> 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/phases/phase_20/session_01_truthful_capability_baseline.md). # Session 01: Truthful Capability Baseline **Session ID**: `phase20-session01-truthful-capability-baseline` **Packages**: `packages/protocol`, `apps/server`, `apps/web` **Status**: Not Started **Estimated Tasks**: \~12-25 **Estimated Duration**: 2-4 hours *** ## Objective Stop presenting metadata-only paths as executable orchestration before adding new execution paths. *** ## Scope ### In Scope (MVP) * Downgrade file executor readiness until real file mutation exists. * Update guarded file approval behavior so metadata-only approvals do not report executed. * Split queue, campaign, file, and hero UI copy between real actions and record-only state changes. * Update capability wording for unavailable, proposal-only, approved-not-executing, and executor-ready states. * Add or update server and web tests proving metadata-only controls are labeled and handled truthfully. ### Out of Scope * Adding new runtime execution behavior. * Implementing file mutation, queue terminal execution, Git dispatch, or managed agent control. *** ## Prerequisites * [ ] Phase 20 PRD reviewed. * [ ] Current command-center capability and action-label tests identified. *** ## Deliverables 1. Registry, route, and UI changes that prevent false `executor_ready`, `Dispatch`, `Execute`, `Apply`, `Edit`, and `Stop` claims. 2. Server and web tests proving metadata-only controls are labeled and handled truthfully. *** ## Success Criteria * [ ] File executor probe cannot promote metadata-only file capabilities to `executor_ready`. * [ ] Guarded file approval returns a non-executing state until a real adapter is available. * [ ] Queue and campaign controls without executable payloads do not use dispatch or execution verbs. * [ ] Observed-only hero sessions show record-only controls, not process-control verbs. * [ ] Relevant server and web tests pass. *** ## Folded Source Detail ### Product Outcome Before any new execution path is added, users must not see production action verbs or `executor_ready` states for paths that only record metadata, proposals, previews, approvals, or audit decisions. ### Source Reality To Preserve * `apps/server/src/managers/taskQueue.ts` currently implements queue dispatch as a state transition to `in_progress`; this is tracking, not doing. * Campaign dispatch currently creates or updates campaign, task, and queue state; it does not hand off to terminal, Git, container, file, or agent execution. * `apps/server/src/managers/executorRegistry.ts` can promote file executor entries to `executor_ready` even though the file executor records bounded metadata only and does not mutate repository content. * Guarded action approval has the right shape, but only Git, terminal when PTY is ready, and containers when runtime probes pass have real execution paths. * `apps/server/src/managers/heroLifecycleManager.ts` records lifecycle intents; hook-ingested Claude Code and Codex CLI sessions are observed sessions unless FactionOS created and owns the process or PTY. * `apps/web/src/lib/commandCenterUi.ts`, `QueueWorkbench.tsx`, `CampaignWorkbench.tsx`, and `HeroLineageWorkbench.tsx` contain visible labels and availability text that must match real behavior. ### Required Changes * Downgrade file executor registry entries from `executor_ready` to `approved_not_executing` or `unavailable` until real file mutation exists. * Update tests that currently expect `capability_file_file_edit` to probe as `executor_ready`. * Update guarded file approval tests that currently expect `state: "executed"` for metadata-only file approval. * Change queue and campaign action copy when no executable payload exists: `Start tracking` or `Queue for review`, not `Dispatch`. * Change hero lifecycle buttons to make visible intent truthful for observed-only sessions, for example `Record message intent`, unless a managed session controller is attached and ready. * Capability matrix copy must distinguish `Unavailable`, `Proposal only`, `Approved, not executing`, and `Executor ready`. ### Acceptance Tests From Findings * `apps/server/tests/executorRegistry.test.ts` proves file executor entries are not ready until a real file adapter is injected. * `apps/server/tests/commandCenterRoutes.test.ts` proves executor probe does not promote metadata-only file entries to `executor_ready`. * `apps/web/tests/commandCenterUi.test.ts` proves queue and campaign labels do not say `Dispatch` for metadata-only records. * `apps/web/tests/CommandCenterPanes.test.tsx` proves hero lifecycle controls communicate record-only behavior when no managed session is ready. ### Delivery Guardrail This session deliberately does not add runtime execution. It succeeds only when metadata-only behavior is visibly and programmatically truthful before the later vertical slices add executable paths. --- # 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/phases/phase_20/session_01_truthful_capability_baseline.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.