@iowarp/clio-coder 0.4.1 → 0.4.3

package/docs/process/documentation-coverage.md

@@ -0,0 +1,100 @@
+# Documentation coverage and source-alignment audit
+
+> **Visual blueprint:** The source checkout includes the complete
+> [Documentation coverage and source-alignment audit visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/documentation_coverage_blueprint.html).
+
+This is the page-level audit for Clio Coder 0.4.2. The source comparison is
+pinned to commit `ff56ea3e`. A disagreement means that a current factual claim,
+default, identifier, path, schema, or command differs from the implementation at
+that commit. Historical records are evaluated as dated evidence and are not
+treated as current operator guidance.
+
+## Headline
+
+- Markdown pages audited: **51**.
+- Dedicated HTML blueprints now present: **51**.
+- Pages without a blueprint: **0**. Every Markdown page has one visual
+  counterpart, so there are no exception reasons to record.
+- Pages with one or more source disagreements at `ff56ea3e`: **42**.
+- Pages with no source disagreement found at `ff56ea3e`: **9**.
+- Source disagreements corrected in Markdown: **42 of 42 affected pages**.
+- HTML blueprints synchronized from the corrected Markdown: **51 of 51**.
+
+At audit time, 40 blueprint files covered 40 pages because
+`prompt-envelope-and-tools.md` had two HTML implementations while
+`proactive-memory.md` shared the evidence and memory blueprint. The table below
+preserves that audit-time state.
+
+## Page audit
+
+| Markdown page | Primary source references | HTML blueprint at audit time | Disagreements with `ff56ea3e` |
+| --- | --- | --- | --- |
+| `README.md` | `package.json`; `src/cli/index.ts`; `src/cli/docs.ts`; `src/cli/doctor.ts`; CLI smoke tests | No dedicated blueprint. `html/index.html` is the landing page. | None found. |
+| `architecture/acp.md` | `src/engine/acp/**`; `src/cli/acp.ts`; `src/entry/orchestrator.ts` | `html/acp_blueprint.html` | Source line pointers and the log prefix are stale. The event and metadata allowlists omit dispatch events and agent attribution fields. Dispatch events can carry a bounded task preview despite the claimed prose embargo. Git is classified as `other`, while dispatch, steer, and monitor also have mappings; five current canonical tools also fall back to `other` and are absent from the table. Tool aliases and the policy source use the `clio-coder-*` namespace, not `clio-*`. The tool mediator governs outbound ACP delegation, not the hosted ACP server's resumable permission bridge. |
+| `architecture/alcf-provider.md` | `src/domains/providers/runtimes/cloud/alcf.ts`; `src/engine/alcf-oauth.ts`; `src/engine/apis/openai-completions.ts` | `html/alcf_blueprint.html` | The runtime stores `model.clioCoder.chatTemplateKwargsUnsupported`, but the request adapter reads the legacy `model.clio` location. The documented omission therefore is not current runtime behavior. |
+| `architecture/architecture.md` | `tests/boundaries/check-boundaries.ts`; `src/core/domain-loader.ts`; `src/entry/orchestrator.ts`; `src/engine/**`; `src/tools/bootstrap.ts`; `src/worker/**` | `html/architecture_blueprint.html` | The boundary checker has six rules, not five. The instant-shell import-graph test no longer exists. Dispatch is eagerly created by tool bootstrap and imports its runner directly, not through `lazy-tool`. The loaded-domain table omits toolchain and optional mux, the feature inventory omits the CLI-owned `user-tasks` domain, and several non-`DomainModule` areas are mislabeled as loaded modules. |
+| `architecture/artifact-placement.md` | `src/core/artifact-paths.ts`; `src/core/xdg.ts`; artifact stores under `src/domains/**`; `src/tools/artifact.ts` | `html/artifact_placement_blueprint.html` | `.clio-coder/test-scratch` has no source owner; scratch output lives below the state directory. `.clio-coder/` becomes ignored only when bootstrap writes the rule. Re-including children below an ignored parent does not implement the documented Git policy; deliberate assets require an explicit force-add. |
+| `architecture/artifact-versions.md` | `src/engine/session.ts`; `src/domains/session/migrations/**`; `src/domains/dispatch/receipt-integrity.ts`; dispatch state stores; `src/domains/eval/schema/**`; `src/domains/observability/trace-store.ts`; `src/domains/user-tasks/store.ts` | `html/artifact_versions_blueprint.html` | Sessions are format 4 and only format 3 migrates to 4. Eval artifacts live below the data directory and use `clio-coder.eval.*` schema identifiers; `EVAL_ARTIFACT_VERSION` no longer exists. Fleet contracts are Markdown in tiered roots, not YAML. A malformed checkout lease fails closed. Trace logs use `[clio-coder:trace]`, while direct readers reject schema drift. Receipt pseudocode names obsolete APIs and types and understates v20 verification. Out-of-turn usage also records prewarm and background memory. The versioned user-tasks file is omitted, while not every other persisted row is versioned. The page incorrectly claims an exhaustive registry; several internal stores are absent. Runtime-descriptor, execution-plan, eval-verdict, capacity-state, and library-pin handling are misstated, and several numeric source pointers are stale. |
+| `guide/built-in-agents.md` | `src/domains/agents/**`; `src/domains/dispatch/**`; `src/worker/**` | `html/agents_blueprint.html` | Discovery omits enabled extension roots and the reserved `auto` identifier. The compact prompt catalog excludes internal recipes and handles oracle separately. Name, description, budget, and other recipe fields are required, so the example recipe is invalid. Audience also permits `custom`. Adaptive routing uses `fleet.adaptiveRouting.agentRoles`. Event names use `clio_coder_*`. Fleet contract v5 is current. The `context-bootstrap` row grants a `ledger` tool its shipped recipe does not carry. |
+| `architecture/capacity-and-scheduling.md` | `src/domains/scheduling/**`; `src/domains/dispatch/capacity-lease.ts`; `src/domains/dispatch/admission.ts`; `src/domains/dispatch/reservation-store.ts`; provider capacity probes | `html/capacity_scheduling_blueprint.html` | The lease schema omits the optional host field. Worker protocol heartbeats run each second, while durable capacity leases renew every ten seconds. Endpoint saturation can queue through the lease controller rather than always refusing immediately. The reference mini endpoint has four llama.cpp slots, not the stated one-slot common case. Numeric source pointers are stale, and lease expiry is described without the live-process identity exception. |
+| `guide/commands-and-modes.md` | `src/cli/**`; `src/interactive/slash-commands.ts`; `src/domains/dispatch/**`; `src/tools/**` | `html/commands_blueprint.html` | Policy and event identifiers use `clio-coder-policy` and `clio_coder_*`. The interop boot prompt is not quoted accurately. The built-in-agent list omits the operator-only oracle. Memory settings use `context.memory.enabled`, not `memory.intervention.enabled`. |
+| `history/config-knobs-audit.md` | Historical snapshot of `src/core/config.ts`, runtime settings, and worker budgets | `html/config_knobs_audit_blueprint.html` | None found in its dated scope. Retired variables such as `CLIO_CODER_RESIDENCY` are historical evidence, not live guidance. |
+| `guide/configuration-and-targets.md` | `src/core/defaults.ts`; `src/core/config.ts`; `src/domains/providers/**`; `src/cli/configure.ts`; `src/cli/targets.ts`; `src/cli/models.ts`; `src/cli/auth.ts` | `html/configuration_blueprint.html` | The six safety limit leaves no longer have environment overrides. Policy and managed-file identifiers use the `clio-coder-*` namespace. The external-agent example uses retired `delegation.agents` rather than `integrations.externalAgents.entries`. |
+| `guide/configuration-reference.md` | `src/core/defaults.ts`; `src/core/config.ts`; all CLI parsers; tool schemas; agent recipe schema; local model catalogs | No; parity gap. | Several YAML string values named `off` were rendered as Boolean `False`, and environment defaults were rendered as booleans instead of presence semantics. `fleet.concurrency` defaults to the constant 4, not derived host capacity. Recipe precedence omits extensions and incorrectly permits project overrides of built-ins. `workers.rosters` is retired; the current key is `fleet.rosters`. |
+| `architecture/context-engine.md` | `src/domains/context/**`; `src/domains/session/**`; `src/domains/providers/**`; `src/domains/prompts/preload.ts`; interactive context and prewarm modules | `html/context_blueprint.html` | Context-window precedence and the unknown fallback are incomplete. The warning boundary is 128,000 while the desired floor is 131,072. Compaction and prewarm examples use v1 keys; `excludeLastTurns` is retired. A replay evidence path was deleted. The reference endpoint describes an obsolete one-slot Qwen route instead of mini with Ornith, four slots, and 262,144 context per slot. Codewiki frontmatter omits empty optional fields rather than always serializing seven. |
+| `architecture/context-working-set.md` | `src/domains/context/working-set/**`; `src/domains/session/**`; `src/interactive/turn-context.ts`; context CLI and tool modules | No; parity gap. | Settings use `context.compaction.threshold`, and `excludeLastTurns` is retired. `age-horizon` does not reproduce legacy selection because a minimum token floor was added. Recall never guesses the nearest reference; invalid-reference errors do not list candidates, while other errors list at most eight. Deleted replay evidence is cited as if shipped. |
+| `process/development-pipeline.md` | `package.json`; `scripts/check-hygiene.ts`; `.github/**`; `tests/**` | No; parity gap. | The width-matrix test, shard scripts, shard weights, and load harness do not exist. The test command now invokes contract and smoke tests directly and has no documented list, shard, serial lane, or `CLIO_TEST_CONCURRENCY` behavior. A named wire-capture fixture suite is no longer present. |
+| `architecture/dispatch-architecture-rationale.md` | `src/domains/dispatch/**`; `tests/boundaries/check-boundaries.ts` | `html/dispatch_rationale_blueprint.html` | File, barrel-line, and cross-domain import counts are stale. Receipt integrity is v20, not v16. The boundary checker has six rules, not five. |
+| `architecture/dispatch-typed-intent.md` | `src/domains/dispatch/intent*.ts`; `src/domains/dispatch/path-scope.ts`; `src/tools/dispatch-*.ts`; dispatch admission tests | No; parity gap. | Exact `.` and `./` roots normalize to repository root. Expected outputs use a looser normalizer than the three scope fields. `{check:"none"}` resolves a verifier actually named `none`. Absent or partial intent warnings are classified but deliberately not published in production. No-intent judge and reviewer requests can only hit legacy inference errors. Two legacy reason codes have no current producer. Prose-path reporting is extension-filtered and capped. Output-versus-write-root and legacy contradiction checks run only when both relevant lists are nonempty. A cited compatibility test was deleted. |
+| `process/documentation-coverage.md` | `src/**`; `tests/**`; `docs/html/**` | No; parity gap. | None found in the former ownership claims, but the former page did not provide the required page-level source, blueprint, and drift audit. |
+| `process/documentation-guide.md` | `src/**`; `tests/**`; documentation and HTML inventories | `html/documentation_blueprint.html` | The map says 20 tools, receipt v16, 45 glossary terms, six trace commands, and nine artifact schemas; current values are 21 canonical tools, receipt v20, 50 glossary terms, eight trace commands, and 25 registry rows. Several pages with standalone HTML are described as lacking it. Nine existing Markdown pages are absent from the map. |
+| `guide/environment-variables.md` | `src/core/guardrails.ts`; `src/core/xdg.ts`; all `process.env` reads; hygiene inventory | `html/environment_blueprint.html` | The page is complete for product `CLIO_CODER_*` variables plus `NO_COLOR`, not for every environment variable read by source. It omits standard directory, editor, terminal, remote-session, multiplexer, text-width, timezone, CI, Ollama capacity, and dynamic credential variable families. |
+| `process/eval-runner.md` | `src/domains/eval/**`; `src/cli/eval.ts`; eval boundary and schema tests | `html/eval_blueprint.html` | Canonical runner kind is `clio-coder-run`, schema IDs use `clio-coder.eval.*`, and the artifact field is `clioCoder`; the old forms are compatibility inputs only. The command list omits `eval inventory --json`, and the schema reference omits current agent, autonomy, cost, workspace setup, and observation fields. Some threshold-file failures exit 1 rather than 2. The mini baseline has Ornith, four slots, 262,144 context per slot, and `thinking: off`. |
+| `process/evals-internal.md` | `src/domains/eval/**`; `evals/**` | `html/evals_internal_blueprint.html` | Examples use legacy `clio.eval.behavior.v1` and `clio-run`; canonical identifiers are `clio-coder.eval.behavior.v1` and `clio-coder-run`. |
+| `architecture/evidence-and-memory.md` | `src/domains/evidence/**`; `src/domains/memory/**`; `src/cli/evidence.ts`; `src/cli/memory.ts`; receipt integrity | `html/memory_blueprint.html` | The evidence vocabulary has 29 tags, not 25. Current receipt integrity is v20; older seals are retired rather than all being invalid. The exact not-found output and CLI inventory are incomplete. Forensic classification explicitly forbids task prose as causal evidence. |
+| `process/evolution.md` | `src/domains/evolution/**`; `src/cli/evolve.ts` | `html/evolution_blueprint.html` | None found. |
+| `guide/exit-codes-and-output.md` | `src/cli/**`; `src/entry/**`; CLI smoke tests | `html/exit_codes_blueprint.html` | The JSON event table is described too broadly; full mode can pass additional `clio_coder_*` tool, permission, and plan frames. Core process exit codes are correct. |
+| `guide/extensions-and-sharing.md` | `src/domains/extensions/**`; `src/domains/resources/**`; `src/domains/share/**`; extension and share CLIs | `html/extensions_blueprint.html` | Extensions discover skills, prompts, agents, fleets, and reserved themes, not only prompts and skills. Judge eval arms are not full-auto. Share archives use `clio-coder-share-archive`, `clio-coder.share.v1`, and `clioCoderVersion`; old names are compatibility inputs. The exported settings fragment contains current v2 leaves rather than the documented old scope. |
+| `process/fleet-demo-runbook.md` | `src/domains/dispatch/**`; `src/domains/scheduling/**`; `src/cli/doctor.ts` | No; parity gap. | Current receipts use integrity v20, not v16, and older versions are retired rather than universally failing verification. |
+| `guide/fleet-dispatch.md` | `src/domains/dispatch/**`; `src/domains/scheduling/**`; dispatch tools | `html/fleet_dispatch_blueprint.html` | Current receipts use v20, not v19. Older receipts are retired and never read as evidence. Tool expansion provenance uses `clio-coder.tool.expand`, not `clio.tool.expand`. Agent-ledger citations point into the former dispatch monolith rather than `dispatch-runner.ts`. |
+| `process/git-commit-provenance.md` | `src/core/commit-attribution.ts`; `src/core/git-commit-attribution.ts`; `src/core/defaults.ts`; dispatch attribution tests | No; parity gap. | Canonical configuration is `integrations.git.commitAttribution`; `attribution.gitCommits` is migration-only. Commit trailers recognize and emit `receipt-v20`, not v19. |
+| `guide/glossary.md` | Owning types in `src/domains/dispatch/**`, `src/domains/session/**`, `src/domains/context/**`, and `src/tools/**` | `html/glossary_blueprint.html` | Receipt integrity is v20. Dispatch run and session IDs are 12-character random base36 identifiers, while session turn and entry IDs use UUIDv7. Route candidates contain more identity and policy fields than the four-field definition. Council is a current topology. `internal` is a dispatch request origin, not a worker run origin. Context ledger buckets are incomplete. |
+| `guide/installation-and-lifecycle.md` | `src/cli/upgrade.ts`; `src/cli/doctor.ts`; `src/cli/reset.ts`; `src/cli/uninstall.ts`; `src/domains/lifecycle/**`; `src/core/xdg.ts` | `html/lifecycle_blueprint.html` | Install metadata omits `repairedAt` and overgeneralizes preexisting-home detection beyond config, data, and state. The upgrade section presents a stale 0.3.x sequence as current and claims one migration, while the current registry has five migrations and 0.4.2 emits a generic notice. |
+| `architecture/middleware-and-components.md` | `src/domains/components/**`; `src/domains/middleware/**`; `src/cli/components.ts`; orchestrator registration | `html/middleware_blueprint.html` | Memory middleware uses the v2 `context.memory.*` settings, not `memory.intervention.*`. Its row omits four hooks and incorrectly places background model work directly at every tool cadence. The built-in registration table omits `observer.marketplace-offer`. |
+| `architecture/model-catalog.md` | `src/domains/providers/catalog.ts`; `src/domains/providers/models/**`; provider probes and capability resolution; model CLI | `html/models_blueprint.html` | The Qwen3.8 sample disagrees with the bundled entry on maximum output tokens, vision, thinking mechanism, and sampler temperature. The page omits the default chat thinking level of `low`. Reference topology should identify mini as the four-slot Ornith llama.cpp route and dynamo as the Qwen3.8 LM Studio chat route. |
+| `architecture/observability.md` | `src/domains/observability/**`; `src/domains/evidence/**`; `src/core/bus-events.ts`; `src/interactive/view/**` | `html/observability_blueprint.html` | Receipt integrity references use v19 instead of v20. The completion-event sample has a nonexistent `status` field and omits current outcome fields. The named dynamo sample identifies the wrong served model; the reference chat model is `qwen3.8-27b-dynamo`, while the dispatched-worker example belongs on mini with Ornith. |
+| `process/performance-methodology.md` | `src/interactive/render-trace.ts`; `src/interactive/interactive-shell.ts`; terminal lease and pacing modules; current smoke tests | No; parity gap. | Two cited render tests were deleted, `CLIO_CODER_PERF_REPORT` no longer exists, and the boot trace prefix changed to `[clio-coder:boot]`. The documented commands, graph and V8 proofs, and numeric reports belong to retired harnesses and cannot be reproduced by the current suite; installed-package coverage is now narrower. |
+| `architecture/pi-boundary.md` | `src/engine/ai.ts`; `src/engine/api-registry.ts`; `src/engine/provider-payload.ts`; `src/interactive/chat-loop.ts`; engine lifecycle tests | `html/pi_boundary_blueprint.html` | The current boundary row still names deleted `src/tools/string-enum.ts` as a live adapter instead of locating the Pi re-export only in `src/engine/ai.ts`. |
+| `guide/proactive-memory.md` | `src/domains/memory/**`; `src/domains/middleware/memory-intervention.ts`; `src/core/defaults.ts`; `src/interactive/memory-overlay.ts` | Shared `html/memory_blueprint.html` | Canonical v2 settings are `context.memory.enabled`, `cadenceToolCalls`, `trajectorySteps`, `maxOutputTokens`, `timeoutMs`, `target`, and `model`. Defaults are true, 10, 8, 2,000, 60,000, null, and null. Retired `memory.intervention.*` and background keys, 400-token and 30-second defaults, and related cost claims are stale. The reference topology names a fictitious node and one-slot route instead of mini and dynamo. A cited proactive-memory eval test was deleted, while the active exported harness now lacks maintained direct test coverage. Measurement tables conflict with one another and are not identified as dated external evidence. `qwopus` is cataloged, not selected as a shipped default. |
+| `architecture/prompt-envelope-and-tools.md` | `src/domains/prompts/compiler.ts`; `src/interactive/chat-loop.ts`; `src/core/tool-names.ts`; `src/tools/registry.ts`; `src/tools/agent-tools.ts` | `html/tools_blueprint.html`; a second prompt-envelope implementation was a duplicate and was deleted in the parity pass | The compile cache key omits several current identity fields and tool-schema bytes. There are 21 canonical tools, not 20, and the minimal and science profiles include ledger. Pane exposure is also conditional. Default compaction first performs non-destructive working-set eviction; destructive masking is legacy-only behind `CLIO_CODER_LEGACY_MASK=1`. The exhaustive size-policy description omits ledger and panes. A steering event still uses the retired `clio_*` namespace. |
+| `architecture/provider-adapter-cookbook.md` | `src/domains/providers/registry.ts`; `src/domains/providers/types/runtime-descriptor.ts`; engine provider adapters | `html/provider_adapter_blueprint.html` | `TargetDescriptor` carries auth metadata rather than an API key. The reasoning cache belongs to the providers domain, not a session ledger. Credential resolution and infill binding do not occur in `synthesizeModel`. The thinking mechanism table lists wire/runtime formats rather than the actual mechanism enum. The cited `thinking-runtime.test.ts` was deleted; current off-wire coverage is narrower. |
+| `history/release-cut-checklist.md` | `scripts/check-release.mjs`; package smoke tests; workflows; `package.json` | No; parity gap. | None found in its explicitly historical v0.4.1 scope. |
+| `guide/resource-library.md` | `src/domains/resources/library.ts`; `src/cli/library.ts`; Skills Hub integration | No; parity gap. | None found. |
+| `architecture/safety-model.md` | `src/domains/safety/**`; `src/tools/registry.ts`; `src/tools/policy.ts`; `src/entry/orchestrator.ts`; dispatch write boundaries | `html/safety_blueprint.html` | Saved autonomy is `safety.autonomy`, not a top-level `autonomy` leaf. The canonical tool surface has 21 entries and the table omits ledger and panes, whose registration is conditional. Permission events and ACP governance use retired `clio_*` and `clio-policy` names. |
+| `process/scientific-validation.md` | `src/domains/safety/rigor.ts`; `src/domains/safety/finish-contract.ts`; verification authoring code | `html/validation_blueprint.html` | None found. |
+| `architecture/session-lifecycle.md` | `src/engine/session.ts`; `src/domains/session/**` | `html/session_lifecycle_blueprint.html` | Current session format is 4. Format 3 migrates additively to 4, while versions below 3 and above 4 are rejected. The example metadata header still uses version 3 and the legacy `clioVersion` field; compatibility prose says every older session is refused. |
+| `guide/skills-marketplace.md` | `src/interactive/overlays/skills-hub.ts`; `src/domains/resources/skills/marketplace.ts` | `html/skills_blueprint.html` | None found. |
+| `architecture/time-conventions.md` | `src/interactive/format-time.ts`; dispatch capacity and scheduling modules; `src/core/state-file-lock.ts`; receipt and session stores | `html/time_conventions_blueprint.html` | In-process spans use either `performance.now()` or `hrtime.bigint()`, while persisted and cross-process deadlines use wall time. Not every clock has an injection seam or a global harness clock. Three cited source or test paths do not exist, and the agent-ledger path is wrong. |
+| `guide/tool-usage.md` | `src/tools/agent-tools.ts`; `src/tools/registry.ts`; `src/tools/dispatch-arguments.ts`; per-tool implementations | `html/tool_usage_blueprint.html` | Dispatch rejects per-item `agent_id`, top-level `failover`, and top-level `allowed_candidates`; routing policy belongs below `routing`. Receipt examples use v19 rather than v20. Ledger and panes are missing from the reference. The canonical OBSERVE plane has seven tools, although only six use the shared observation envelope. Docs corpus wording assumes a flat `docs/*.md` directory. Several cited dispatch, safety, and scheduler test paths were deleted. |
+| `architecture/trace-store.md` | `src/cli/trace.ts`; `src/domains/observability/trace-store.ts` | `html/trace_blueprint.html` | None found. |
+| `guide/troubleshooting.md` | `src/core/**`; `src/cli/**`; `src/domains/**`; exact error strings | `html/troubleshooting_blueprint.html` | The local model catalog path is `src/domains/providers/models/local-models/clio-coder-local-coding-targets.yaml`, not the former `clio-local-coding-targets.yaml`. |
+| `architecture/tui-design.md` | `src/interactive/theme/tokens.ts`; `src/interactive/theme/glyphs.ts`; interactive renderer and view modules | `html/tui_design_blueprint.html` | The cited `tests/contracts/usage-vocabulary.test.ts` no longer exists. |
+| `architecture/worker-dispatch-mechanics.md` | `src/worker/**`; dispatch receipt, worker spec, heartbeat, and failure classification modules | `html/worker_dispatch_blueprint.html` | Receipt integrity is v20, not v19. A pre-v20 seal is retired and excluded from evidence rather than treated as a current invalid seal. Steering and permission events use the `clio_coder_*` namespace. The detailed retry-acceptance table cites contract files that no longer exist. |
+
+## Blueprint disposition
+
+The eleven audit-time gaps now have dedicated blueprints: the documentation
+hub, configuration reference, context working set, development pipeline, typed
+dispatch intent, this coverage audit, fleet demo runbook, Git commit provenance,
+performance methodology, release checklist, and resource library. Proactive
+memory also has its own page instead of sharing the evidence blueprint, and the
+duplicate prompt-envelope implementation was removed. The historical
+configuration-knob audit remains available under the History section of the
+HTML index.
+
+## Audit disposition
+
+The source-alignment pass corrected all findings across the 42 affected
+Markdown pages. The table preserves what the audit found at `ff56ea3e`; it does
+not describe outstanding Markdown debt. Every HTML blueprint now renders the
+complete corrected counterpart and identifies its Markdown source explicitly.

