From a2fc8e99cf0d5087983b151cce0017420c5e3c0f Mon Sep 17 00:00:00 2001 From: thePR0M3TH3AN Date: Thu, 1 Oct 2026 16:24:37 -0400 Subject: [PATCH] docs: specify shared project knowledge and domain handbooks --- docs/PORTABLE_AGENT_FLEET_SPEC.md | 6 ++ docs/PROJECT_KNOWLEDGE_SPEC.md | 111 ++++++++++++++++++++++++++++++ docs/TODO.md | 18 +++++ 3 files changed, 135 insertions(+) create mode 100644 docs/PROJECT_KNOWLEDGE_SPEC.md diff --git a/docs/PORTABLE_AGENT_FLEET_SPEC.md b/docs/PORTABLE_AGENT_FLEET_SPEC.md index 3a55f0b..afbb483 100644 --- a/docs/PORTABLE_AGENT_FLEET_SPEC.md +++ b/docs/PORTABLE_AGENT_FLEET_SPEC.md @@ -2743,6 +2743,12 @@ and refuses to replace a launcher path not owned by that installation. ## 27. User interfaces +Project reference documentation, domain handbooks and provisional working memory +MUST follow [Project knowledge and domain institutional memory](PROJECT_KNOWLEDGE_SPEC.md). +This owner-approved extension requires a Git-backed shared KB, durable domain +ownership, compact agent entry points and a dedicated Console Knowledge view. +It is a development requirement, not a claim that the feature is implemented. + ### 27.1 CLI The target command surface includes: diff --git a/docs/PROJECT_KNOWLEDGE_SPEC.md b/docs/PROJECT_KNOWLEDGE_SPEC.md new file mode 100644 index 0000000..ed4e697 --- /dev/null +++ b/docs/PROJECT_KNOWLEDGE_SPEC.md @@ -0,0 +1,111 @@ +# 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//` 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. diff --git a/docs/TODO.md b/docs/TODO.md index c8ffd17..787df51 100644 --- a/docs/TODO.md +++ b/docs/TODO.md @@ -1,5 +1,23 @@ # TORCH remaining work +## Owner-approved project knowledge requirement (2026-10-01) + +See [Project knowledge and domain institutional memory](PROJECT_KNOWLEDGE_SPEC.md). +The existing authoritative backlog holds the implementation slices below; this +section is an index, not a second queue. All are proposed/unassigned, and the +fleet remains manually paused until the owner explicitly requests resume. + +- `TASK-knowledge-contract`: project-fit Git-backed KB, domain handbooks and + provisional memory; metadata, visibility, evidence and ownership contract. +- `TASK-knowledge-agent-context`: documentation discovery, compact domain brief + references and provider-independent retrieval/inheritance without context bloat. +- `TASK-knowledge-maintenance`: documentation-impact workflow, verification + evidence, cross-domain notifications and ownership transfer without duplicate truth. +- `TASK-knowledge-console`: dedicated accessible Knowledge view, safe rendering, + search, history and durable ask-domain/report-outdated actions. +- `TASK-knowledge-qualification`: end-to-end inheritance/freshness/privacy/pause + scenarios and realistic browser acceptance, including isolated demo fixtures. + ## Authoritative current handoff (2026-09-30, after alpha.2 reinstall) TORCH is installed and healthy at `0.1.0-alpha.2`. Setup/restore and all seven