From d31437a4fb255c1e307bbb70ee9513cc1e0bdf4c Mon Sep 17 00:00:00 2001 From: thePR0M3TH3AN Date: Sun, 27 Sep 2026 23:38:55 -0400 Subject: [PATCH] Clarify hierarchy growth proposal pathway --- docs/ARCHITECTURE_DECISIONS.md | 25 +++++---- docs/PORTABLE_AGENT_FLEET_SPEC.md | 54 +++++++++++++++++++ docs/TODO.md | 9 ++-- ...grity-note-2026-09-27-portable-kernel.yaml | 2 +- test/fleet/product-surface.test.mjs | 6 ++- 5 files changed, 80 insertions(+), 16 deletions(-) diff --git a/docs/ARCHITECTURE_DECISIONS.md b/docs/ARCHITECTURE_DECISIONS.md index 0cc9a84..c0a45ac 100644 --- a/docs/ARCHITECTURE_DECISIONS.md +++ b/docs/ARCHITECTURE_DECISIONS.md @@ -122,9 +122,10 @@ The current organization model has one required `session-manager` identity and flat implementation domains. TORCH's Fleet-evolution service can propose specialist additions, retirements, and domain-boundary changes, but it does not yet model Program Directors, Fleet Operations, multiple levels of domain leads, -or role promotion as durable authority-bearing relationships. Do not represent -that capability as implemented or encode COMBATRIG's proposed departments as -the default organization. +or role promotion as durable authority-bearing relationships. Its current +read-only assessment does not yet produce owner-facing hierarchy proposals. +Do not represent that capability as implemented or encode COMBATRIG's proposed +departments as the default organization. The target design is an owner-approved, versioned organization graph generated from each project's repository and specification. It separates @@ -137,16 +138,18 @@ program and domain documents are summaries, not task queues. Before implementation, a follow-up decision and acceptance scenarios must define role schemas and permissions, Session Manager compatibility, how the -Session Architect proposes measured hierarchy changes, owner approval, safe -promotion/reassignment, active-task and branch preservation, staged -provisioning, startup/wind-down order, rollback, and hierarchy-aware doctor and -console views. A proposed lead must own a concrete integrated outcome, and -headcount alone must never trigger an added management layer. +Fleet assessment detects sustained coordination pressure and deduplicates +owner-facing proposals, how the Session Architect compares role changes with +process or specialist changes, owner approval, safe promotion/reassignment, +active-task and branch preservation, staged provisioning, pilot measures, +startup/wind-down order, rollback, and hierarchy-aware doctor and console +views. A proposed lead must own a concrete integrated outcome, and headcount +alone must never trigger an added management layer. ## Consequences These decisions keep the first usable release local-first and provider- independent. They also make current boundaries explicit: repository moves, -multi-machine control, non-Linux persistent launchers, and published update -channels, and multi-level organization management are unavailable rather than -silently approximated. +multi-machine control, non-Linux persistent launchers, published update +channels, and multi-level organization management remain unavailable rather +than silently approximated. diff --git a/docs/PORTABLE_AGENT_FLEET_SPEC.md b/docs/PORTABLE_AGENT_FLEET_SPEC.md index 10c9422..2311b15 100644 --- a/docs/PORTABLE_AGENT_FLEET_SPEC.md +++ b/docs/PORTABLE_AGENT_FLEET_SPEC.md @@ -882,6 +882,53 @@ limits, affected identities and relationships, expected context or delivery benefit, and the costs or risks of adding management. The change SHOULD begin as a bounded pilot with review criteria and a way to reverse it. +The growth pathway MUST be an explicit, durable lifecycle: + +```text +observe coordination evidence + ↓ +assess whether the cause is structural and recurring + ↓ +compare process changes, specialist changes, and coordination-role options + ↓ +submit an owner-facing organization proposal + ↓ +owner decision → migration plan → bounded pilot + ↓ +measure results → adopt, revise, or reverse +``` + +The Session Manager SHOULD run the read-only Fleet assessment at startup and +when recurring coordination friction appears. TORCH SHOULD evaluate evidence +over a project-configured observation window and require a sustained pattern +or multiple independent signals; a single large task or temporary incident +MUST NOT trigger a management proposal. Useful signals include repeated work +across the same domains, coordination requests and handoffs, time waiting for +cross-domain decisions, dependency-related blocked time, rework from late +integration, and the dispatcher repeatedly switching among unrelated areas. +Where measurements are unavailable, the proposal MUST label the evidence as +qualitative rather than imply measured improvement. + +Before proposing a lead, the Session Manager MUST consider whether a clearer +interface, direct peer agreement, backlog sequencing, a new implementation +specialist, or promotion of an existing specialist would address the cause +with less coordination cost. A hierarchy proposal MUST reach the owner through +the project's single owner-facing coordination role and include: + +- the recurring problem and linked evidence, dates, and observation window; +- the integrated outcome and candidate role responsibilities; +- the domains or specialists it would coordinate and its explicit authority + limits; +- alternatives considered, including no change and promotion of an existing + identity; +- expected benefits, added context/meeting/routing cost, and pilot duration; +- success and stop criteria, baseline measures, and the reversal plan. + +No repeated assessment should create or repeatedly resend the same proposal. +TORCH SHOULD deduplicate against open organization proposals and present only +material updates to the owner. The owner may approve, reject, or defer it; a +recommendation alone never changes roles, authority, routing, or sessions. + The Session Manager or a designated organization planner MAY propose a change, but MUST NOT activate it unilaterally. The owner approves the intended organization. Before activation, TORCH MUST produce a reviewable migration @@ -893,6 +940,13 @@ session provisioning, and runtime launch are separate steps; runtime launch remains an explicit action. Existing specialist-to-specialist communication and backlog history MUST survive a hierarchy change. +The pilot MUST start with the smallest affected group and retain a way to +continue under the prior organization. At the end of its review window, the +owner-facing role receives a comparison with the baseline using the proposal's +success criteria. TORCH may recommend adoption, adjustment, or reversal; only +the owner approves the next organizational change. A successful pilot is not +permission to add unrelated layers automatically. + On wind-down, coordination roles SHOULD record concise domain or program state, while Fleet Operations preserves session and restart state. This reporting supplements the backlog and does not replace it. diff --git a/docs/TODO.md b/docs/TODO.md index 4ee767a..7ac11b7 100644 --- a/docs/TODO.md +++ b/docs/TODO.md @@ -32,9 +32,12 @@ passed 61/61 with lint, syntax checks, and diff hygiene also passing. ## Planned architecture follow-up - [ ] Implement ADR-011: versioned, project-specific organization graphs and - owner-approved hierarchy changes. Add a gated role schema and migration plan - before enabling Program Directors, Fleet Operations roles, domain leads, or - specialist promotion. Preserve direct peer communication, single backlog, + owner-approved hierarchy changes. Extend Fleet assessment to detect + sustained coordination pressure, distinguish role needs from process or + specialist changes, and create deduplicated proposals for the owner. Then add + a gated role schema, impact plan, promotion path, bounded pilot, success/stop + measures, and reversal before enabling Program Directors, Fleet Operations + roles, or domain leads. Preserve direct peer communication, single backlog, implementation ownership, active work, and explicit runtime launch. Do not copy COMBATRIG's proposed hierarchy as the default. diff --git a/reports/test-audit/test-integrity-note-2026-09-27-portable-kernel.yaml b/reports/test-audit/test-integrity-note-2026-09-27-portable-kernel.yaml index 0641da5..8ebf3ee 100644 --- a/reports/test-audit/test-integrity-note-2026-09-27-portable-kernel.yaml +++ b/reports/test-audit/test-integrity-note-2026-09-27-portable-kernel.yaml @@ -226,7 +226,7 @@ test_integrity_note: - id: SCN-architecture-decisions given: the eleven implementation decisions required by the portable Fleet specification when: the repository architecture ledger is inspected - then: implemented choices are accepted explicitly, unavailable capabilities including multi-level hierarchy management remain fail-closed gates, and COMBATRIG roles are not treated as TORCH defaults + then: implemented choices are accepted explicitly, unavailable capabilities including a measured, deduplicated hierarchy proposal lifecycle remain fail-closed gates, and COMBATRIG roles are not treated as TORCH defaults - id: SCN-console-readonly given: an installed Fleet without an initialized control-plane database when: the observation API and local HTTP console are requested diff --git a/test/fleet/product-surface.test.mjs b/test/fleet/product-surface.test.mjs index 5227b11..0498d68 100644 --- a/test/fleet/product-surface.test.mjs +++ b/test/fleet/product-surface.test.mjs @@ -54,11 +54,15 @@ test('SCN-architecture-decisions: every specification decision has an explicit a assert.match(decisions, /MCP over\s+stdio/); assert.match(decisions, /exact Git commit and the exact hash/); assert.match(decisions, /Project-specific coordination hierarchy[\s\S]*\*\*Status:\*\* gated/); - assert.match(decisions, /headcount alone must never trigger an added management layer/); + assert.match(decisions, /headcount\s+alone must never trigger an added management layer/); const spec = readFileSync(new URL('../../docs/PORTABLE_AGENT_FLEET_SPEC.md', import.meta.url), 'utf8'); assert.match(spec, /Optional coordination hierarchy/); assert.match(spec, /existing single backlog remains the task ledger and queue/); assert.match(spec, /COMBATRIG example, not a default organization/); + assert.match(spec, /The growth pathway MUST be an explicit, durable lifecycle/); + assert.match(spec, /No repeated assessment should create or repeatedly resend the same proposal/); + assert.match(spec, /owner-facing organization proposal/); + assert.match(spec, /bounded pilot/); }); test('SCN-console-readonly: HTTP console serves fixed assets and observes an installed fleet without mutation', async (context) => {