TORCH/docs/PROJECT_KNOWLEDGE_SPEC.md

Project knowledge and domain institutional memory

Status: owner-approved development requirement, 2026-10-01. Not implemented. The fleet remains manually paused; recording this requirement does not authorize dispatch, new sessions, model calls, publication or automatic restart.

Purpose

Give users and agents a shared, evolving project reference, while preserving focused domain knowledge across session restarts, provider changes and agent replacement. Documentation should explain how the project actually works, not be a transcript archive, another backlog or a source of implicit authority.

Three connected layers

1. Project KB: authoritative, Git-backed Markdown documenting architecture, setup, interfaces, workflows, pipelines, troubleshooting and decisions.
2. Domain handbook: a compact entry point owned by the domain, linking to relevant KB pages and recording domain conventions, procedures and pitfalls. Prefer links over duplicated shared contracts. Knowledge belongs to the durable domain identity, not a provider conversation or disposable session.
3. Working memory: current investigations, hypotheses, handoffs and unfinished work. It is explicitly provisional; promotion to reference documentation requires supporting evidence and the ordinary review/integration process.

The existing backlog remains the sole task queue. Handbooks may link to tasks and domain coordination summaries but must not become competing task ledgers.

Storage and adoption

The repository is the source of truth; Console indexes and search results are rebuildable projections, never independent authoritative copies. Documentation must remain usable offline and without TORCH. Do not require a hosted service, particular AI provider or external documentation platform.

During init/analyze, discover existing documentation and propose a project-fit navigation and ownership map. Reuse existing directories and conventions rather than silently moving documents. For projects without conventions, a candidate layout is docs/knowledge/, docs/domains/<domain>/ and a clearly separated working-memory area. Exact paths and metadata format need a reviewed implementation contract; the layout is not a mandate for every project.

One accountable domain owns each reference page; collaborators and reviewers may be named separately. Cross-domain interface documentation retains one owner and review links to affected domains. Domain retirement, merge, split or reassignment must preserve history and transfer responsibility, not delete institutional memory.

Agent use and maintenance

Startup/resume briefs expose the compact domain index and essential references, not the full KB. Agents retrieve relevant detail on demand and can discover cross-domain references without loading unrelated documentation into every context. Record which revision was supplied; warn about stale references where detectable.

Completion of a behavior, interface or workflow change requires documentation impact to be considered: update affected pages or record why no update is needed. Do not make clerical documentation edits a permission to change another domain's implementation. Route cross-domain documentation changes through existing ownership and review mechanisms and notify affected owners.

Reference pages expose owner, status (draft/experimental/reference/deprecated), verification evidence and exact last-verified commit. A timestamp or successful render does not prove accuracy. Branch/candidate documentation must not masquerade as landed canonical behavior; represent divergence and unknown freshness honestly. Flag broken links, missing owners and affected pages needing re-verification. Do not automatically certify pages, mass-rewrite them or invent a freshness score.

Console Knowledge view

Add a dedicated Knowledge screen, not another long Overview section. Provide Read-the-Docs-style sidebar navigation, search, breadcrumbs, readable articles, stable deep links, responsive/mobile navigation and keyboard accessibility. Show owner, status, verified revision, related domains, tasks, pipeline definitions and history. Keep handbook, reference and provisional memory visibly distinct.

Offer bounded actions to ask the responsible domain and report outdated content through existing durable conversations/intake. Show queued/delivered outcomes; these actions must not wake agents while paused or silently grant edit authority. Use the same renderer for live project documentation and labelled demo fixtures. Do not bundle private project documents into the public marketing demo.

Safety and portability

Render repository text as untrusted content: sanitize Markdown, block script/raw HTML execution, unsafe URL schemes, path traversal and escaping symlinks. Restrict indexing/serving to approved documentation roots. Exclude credentials and private working-memory content according to explicit project visibility policy, including search snippets and cached indexes. External links/imported instructions do not override TORCH policy. KB content does not expand operational authority.

Required acceptance scenarios

• Existing project docs are discovered and linked without moves or overwrite; an empty project receives only a reviewed, project-fit plan.
• Restart or provider replacement inherits the same domain handbook; unrelated KB bodies are not injected into its startup context.
• A shared interface change updates its single authoritative page and routes affected-domain notification; unchanged pages are not falsely re-verified.
• A domain ownership change preserves document history and transfers maintenance responsibility without creating two authoritative copies.
• Provisional claims and candidate-branch behavior remain distinct from verified reference docs; missing evidence is visible rather than converted into confidence.
• Navigation, search, deep links, keyboard and mobile use work on a realistic multi-domain project; actual browser inspection is required before UI acceptance.
• Unsafe Markdown, traversal, symlink escape and private search leakage fail closed.
• Questions/corrections are durable while paused; no provider launch occurs.
• Markdown remains readable without TORCH, and the public demo has no private docs or live control-plane calls.

Implementation slices are recorded in the existing authoritative TORCH backlog. They remain proposed and unassigned for Session Manager triage after owner resume.