package/docs/process/documentation-guide.md

@@ -0,0 +1,187 @@
+# Documentation Standards and Codebase Alignment
+
+> **Visual blueprint:** The source checkout includes the complete
+> [Documentation Standards and Codebase Alignment visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/documentation_blueprint.html).
+
+Clio Coder is an experimental community alpha. Documentation should help contributors and early users work from the source of truth without overstating maturity. When docs drift, prefer the current source and tests over older prose or aspirational roadmap notes.
+
+---
+
+## Source-first documentation rule
+
+Before changing public docs, inspect the relevant implementation:
+
+1. `git log --oneline -- <area>` for recent intent and release context.
+2. `src/**` for current behavior.
+3. `tests/**` for executable contracts and edge cases.
+4. `README.md`, `CHANGELOG.md`, and `docs/**/*.md` for existing public wording.
+
+Classify claims clearly:
+
+| Claim class | How to word it |
+| --- | --- |
+| Shipped and tested | State directly and link to source/tests. |
+| Implemented but experimental | Say alpha/experimental and name sharp edges. |
+| Typed contract exists, default runtime is inert | Say the schema exists but no public loader/rules are active. |
+| Planned/future | Put in roadmap language; do not present as available behavior. |
+
+---
+
+## Documentation map
+
+| Guide | Primary source references | What it should cover |
+| --- | --- | --- |
+| [README.md](../../README.md) | `CHANGELOG.md`, package metadata, release receipts | Product overview, install, first run, alpha framing, and release status. |
+| [docs/README.md](../README.md) | This docs directory | Documentation hub. |
+| [documentation-guide.md](documentation-guide.md) | `docs/**`, `src/**`, `tests/**` | Documentation structure, source ownership, writing rules, and blueprint policy. |
+| [commands-and-modes.md](../guide/commands-and-modes.md) | `src/cli/index.ts`, `src/cli/args.ts`, `src/interactive/slash-commands.ts`, `src/domains/dispatch/**` | CLI commands, headless run flags (`--session`, `--continue`, `--json-events`), session continuity, `--json` wire projection promise, slash commands, keybindings, live steering. |
+| [context-engine.md](../architecture/context-engine.md) | `src/domains/context/**`, `src/domains/session/context-accounting.ts`, `src/domains/session/context-ledger.ts`, `src/domains/session/compaction/` | Context window resolution, per-model probe capabilities, token accounting, snapshots, the three compaction mechanisms, model-driven `clio-coder context init`, format v4 session enforcement. |
+| [context-working-set.md](../architecture/context-working-set.md) | `src/domains/context/working-set/**`, `src/domains/session/entries.ts`, `src/interactive/turn-context.ts` | Working-set vocabulary, eviction as a projection, the `contextEviction` / `contextRecall` records, the marker contract, the `age-horizon` and `structural-v1` policies, recall semantics, and the operator surfaces. |
+| [architecture.md](../architecture/architecture.md) | `tests/boundaries/check-boundaries.ts`, `src/core/domain-loader.ts`, `src/engine/**`, `src/worker/**` | Source layout, six enforced boundary rules, runtime flow mermaid diagram, event and audit model, and detect-and-rollback write boundaries. |
+| [time-conventions.md](../architecture/time-conventions.md) | `src/domains/dispatch/code-step.ts`, `src/domains/dispatch/extension.ts`, `src/domains/session/**`, `src/domains/observability/**` | Monotonic durations, wall-clock instants, anchored spans, injected clocks, timeout accounting, and timestamp serialization. |
+| [dispatch-architecture-rationale.md](../architecture/dispatch-architecture-rationale.md) | `src/domains/dispatch/**`, `tests/boundaries/check-boundaries.ts` | Design rationale, not behavior: invariants that cross the seams a dispatch split would use, what any future split must preserve, the one dispatch→eval import, and the closed barrel-import decision. |
+| [dispatch-typed-intent.md](../architecture/dispatch-typed-intent.md) | `src/domains/dispatch/intent.ts`, `src/domains/dispatch/intent-compatibility.ts`, `src/domains/dispatch/path-scope.ts`, `src/tools/dispatch-plan.ts` | Dispatch intent v2, path provenance, legacy inference, retirement telemetry, and fail-closed version handling. |
+| [configuration-and-targets.md](../guide/configuration-and-targets.md) | `src/core/defaults.ts`, `src/core/config.ts`, `src/domains/providers/**`, `src/cli/configure.ts`, `src/cli/targets.ts`, `src/cli/models.ts`, `src/cli/auth.ts` | TargetDescriptor, contextWindowProvenance (`configured`, `discovered`, `catalog`, `runtime-default`), settings.yaml, strict validation, saved defaults vs live routing. |
+| [artifact-placement.md](../architecture/artifact-placement.md) | `src/core/artifact-paths.ts`, `src/core/config.ts`, `src/domains/agents/result-contract-filesystem.ts` | Audience-based artifact placement, configured output roots, containment, and migration from legacy paths. |
+| [configuration-reference.md](../guide/configuration-reference.md) | `src/core/defaults.ts`, `src/cli/**`, `src/tools/**`, `src/domains/agents/recipe-schema.ts`, `src/domains/providers/models/local-models/**` | Audited inventory of every settings key, environment variable, CLI flag, project-file key, frontmatter key, tool argument, and model tag with defaults and precedence. |
+| [safety-model.md](../architecture/safety-model.md) | `src/domains/safety/**`, `src/tools/registry.ts`, `src/tools/policy.ts`, `src/tools/verify/**`, `src/entry/orchestrator.ts`, `src/domains/dispatch/write-boundary.ts` | Operating posture, `resolveEffectiveAutonomy` / `resolveBaselineAutonomy`, detect-and-rollback write boundaries, approval axes, damage control, typed validation. |
+| [prompt-envelope-and-tools.md](../architecture/prompt-envelope-and-tools.md) | `src/domains/prompts/compiler.ts`, `src/interactive/chat-loop.ts`, `src/core/tool-names.ts`, `src/tools/registry.ts`, `src/tools/observation.ts`, `src/tools/agent-tools.ts` | Prompt envelope reuse, canonical tool delivery via single `agent-tools.ts` adapter, seven-plane tool surface, observation envelope, strict `ToolName` keying. |
+| [tool-usage.md](../guide/tool-usage.md) | `src/tools/agent-tools.ts`, `src/tools/registry.ts`, `src/tools/observation.ts` | In-depth reference for all 21 canonical tools, including conditional registration, parameters, typical payloads, normalizers, and error examples. |
+| [provider-adapter-cookbook.md](../architecture/provider-adapter-cookbook.md) | `src/domains/providers/registry.ts`, `src/domains/providers/types/runtime-descriptor.ts` | RuntimeDescriptor, probe(), probeReasoning(), synthesizeModel(), thinking mechanisms. |
+| [pi-boundary.md](../architecture/pi-boundary.md) | `src/engine/**`, `src/tools/truncate.ts`, `tests/boundaries/check-boundaries.ts` | Which Pi SDK capabilities Clio delegates to, which Clio-specific adapters remain, and the boundary tests that keep the split explicit. |
+| [alcf-provider.md](../architecture/alcf-provider.md) | `src/domains/providers/runtimes/cloud/alcf.ts`, `src/engine/alcf-oauth.ts` | Globus PKCE OAuth, openAuthStorage(), Sophia vLLM, Metis API, chatTemplateKwargsUnsupported. |
+| [environment-variables.md](../guide/environment-variables.md) | `src/core/guardrails.ts`, `src/core/xdg.ts`, `src/domains/providers/knowledge-base-path.ts` | Comprehensive env var matrix: guardrail overrides, directory layout (CLIO_CODER_HOME), debug toggles, and internal plumbing. |
+| [built-in-agents.md](../guide/built-in-agents.md) | `src/domains/agents/**`, `src/domains/agents/builtins/*.md`, `src/domains/dispatch/**` | Builtin agent recipes, discovery roots, frontmatter schema, fleet contract shadowing (`.clio-coder/fleets/<name>.md`), active route automation. |
+| [fleet-dispatch.md](../guide/fleet-dispatch.md) | `src/domains/dispatch/**` | Multi-node SSH dispatch: process-safe admission, capacity leases, fleet contracts v1 through v5, v4 write boundaries, v5 plan and gate steps, bounded check/repair loops (`loop_bound_exhausted`), deterministic code steps, attestation, and receipts v20. |
+| [capacity-and-scheduling.md](../architecture/capacity-and-scheduling.md) | `src/domains/scheduling/**`, `src/domains/dispatch/capacity-lease.ts`, `src/domains/dispatch/reservation-store.ts` | Multi-process capacity leases (`dispatch-admission.json`), heartbeat TTLs, cross-process transaction locks (`dispatch-admission.json.lock`), and cluster drain controls. |
+| [worker-dispatch-mechanics.md](../architecture/worker-dispatch-mechanics.md) | `src/worker/**` | NDJSON parent-child socket protocols, control/bulk lane demuxing, watchdog timers, worker attestation (13 protocol fields), permission parking, exit codes. |
+| [fleet-demo-runbook.md](fleet-demo-runbook.md) | `src/domains/dispatch/**` | Multi-node fleet demo: SSH setup, C++ build/repair workflow, reviewer gates, and receipt verification v20. |
+| [session-lifecycle.md](../architecture/session-lifecycle.md) | `src/engine/session.ts`, `src/domains/session/**` | Session lifecycle, on-disk ledger format v4 (`current.jsonl`), tree branching (`tree.json`), active-path lineage selection, `/fork`, `/resume`, checkpoints, and write-ahead protected-artifact journal. |
+| [acp.md](../architecture/acp.md) | `src/engine/acp/**`, `src/cli/acp.ts` | Agent Client Protocol (ACP) server over stdio, tool mediation, non-stall permission handling, timeout bounds, and error taxonomy. |
+| [artifact-versions.md](../architecture/artifact-versions.md) | `src/domains/dispatch/receipt-integrity.ts`, `src/engine/session.ts`, `src/worker/spec-contract.ts`, `src/domains/agents/fleet-contract.ts`, `src/domains/eval/schema/`, `src/domains/observability/trace-store.ts` | Operator-facing registry and migration policies for selected compatibility-sensitive serialized artifacts. |
+| [exit-codes-and-output.md](../guide/exit-codes-and-output.md) | `src/cli/**`, `src/entry/**` | Global process exit codes (0, 1, 2, 3), `--help` standard on stdout, machine-readable JSON streaming (`--json`, `--json-events`), and headless stdout deliverable contracts. |
+| [troubleshooting.md](../guide/troubleshooting.md) | `src/core/**`, `src/cli/**`, `src/domains/**` | Actionable error remediation and diagnostics keyed by exact user-facing messages. |
+| [glossary.md](../guide/glossary.md) | `src/domains/dispatch/types.ts`, `src/tools/**`, `src/domains/agents/**`, `src/core/**` | Canonical definitions of 50 core architectural concepts mapped to `src/` types. |
+| [documentation-coverage.md](documentation-coverage.md) | `src/**` | Complete source-to-documentation mapping matrix and subsystem coverage status. |
+| [tui-design.md](../architecture/tui-design.md) | `src/interactive/theme/tokens.ts`, `src/interactive/theme/glyphs.ts` | TUI color system, glyph vocabulary (`contextReserve`), structural layouts, state choreography, code ink. |
+| [installation-and-lifecycle.md](../guide/installation-and-lifecycle.md) | `src/cli/paths.ts`, `src/cli/doctor.ts`, `src/cli/uninstall.ts`, `src/cli/removal.ts` | Installation, upgrade, reset, uninstallation, launcher ownership and what `--remove-binary` will and will not remove, partial-failure behavior, configuration folders (`credentials.yaml` `0o600`), and permissions. |
+| [release-cut-checklist.md](../history/release-cut-checklist.md) | `scripts/check-release.mjs`, `tests/smoke/installed-package.test.ts`, `.github/workflows/`, `package.json` | Historical v0.4.1 release procedure retained as evidence; future releases must draft and verify their own checklist. |
+| [development-pipeline.md](development-pipeline.md) | `skills/git/**`, `.github/**`, `scripts/check-release.mjs`, `package.json` | Issue-to-PR development lifecycle, validation, release inheritance, and the human merge boundary. |
+| [git-commit-provenance.md](git-commit-provenance.md) | `src/core/commit-attribution.ts`, `src/core/git-commit-attribution.ts`, `src/domains/dispatch/fleet-commit-attribution.ts` | Evidence-aware commit roles, trailers, managed hook chaining, and receipt v20 attribution. |
+| [observability.md](../architecture/observability.md) | `src/domains/observability/**`, `src/interactive/view/**`, `src/domains/dispatch/**`, `src/core/bus-events.ts` | `/view` artifact browsing, receipt verification, worker diagnostics, event routing, and cost snapshots. |
+| [performance-methodology.md](performance-methodology.md) | `src/interactive/render-trace.ts`, `src/interactive/**`, `tests/contracts/rendering-invariants.test.ts`, `tests/smoke/real-binary-boot.test.ts` | Reproducible terminal and model-path performance endpoints, trace interpretation, measurement controls, and reporting rules. |
+| [evidence-and-memory.md](../architecture/evidence-and-memory.md) | `src/domains/evidence/**`, `src/domains/memory/**`, `src/cli/evidence.ts`, `src/cli/memory.ts` | Evidence corpus layout, findings, memory lifecycle and prompt injection. |
+| [proactive-memory.md](../guide/proactive-memory.md) | `src/domains/memory/**` | Proactive task memory architecture, session task bank, intervention rules, and handoff carrying. |
+| [trace-store.md](../architecture/trace-store.md) | `src/cli/trace.ts`, `src/domains/observability/trace-store.ts` | WAL SQLite trace mirror database schema, rowid cursor queries, rebuildability, and eight `clio-coder trace` subcommands: `runs`, `phases`, `tail`, `procs`, `inspect`, `prune`, read-only `sql`, and `ui`. |
+| [eval-runner.md](eval-runner.md) | `src/domains/eval/**`, `src/cli/eval.ts` | Local YAML eval tasks, dual token accountings (`tokens.*` wire vs `receiptUsage.*` journal), fail-closed null totals, EvalArtifactV4 format, `verify.measure` task outcome recording. |
+| [evals-internal.md](evals-internal.md) | `src/domains/eval/**`, `evals/**` | Private suite handling, measurement design, and the boundary between shipped reference inputs and external campaigns. |
+| [extensions-and-sharing.md](../guide/extensions-and-sharing.md) | `src/domains/extensions/**`, `src/domains/resources/**`, `src/domains/share/**`, `src/cli/extensions.ts`, `src/cli/share.ts` | Prompt, skill, agent, fleet, and reserved theme resources; extension manifests; portable share archives. |
+| [resource-library.md](../guide/resource-library.md) | `src/domains/resources/library.ts`, `src/cli/library.ts` | Catalog schemas, private and remote source policy, checksum pins, resource installation, and update checks. |
+| [skills-marketplace.md](../guide/skills-marketplace.md) | `src/interactive/overlays/skills-hub.ts`, `src/domains/resources/skills/marketplace.ts` | Skills Hub marketplace discovery through the install resolver, empty state, install actions, publishing flow. |
+| [model-catalog.md](../architecture/model-catalog.md) | `src/domains/providers/catalog.ts`, `src/domains/providers/models/**`, `src/domains/providers/probe/**`, `src/domains/providers/model-capabilities.ts` | Model catalog, live probes (`--offline` toggle), exact-id selector `probeCapabilitiesForModel`, field-note promotion. |
+| [middleware-and-components.md](../architecture/middleware-and-components.md) | `src/domains/components/**`, `src/domains/middleware/**`, `src/cli/components.ts` | Active component snapshots, phase-aware middleware hook budgets (`DEFAULT_MIDDLEWARE_HOOK_BUDGETS_MS`). |
+| [scientific-validation.md](scientific-validation.md) | `src/domains/safety/rigor.ts`, `src/domains/safety/finish-contract.ts` | Advisory validation-contract patterns for scientific artifacts and HPC assumptions. |
+| [evolution.md](evolution.md) | `src/domains/evolution/**`, `src/cli/evolve.ts` | Falsifiable Change Manifest JSON templates, evidence-linked validation, and `clio-coder evolve`. |
+| [config-knobs-audit.md](../history/config-knobs-audit.md) | `src/cli/config.ts` | Point-in-time inventory of legacy environment variables (Historical Appendix). |
+
+---
+
+## Style conventions
+
+### Alpha framing
+
+Use direct, honest language:
+
+- "experimental community alpha"
+- "source-build path"
+- "current runtime is conservative/inert"
+- "advisory contract"
+- "planned/future milestone"
+
+Avoid phrases that imply managed production stability, full plugin maturity, or automatic scientific validation when the current code does not provide it.
+
+### Markdown structure
+
+- Prefer short sections with tables for command and schema references.
+- Use fenced examples that can be copied.
+- Keep links relative and repository-portable; do not use absolute `file:///home/...` links.
+- Mention source file paths in backticks instead of editor-specific absolute URLs.
+
+### GitHub alerts
+
+Use alerts sparingly:
+
+> [!NOTE]
+> Context or caveats that prevent misinterpretation.
+
+> [!WARNING]
+> Sharp edges, alpha limitations, or behavior that can surprise contributors.
+
+> [!CAUTION]
+> Safety, data loss, or security-sensitive constraints.
+
+---
+
+## Blueprint coverage and format strategy
+
+Clio Coder maintains two complementary documentation formats:
+
+1. **Markdown documents (`docs/guide/**/*.md`, `docs/architecture/**/*.md`, `docs/process/**/*.md`, and `docs/history/**/*.md`)**: The canonical reference for coding agents, developers, and maintainers, with `docs/README.md` as the hub. They optimize for retrievability, exact enumerations, schema tables, typed TypeScript contracts, and source citations (`src/...:line`).
+2. **HTML blueprints (`docs/html/*_blueprint.html`)**: One visual counterpart per Markdown page for human readers. Each blueprint carries the complete canonical prose plus navigation and copy affordances, and declares its source in `meta[name="clio-markdown-source"]`.
+
+### Blueprint Creation Policy
+
+Blueprint coverage is explicit rather than inferred from document style. The
+page-level audit lives in
+[`documentation-coverage.md`](documentation-coverage.md). All 51 Markdown pages
+have a dedicated blueprint. `docs/html/index.html` groups those counterparts by
+the same Guide, Architecture, Process, and History tree, while a source meta tag
+provides the one-to-one machine-readable mapping. Every mapping must remain
+unique, complete, and free of orphaned Markdown or HTML pages.
+`npm run lint` rejects any absent named blueprint, enforces that mapping, and
+compares every extractable `clio-coder <command>` string and `CLIO_CODER_*`
+name in each counterpart.
+
+---
+
+## Update checklist
+
+When a feature changes:
+
+1. Identify the source owner (`src/cli`, `src/interactive`, `src/tools`, or a domain).
+2. Check whether public CLI help changed.
+3. Update the mapped guide in the same PR.
+4. If behavior affects safety, sessions, receipts, prompts, targets, or dispatch, update both README-level user docs and the deeper guide.
+5. Run a lightweight link check for changed Markdown.
+6. For release docs, verify version badges/sections match `package.json` and `CHANGELOG.md`.
+7. Run `npm run lint` to verify Markdown and HTML blueprint parity.
+
+Suggested local link check:
+
+```bash
+python3 - <<'PY'
+import pathlib, re
+for md in list(pathlib.Path('docs').rglob('*.md')) + [pathlib.Path('README.md')]:
+    text = md.read_text()
+    for m in re.finditer(r'\[[^\]]+\]\(([^)]+)\)', text):
+        link = m.group(1)
+        if link.startswith(('http://', 'https://', 'mailto:', '#')):
+            continue
+        target = link.split('#')[0]
+        if target and not (md.parent / target).exists():
+            line = text.count('\n', 0, m.start()) + 1
+            print(f'{md}:{line}: missing {link}')
+PY
+```
+
+---
+
+## Community documentation priorities
+
+Clio users tend to be early adopters running real repositories, local models, and scientific/HPC code. Good docs should therefore prioritize:
+
+- reproducible first-run and target configuration;
+- local model/runtime field notes with exact versions and serving settings;
+- safety receipts and redaction guidance for issue reports;
+- small examples for project-local `CLIO-CODER.md`, `.clio-coder/safety.yaml`, prompts, skills, and agents;
+- clear labels for experimental surfaces such as middleware and scientific validation contracts.