> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase20-session01-truthful-capability-baseline/spec.md). # Session Specification **Session ID**: `phase20-session01-truthful-capability-baseline` **Phase**: 20 - Orchestration Actionability Execution **Status**: Complete **Created**: 2026-06-28 **Package**: null **Package Stack**: TypeScript across `packages/protocol`, `apps/server`, and `apps/web` *** ## 1. Session Overview This session corrects command-center capability and action wording before new execution paths are added. The current server registry, guarded-action tests, and docs can treat file approval as an executed capability even though the current file path records audit metadata only and does not mutate repository content. The session also makes queue, campaign, and hero lifecycle UI copy match the current runtime. Queue and campaign paths that only create or transition local records must not use execution verbs, and observed hook-ingested hero sessions must show record-only lifecycle intent until a future managed session controller exists. This is the required first Phase 20 slice because later terminal, Git, campaign, file, and managed-agent sessions depend on a truthful baseline for `unavailable`, `proposal_only`, `approved_not_executing`, and `executor_ready` states. *** ## 2. Objectives 1. Downgrade file executor capability and guarded file approval behavior until a real file mutation manager exists. 2. Replace metadata-only queue and campaign action copy with record-only or tracking wording where no executable payload exists. 3. Replace observed-only hero lifecycle control verbs with record-only intent wording until a managed session controller is attached. 4. Update server, web, and docs tests so future execution slices cannot accidentally restore the false action claims. *** ## 3. Prerequisites ### Required Sessions * [x] `phase19-session06-executor-registry` - Provides the current executor registry and capability surfaces. * [x] `phase19-session08-file-and-git` - Provides file intent and Git workbench posture. * [x] `phase19-session09-heroes-and-lineage` - Provides hero lifecycle and lineage surfaces. * [x] `phase19-session16-ergonomics-and-documentation` - Provides Command Center docs, labels, and validation baseline. ### Required Tools Or Knowledge * Node 26.2.0+ and npm 11.16.0 from `.spec_system/CONVENTIONS.md`. * Vitest for focused server and web tests. * Existing command-center status vocabulary in `packages/protocol/src/orchestrationCommandCenter.ts`. * Current privacy boundary from `.spec_system/CONSIDERATIONS.md` and `.spec_system/SECURITY-COMPLIANCE.md`. ### Environment Requirements * No external credentials, hosted services, Docker, PTY, or provider transfer are required for this session. * Work stays local to the monorepo and must preserve ASCII-only, Unix LF files. *** ## 4. Scope ### In Scope (MVP) * Operators see file executor entries as unavailable or approved-not-executing until real workspace mutation exists - update server registry behavior and tests. * Operators approving guarded file actions receive a non-executing result until a real file adapter exists - use existing guarded-action unavailable/not-executed semantics. * Operators see queue and campaign controls that only transition metadata as record-only or tracking actions - update web copy, reasons, and tests. * Operators see observed hero lifecycle sessions as record-only intent surfaces - update web copy, accessible labels, and tests. * Maintainers get docs and focused tests proving metadata-only controls are labeled and handled truthfully - update API, web, and architecture docs. ### Out Of Scope (Deferred) * Terminal queue execution - Reason: owned by Phase 20 Session 02 after this baseline is validated. * Queue Git execution - Reason: owned by Phase 20 Session 03 after terminal queue contracts exist. * Campaign executable dispatch and DAG recovery - Reason: owned by Phase 20 Sessions 04 and 05. * File mutation and file executor integration - Reason: owned by Phase 20 Sessions 06 and 07. * Managed agent process or PTY lifecycle control - Reason: owned by Phase 20 Session 08. * Container dispatch, template/channel executable intake, and release evidence closeout - Reason: owned by Phase 20 Sessions 09 through 11. *** ## 5. Technical Approach ### Architecture Keep the existing protocol status vocabulary and use it truthfully. The server registry should make file entries non-ready until a real file mutation adapter exists, letting the existing non-ready guarded-action path return compact not-executed or unavailable results. This avoids introducing a new execution contract before Session 02 and Session 06 define executable payloads. On the web, centralize wording in `apps/web/src/lib/commandCenterUi.ts` and let the workbench components render those labels. Queue and campaign buttons can continue to call their current compatibility handlers in this session, but the visible labels and reasons must say record-only or tracking behavior unless the record actually has an executable payload. Docs should describe the current boundary: Git, terminal, and container paths can be real only where their bounded local executor paths pass readiness gates; file paths are audit/proposal state until file mutation ships; remote, Worker, hosted, observed hero, channel, mission, and handoff paths remain non-executing unless later sessions prove otherwise. ### Design Patterns * Protocol-owned vocabulary: Keep shared state names in `packages/protocol` and change behavior/copy around existing statuses. * Manager-owned runtime boundaries: Keep readiness and approval outcomes in server managers instead of route-specific string patches. * Broad-summary/scoped-detail split: Keep raw paths, command text, diffs, file contents, terminal output, and provider payloads out of broad rows and events. * Product-facing copy only: UI labels must describe what the click really does, not future execution intent. *** ## 6. Deliverables ### Files To Create | File | Purpose | Est. Lines | | ---- | ---------------------------------------------------------- | ---------- | | none | No new source files are planned for this baseline session. | 0 | ### Files To Modify | File | Changes | Est. Lines | | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ---------- | | `packages/protocol/src/orchestrationCommandCenter.ts` | Confirm status vocabulary and parser constraints still support truthful non-ready states; update comments only if needed. | \~0-20 | | `apps/server/src/managers/executorRegistry.ts` | Downgrade file executor entries, remove metadata-only execution from file entries, and make repair summaries clear. | \~80 | | `apps/server/tests/executorRegistry.test.ts` | Assert file entries are not executor-ready and file approvals do not execute. | \~80 | | `apps/server/tests/guardedActions.test.ts` | Assert guarded file approval records non-executing state and execution detail is not executed. | \~80 | | `apps/server/tests/commandCenterRoutes.test.ts` | Assert capability and probe routes do not promote file entries to `executor_ready`. | \~40 | | `apps/web/src/lib/commandCenterUi.ts` | Update capability, queue, campaign, and hero lifecycle copy and action availability labels. | \~120 | | `apps/web/src/components/orchestration/QueueWorkbench.tsx` | Render record-only queue action labels and feedback with duplicate-trigger disabled states. | \~40 | | `apps/web/src/components/orchestration/CampaignWorkbench.tsx` | Render truthful campaign action labels and planning-only task copy. | \~40 | | `apps/web/src/components/orchestration/HeroLineageWorkbench.tsx` | Render record-only observed lifecycle buttons and accessible labels. | \~40 | | `apps/web/tests/commandCenterUi.test.ts` | Cover truthful status copy, queue/campaign labels, and observed lifecycle labels. | \~90 | | `apps/web/tests/CommandCenterPanes.test.tsx` | Cover integrated command-center panes for record-only queue and campaign controls. | \~50 | | `apps/web/tests/HeroLineageWorkbench.test.tsx` | Cover observed-only record intent controls and duplicate in-flight states. | \~50 | | `docs/api/README_api.md` | Remove file executor-ready audit execution claims and document non-executing file state. | \~40 | | `docs/api/event-api-hook-contracts.md` | Align command-center REST and WebSocket wording with truthful file and lifecycle states. | \~30 | | `apps/web/README_web.md` | Align web Command Center UX contract with record-only queue/campaign/hero behavior. | \~30 | | `docs/ARCHITECTURE.md` | Align architecture overview with Phase 20 actionability boundaries. | \~20 | *** ## 7. Success Criteria ### Functional Requirements * [ ] File executor capability probes cannot report metadata-only file entries as `executor_ready`. * [ ] Guarded file approval returns non-executing state until a real file mutation adapter is available. * [ ] Queue controls that only transition local metadata do not use `Dispatch` or execution wording. * [ ] Campaign controls and task rows without executable payloads do not claim dispatch or execution. * [ ] Observed-only hero lifecycle controls show record-only intent, not process-control verbs. ### Testing Requirements * [ ] Server tests cover file capability downgrade, guarded file approval, and command-center route probes. * [ ] Web tests cover capability copy, queue/campaign labels, and observed hero lifecycle controls. * [ ] Focused Vitest commands pass for the touched server and web tests. ### Non-Functional Requirements * [ ] Broad rows, route responses, WebSocket frames, docs, and tests avoid raw commands, terminal output, diffs, file contents, provider payloads, tokens, secrets, and broad absolute paths. * [ ] UI controls preserve duplicate-trigger prevention while in-flight. * [ ] Product copy remains local-first and does not imply hosted, remote, Worker, or managed-agent execution. ### Quality Gates * [ ] All files ASCII-encoded * [ ] Unix LF line endings * [ ] Code follows project conventions * [ ] UI surfaces contain product-facing copy only * [ ] `git diff --check` passes *** ## 8. Implementation Notes ### Working Assumptions * Cross-package session scope: The analyzer returned `package: null`, while the Session 01 stub explicitly names `packages/protocol`, `apps/server`, and `apps/web`; this is safe to proceed as `Package: null` because the work is intentionally cross-cutting and all target files are repo-root-relative. * Current queue dispatch route compatibility can remain while visible copy changes: Session 02 owns real queue terminal dispatch and route reshaping, while Session 01 only needs users and tests to stop reading metadata transitions as execution. * Current hero lifecycle rows are observed-only by default: The Phase 20 stub states hook-ingested Claude Code and Codex CLI sessions are observed unless FactionOS created and owns the process or PTY, and no managed controller exists in current source. ### Conflict Resolutions * Docs and tests currently describe file guarded-action adapters as executor-ready for audit metadata, while the Phase 20 PRD requires metadata-only file behavior to be downgraded. Phase 20 wins because it is the active phase and names this as the first required correction. * Existing guarded file tests expect `state: "executed"` for metadata-only approval, while the Session 01 success criteria require a non-executing result. The Session 01 criteria win because current file entries do not mutate workspace content. ### Key Considerations * Do not add executable payload DTOs or coordinator behavior in this session. * Use existing non-ready statuses before adding new protocol vocabulary. * Keep docs and UI wording consistent so later sessions do not reintroduce execution claims through copy. ### Potential Challenges * Some status names are shared across capability and execution concepts; mitigate by updating tests around both capability rows and guarded-action results. * Existing UI helpers may not know whether queue or campaign records have executable payloads yet; mitigate by defaulting metadata-only actions to record/tracking wording until future sessions add payload fields. * Hero lifecycle action labels are currently global by action kind; mitigate by making current observed-only controls explicitly record intent while leaving real control labels for Session 08. ### Relevant Considerations * \[P19] **Executor claims are family-scoped**: File must not be `executor_ready` until file mutation is proved. * \[P19] **Scoped detail stays separate from broad rows**: Raw prompts, diffs, command bodies, terminal output, transcripts, provider payloads, and absolute paths must stay out of broad labels and events. * \[P19] **Channel intake is proposal-first**: The same no-auto-execution posture should shape queue and campaign copy in this baseline. * \[P03-packages/protocol] **Protocol leads cross-package work**: Reuse or confirm shared status vocabulary before server and web changes. * \[P19] **Command-center state is manager-owned**: Capability and approval state should stay in managers and shared helpers, not ad hoc route copy. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Metadata-only paths may still be reachable through duplicate clicks or stale state after labels change. * Broad UI rows or docs may leak scoped execution words, raw local details, or future claims. * Server and web status labels may drift, causing a non-ready capability to appear executable in one surface. *** ## 9. Testing Strategy ### Unit Tests * Update `apps/server/tests/executorRegistry.test.ts` for file capability downgrade and non-ready guarded results. * Update `apps/web/tests/commandCenterUi.test.ts` for capability copy, queue/campaign action labels, and observed lifecycle labels. ### Integration Tests * Update `apps/server/tests/guardedActions.test.ts` so guarded file approval produces non-executing state and bounded execution metadata. * Update `apps/server/tests/commandCenterRoutes.test.ts` so route-level capability snapshots and executor probes do not promote file entries to ready. * Update `apps/web/tests/CommandCenterPanes.test.tsx` and `apps/web/tests/HeroLineageWorkbench.test.tsx` for integrated control labels and in-flight disabled states. ### Runtime Verification * Run focused Vitest coverage for touched server and web files. * Run protocol, server, and web typechecks. * Run `git diff --check` and ASCII/LF verification over changed spec, source, test, and doc files. ### Edge Cases * Missing file executor adapter returns a compact non-executing or unavailable result instead of executed. * Queue or campaign records without executable payloads stay record-only even when their state allows mutation. * Observed-only hero lifecycle actions keep duplicate-trigger prevention and accessible names while avoiding process-control verbs. * Capability summaries with mixed ready and non-ready families use deterministic ordering and truthful aggregate status. *** ## 10. Dependencies ### Other Sessions * Depends on: Phase 19 complete and Phase 20 PRD. * Depended by: `phase20-session02-queue-terminal-execution`, `phase20-session03-queue-git-execution`, `phase20-session04-campaign-executable-dispatch`, `phase20-session06-file-mutation-core`, `phase20-session08-managed-agent-lifecycle-control`, and later release evidence. *** ## Next Steps Run the `implement` workflow step to begin implementation. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase20-session01-truthful-capability-baseline/spec.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.