@thebackstoryis/engineering-with-ai 0.2.9

package/Docs/guided-intent-workspace-guide.md

@@ -0,0 +1,109 @@
+# Guided Intent Workspace
+
+The Guided Intent Workspace, labelled **Intent Studio** in the local dashboard, helps a product owner, facilitator, or engineer shape one feature intent without using the command line. It supports two bounded outcomes:
+
+- **Create a new intent** from a recoverable draft.
+- **Reconcile an eligible draft intent** while preserving its identity and delivery relationships.
+
+It does not replace participant conversations, approve delivery, or turn model output into project truth. Premium personas aren't required to create or review an intent. Installed personas improve the questions and challenges presented during shaping.
+
+## Before you begin
+
+Run the normal EWAI check-in and open the local dashboard URL it returns. Select **Intent Studio** from the main navigation.
+
+The workspace reads its project and persona context from the local EWAI runtime. It does not accept a project root, model provider, delivery command, or arbitrary output path from the browser.
+
+## Create a new intent
+
+An **intent identifier** points to one proposed outcome. For example, domain `support` and slug `export-filtered-tickets` identify a feature to export the filtered ticket list; its saved reference may include the domain. Use the reference EWAI returns in later commands rather than copying an example slug. Keep the title human-readable—the identifier is for finding the same work again.
+
+1. Select **Create a new intent**.
+2. Give the intent a stable slug, domain and title.
+3. Work through the evidence spine:
+   - identity;
+   - problem;
+   - desired outcome;
+   - users and affected roles;
+   - journeys;
+   - acceptance criteria;
+   - constraints and non-goals;
+   - intent relationships;
+   - delivery shape;
+   - evidence;
+   - open decisions;
+   - review.
+4. Use **Save and continue** to store a project-local draft and move to the next section.
+5. At Review, resolve every blocking omission and check the exact Markdown and JSON destinations.
+6. If you're the accountable approver, enter your name, confirm the review statement and approve the current draft revision. Otherwise, have that person review and approve it themselves.
+
+Approval atomically creates the canonical adjacent Markdown and JSON intent records. It does not approve Build, Manual QA, certification, deployment, or release.
+
+## Reconcile an eligible draft intent
+
+Choose **Reconcile an eligible draft intent**, then select a listed intent. An intent is eligible only when it is still genuinely draft work: its canonical Markdown and JSON agree, and delivery has not started.
+
+The workspace imports the existing intent into a new project-local working draft. Identity, relationships and delivery state remain protected. You can refine the title, personas, delivery shape and evidence-bearing intent sections.
+
+Review displays the proposed before and after values. A named approval of the current revision performs one atomic canonical replacement. If the underlying intent has moved into delivery or no longer matches the imported identity, reconciliation is rejected and the working draft is retained for recovery.
+
+## Recoverable drafts and revision conflicts
+
+Every successful save creates a new draft revision. If another tab or operator saved after you opened your copy, your save is rejected with a **revision conflict** rather than overwriting their newer work.
+
+When that happens:
+
+1. Copy any unsaved text you need to retain.
+2. Reload Intent Studio to obtain the current project-local draft.
+3. Reapply the relevant change and save again.
+
+**Discard draft** requires explicit confirmation and the current revision. It removes only the recoverable working draft, never an approved canonical intent.
+
+Failed canonical creation or reconciliation leaves the project-local draft in place. Resolve the reported collision or consistency problem, reload if necessary, and retry.
+
+## How persona engagement works
+
+EWAI recalculates the actively engaged personas when the current section or material draft context changes. The right-hand rail shows, for each active persona:
+
+- name;
+- source tier: project, core, installed premium, or personal;
+- the signals that matched;
+- why the persona is engaged now.
+
+The ensemble is deliberately replaced as the work moves from problem framing to journeys, assurance, delivery shape, and review. A small relevant ensemble is more useful than asking every persona every question.
+
+The **Standard host-model baseline** remains sufficient when no persona matches. Premium personas are optional. When the installed premium library is unavailable, the workspace explains that state and continues; it does not download or synchronise premium content. Project-local and personal personas can add organisation-specific language and responsibilities without weakening the baseline.
+
+Personas are advisory lenses. Their output is not participant evidence, legal approval, specialist assurance, business acceptance, or permission to build. Record interviews, workshops, repository observations, policies and research under Evidence, and keep unresolved claims under Open decisions.
+
+## Using the AI review hand-off
+
+**Copy AI review hand-off** places a bounded summary and instructions on the clipboard for use in the current host-model conversation. It does not send project data to a browser-selected provider, call a hidden model endpoint, save model output, or approve the draft.
+
+Ask the model to identify ambiguity, missing evidence, conflicting acceptance criteria, overlooked users and delivery-shape concerns. Bring useful suggestions back into the relevant section yourself and preserve their status as hypotheses until supported.
+
+## Review and accountable approval
+
+The Review section provides four distinct checks:
+
+1. **Readiness:** structural omissions that prevent materialisation.
+2. **Exact destinations:** the canonical Markdown and JSON paths that will change.
+3. **Before and after:** reconciliation changes, when applicable.
+4. **Accountable intent decision:** a named approval tied to the current revision.
+
+Intent approval means only: “this is an adequate statement of the intended outcome and its current evidence, constraints and open decisions.” Build approval remains a later durable gate. Manual QA, certification, deployment and release also remain separate decisions.
+
+## For EWAI maintainers
+
+The tests for changing Intent Studio itself are in [Verify changes to EWAI](maintainers/verification-walkthroughs.md#intent-studio). They aren't steps you need to complete to use the workspace.
+
+## Troubleshooting
+
+**No intent appears for reconciliation:** it is not a consistent draft, delivery has started, or its Markdown and JSON do not agree. Resolve canonical state through the governed workflow rather than bypassing the filter.
+
+**Premium personas are unavailable:** continue with the standard baseline and installed project or core personas. Use the normal entitlement and installation process separately if premium access is expected.
+
+**A save is rejected:** reload after preserving unsaved text. Revision conflicts are intentional concurrency protection.
+
+**Approval is disabled:** complete the blocking fields, provide the approver name, tick the review confirmation, and ensure the displayed revision is current.
+
+**Canonical materialisation fails:** the draft remains recoverable. Review the collision or consistency message; do not edit delivery state to force eligibility.

package/Docs/guided-phase-evidence-drafting-guide.md

@@ -0,0 +1,119 @@
+# Guided Phase Evidence Drafting
+
+The dashboard's **Contributions** view lets business and technical colleagues add what they know to an active delivery. They can record evidence, questions and decisions, then hand the discussion to the next owner. Contributions remain attributed to the people who made them; adding evidence doesn't approve Build or complete a delivery phase.
+
+## What it is for
+
+Use Contributions during these participant-facing moments:
+
+| Governed moment | Typical contribution |
+| --- | --- |
+| Reconcile | Observable current behaviour, inherited constraints, protected outcomes and unresolved history |
+| Plan | Outcomes, scope, dependencies, trade-offs, acceptance and named decisions |
+| Test Plan | Journeys, evidence oracles, environments, technical coverage and recovery |
+| Delivery preparation | Readiness, operations, communications, recovery, acceptance evidence and residual decisions |
+| Manual QA preparation | Representative journeys, devices, accessibility, observations, limitations and named acceptance route |
+
+Build execution, Standards Sweep, external validation, security disposition, phase completion and Retro keep their specialised governed workflows.
+
+## Open Contributions
+
+Work on the computer running the project dashboard, or with its owner through screen sharing. Sending a colleague the loopback URL doesn't give them remote access. Team Hub publishes bounded read-only summaries; it doesn't turn Contributions into a remotely editable shared workspace.
+
+1. Run the normal EWAI check-in and open the local dashboard URL.
+2. If **Contributions** isn't in the sidebar, enable it in **Configuration** and save. See [dashboard configuration](operations/dashboard-configuration.md).
+3. Open **Contributions**.
+4. Choose an active delivery.
+5. Check the phase, shared revision, digest and integrity state before contributing.
+
+An unsupported, completed or inconsistent phase is read-only. Follow its Companion route or the guarded delivery workflow instead of trying to bypass it.
+
+## Work in the right owner context
+
+The context bridge has three views:
+
+- **Business-facing owner** foregrounds outcomes, stakeholders, trade-offs, acceptance, communications and business decisions.
+- **Technical owner** foregrounds repository evidence, constraints, dependencies, standards, architecture, testing, operations and recovery.
+- **Shared review** presents both perspectives with their original attribution and keeps disagreement visible.
+
+Enter the real participant's name. Context selection is not authentication and does not prove expertise or authority. If the same person holds two responsibilities, use separate context records so the change in responsibility remains explicit.
+
+Changing context retains the same evidence, revision history, sources, decisions and questions. It also recomputes the active persona ensemble and announces which perspectives joined or left.
+
+## Record evidence with provenance
+
+Choose the current evidence topic, then classify each contribution:
+
+| Class | Use it for |
+| --- | --- |
+| `repository-fact` | Observable source, configuration, tests, history or generated Source Map evidence |
+| `participant-statement` | A statement attributed to a real named participant |
+| `imported-source` | A bounded claim from an identified document, transcript or external artefact |
+| `persona-hypothesis` | A question or hypothesis raised through an advisory persona lens |
+| `named-decision` | A decision attributed to a real accountable person |
+| `unresolved-question` | A question whose evidence or owner remains open |
+
+Add a source wherever possible. Record open questions and limitations instead of making the draft look artificially complete. Earlier evidence is append-oriented: qualify or resolve it in a later revision rather than silently changing its contributor or provenance.
+
+## Understand active personas
+
+Contributions continually shows each engaged persona's name, tier, matched signals and engagement reason.
+
+- Project and core personas plus standard host-model reasoning provide a complete baseline.
+- Relevant installed premium, personal and project-local personas can add specialist depth.
+- Missing premium personas are visible but never block a field, action, review or confirmation.
+- Contributions never downloads, synchronises, imitates or returns the full private body of a premium persona.
+
+Personas are lenses, not participants. They do not provide stakeholder evidence, identity, delegation authority, specialist assurance, validation, acceptance or approval.
+
+## Hand responsibility to another owner
+
+Choose **Prepare hand-off** when responsibility is genuinely moving. The preview binds:
+
+- source and destination owners;
+- source and destination contexts;
+- reason for the transition;
+- questions for the incoming owner;
+- current revision and digest.
+
+The incoming owner continues the same thread. A hand-off does not copy the draft or change the governed phase.
+
+## Request host-AI review
+
+Choose **Request host review**, then return to your EWAI conversation to confirm that you'd like the queued review picked up. The host can challenge missing evidence, provenance, contradictions and unresolved questions, then return suggestions to the discussion. Queuing or completing that review doesn't confirm your evidence or progress delivery.
+
+Only a bounded summary and safe metadata enter the hand-off queue, not your contribution body, credentials or private persona definitions. The [Contributions API reference](reference/contributions-api.md) describes the payload and its `authority: none` boundary for integration authors.
+
+## Confirm contribution evidence
+
+Use shared review before confirmation. Check named owners, original attribution, sources, hand-off history, conflicts, open questions, limitations, active personas, revision and digest.
+
+Choose **Confirm evidence**, enter the real confirmer's name and accept the exact consequence. EWAI writes collision-safe paired files under:
+
+```text
+SPECS/6.Build/<slug>/phase-contributions/<profile>/
+├── contribution-<timestamp>-r<revision>-<digest>.md
+└── contribution-<timestamp>-r<revision>-<digest>.json
+```
+
+Existing bundles are never overwritten. The JSON records the delivery and profile digests, evidence classes, owners, hand-offs, conflicts, limitations, active safe persona metadata and assurance boundary. The Markdown is a readable equivalent.
+
+The bundle is supporting evidence only. It doesn't automatically become the required Plan, Test Plan, Delivery or Manual QA document. Ask EWAI to reconcile the confirmed contributions into the relevant phase work, then review the result. The phase still needs its required documents and passing gate.
+
+## Discard and recover
+
+- **Discard draft** removes only the disposable file under `.ewai-pipeline/runtime/phase-contributions/`. Confirmed bundles remain.
+- A **stale revision** means another save or hand-off won. Preserve your unsaved text, reload and add it to the current revision.
+- A **changed phase, source or profile** pauses mutation. Review the governed change before deciding whether the old contribution still applies.
+- An **integrity blocker** leaves Contributions read-only. Reconcile the Markdown intent, adjacent JSON, delivery state and SQLite projection through the normal EWAI workflow.
+- A **missing premium library** needs no recovery. Continue with the complete standard and project/core baseline.
+
+## Loopback API for implementers
+
+The [Contributions API reference](reference/contributions-api.md) preserves the six routes, revision checks and server-owned context rules. You don't need these HTTP details to contribute through the dashboard or host.
+
+## Assurance boundary
+
+Contribution evidence can still be incomplete or wrong. Personas and model output can miss issues. A named human must review attribution, sources, limitations, disagreements and applicability before incorporating it into governed phase material.
+
+If the contribution concerns security, use the separate [security validation workflow](security-validation-guide.md). Confirming a contribution doesn't satisfy that review or its release conditions.

package/Docs/human-approval-and-assurance-guide.md

@@ -0,0 +1,146 @@
+# Human approval and assurance guide
+
+Use this guide when you are asked to approve Discovery, Build, curation, Manual QA, or another consequential EWAI action.
+
+## What approval means
+
+Approval means a named person has reviewed the stated evidence, understands the consequences and remaining uncertainty, has authority for the decision, and accepts the scope recorded at that moment.
+
+It does not mean:
+
+- every possible defect has been eliminated;
+- an AI persona agrees with the decision;
+- a green test suite proves the product is useful;
+- a Blueprint publisher owns the project's consequences;
+- later upstream changes are automatically approved;
+- the same decision covers a materially expanded scope.
+
+## The approval layers
+
+| Decision | Typical approver | Minimum evidence |
+| --- | --- | --- |
+| Discovery or Blueprint application | Product or project owner | Proposed project files, modules, provenance, conflicts, and exact consequences |
+| Archaeology curation | Project owner or knowledge steward | Source-linked findings, disagreements, rejected inferences, and destination paths |
+| Premium library sync | Entitled user or administrator | Website licence entitlement, verified release/update status, and explicit consent |
+| Build | Product owner or delegated delivery authority | Ready intent, plan, tests, standards coverage, scope, risks, and stop conditions |
+| Destructive operation | Owner of the affected data or system | Exact targets, recovery route, blast radius, and necessity |
+| Manual QA | Accountable accepter or authorised tester | Reproducible walkthrough, results, limitations, and residual risks |
+
+Roles vary by organisation. Record the actual person and their authority rather than relying on a job-title assumption.
+
+## Evidence before confidence
+
+An assurance pack should answer:
+
+1. **Outcome:** What human or operational result was intended?
+2. **Scope:** What was included and explicitly excluded?
+3. **Provenance:** Where did requirements, standards, and reusable content come from?
+4. **Implementation:** What changed and where?
+5. **Validation:** Which tests, standards checks, and independent reviews ran?
+6. **Exceptions:** What failed, was unavailable, or remains uncertain?
+7. **Operation:** How will the change be observed, supported, and recovered?
+8. **Acceptance:** What did a person actually inspect or experience?
+
+Prefer links to durable project evidence over copied summaries that can drift.
+
+## Preserve independence honestly
+
+An agent cannot independently review its own work merely by starting a second prompt. EWAI removes the current orchestrator from eligible external validators and respects the configured provider set and cycle limit.
+
+When no independent provider remains:
+
+- record the checkpoint as not supported;
+- strengthen deterministic checks and human review proportionately;
+- do not relabel self-review as external assurance;
+- decide explicitly whether the remaining evidence is adequate for the risk.
+
+## Approve Build precisely
+
+The durable command is:
+
+```bash
+ewai delivery approve-build <intent-slug> \
+  --project . \
+  --yes \
+  --approved-by "Approver name" \
+  --scope "Exact approved outcome and boundaries"
+```
+
+Before approving, verify that:
+
+- the intent is ready or approved;
+- Reconcile addressed existing behaviour where relevant;
+- vertical slices and dependencies are understandable;
+- the first tests and acceptance evidence are defined;
+- standards coverage passes;
+- external-review availability is represented accurately;
+- the scope describes what may be changed.
+
+## Approve Manual QA separately
+
+Automated Delivery completion pauses at Manual QA. Approval requires a project-owned evidence file:
+
+```bash
+ewai delivery approve-manual-qa <intent-slug> \
+  --project . \
+  --yes \
+  --approved-by "Approver name" \
+  --evidence SPECS/6.Build/<intent-slug>/qa-evidence.md \
+  --notes "Observed outcome and accepted limitations"
+```
+
+The evidence should say what environment was used, what steps were performed, what happened, what was not tested, and whether any defects or follow-ups remain.
+
+Do not approve Manual QA for someone else unless your governance model explicitly makes you accountable for their evidence.
+
+## Assess evidence proportionately
+
+Recommended practice is to scale assurance with:
+
+- user and business impact;
+- data sensitivity and regulatory exposure;
+- external accessibility;
+- reversibility;
+- operational blast radius;
+- novelty and uncertainty;
+- dependency and supply-chain risk;
+- quality of direct user evidence.
+
+A small internal reversible tool may need a short walkthrough. A public system handling sensitive data needs deeper security, privacy, resilience, accessibility, and operational evidence.
+
+## Reject or return the decision when
+
+- the approver cannot explain the outcome or consequences;
+- evidence is missing, stale, contradictory, or unauthorised;
+- the scope is broader than the reviewed plan;
+- tests are green but meaningful user behaviour was not exercised;
+- a persona is presented as stakeholder consent;
+- an unavailable external review is presented as passed;
+- rollback, migration, or operational ownership is unclear;
+- pressure to approve is being used to conceal uncertainty.
+
+## Approval record checklist
+
+- [ ] Decision and exact scope are stated.
+- [ ] Approver identity and authority are clear.
+- [ ] Evidence is durable and linked.
+- [ ] Automated, independent, and human checks are distinguished.
+- [ ] Unavailable checks and residual risks are visible.
+- [ ] Time-sensitive versions, digests, and environments are recorded.
+- [ ] A material change will require a new decision.
+
+## Related guides
+
+- [Product Owner guide](product-owner-guide.md)
+- [Developer delivery guide](developer-delivery-guide.md)
+- [Manual QA and acceptance](quality/manual-qa-and-acceptance.md)
+- [Governance team guide](governance/governance-team-guide.md)
+
+## Current contract sources
+
+- `SPECS/pipeline.yaml`
+- `src/discovery.mjs`
+- `src/archaeology.mjs`
+- `src/checkin.mjs`
+- `src/delivery.mjs`
+- `src/validation-config.mjs`

package/Docs/knowledge-proposals-implementer-guide.md

@@ -0,0 +1,106 @@
+# Evidence-to-Knowledge Proposals implementer guide
+
+Use this guide when extending EWAI or building an integration for knowledge proposals. The CLI, MCP tools and dashboard all call the same domain module. That module validates destinations, review decisions and file changes; the interfaces must not implement different rules.
+
+Connectors are not implemented by this capability; organisation-owned consumers use the generic post-persistence lifecycle-hook boundary.
+
+## Domain architecture
+
+`src/knowledge-proposals.mjs` owns the domain rules, grouped here by responsibility:
+
+- sources and preparation: promoted-meeting-evidence and retrospective adapters, bounded reads, digests, anchors, contextual installed-persona selection and the host-model contract;
+- proposals and decisions: closed taxonomy, evidence-only bundles and complete named review;
+- publication and recovery: separately confirmed materialisation, additive/current/conflict classification, transaction journals and idempotency;
+- integration: public-safe state and `ewai.knowledge-proposals.materialised`.
+
+The configured project root comes from EWAI. MCP and browser callers cannot provide another root.
+
+## Storage
+
+```text
+3.Evidence/knowledge-proposals/<bundle-id>/
+├── bundle.json
+├── review.json
+├── materialisation.json
+└── proposals/SPECS/<closed destination>.md
+```
+
+The `proposals/` tree is evidence, not canonical destination knowledge. A private journal under `.ewai-pipeline/knowledge-proposals/transactions/` records transaction-owned destinations and a `createdDigests` map of the SHA-256 of each recorded write. It stores no document bodies.
+
+Bundle, review and materialisation records have independent digests. Materialisation re-resolves the source and verifies all authority layers before any destination write.
+
+## Domain operations
+
+| Function | Mutates | Boundary |
+| --- | --- | --- |
+| `listKnowledgeSources` | Nothing | Allowlisted canonical source families, no content/path |
+| `prepareKnowledgeProposals` | Nothing | Bounded model context, strict schema and active personas |
+| `recordKnowledgeProposalBundle` | Proposal evidence only | Closed taxonomy, exact destination, anchors and provenance |
+| `recordKnowledgeProposalReview` | Review evidence only | Named complete dispositions and amendment rationale |
+| `materialiseKnowledgeProposals` | Absent accepted destinations and ledger | Separate exact confirmation, named approver and digest revalidation |
+| `recoverKnowledgeMaterialisation` | Unchanged transaction-created files or stale journal | Exact confirmation, safe paths and matching creation digests; preserve unknown or changed files |
+| `readKnowledgeProposalWorkspace` | Nothing | Safe source, proposal, review, outcome and persona projection |
+
+Normal materialisation doesn't overwrite, merge or delete an existing destination. An identical file is current; a differing file is a conflict. Interrupted recovery is a separate operation that may remove unchanged transaction-created files under the conditions below.
+
+## CLI, MCP and HTTP
+
+CLI:
+
+```bash
+ewai knowledge sources --project . --json
+ewai knowledge prepare SOURCE_REF [--focus TEXT] --project . --json
+ewai knowledge record SOURCE_REF --input FILE --project . --json
+ewai knowledge review BUNDLE_ID --input FILE --reviewed-by NAME --project . --json
+ewai knowledge materialise BUNDLE_ID --yes --approved-by NAME --project . --json
+ewai knowledge recover BUNDLE_ID --yes --project . --json
+ewai knowledge status [BUNDLE_ID] --project . --json
+```
+
+MCP exposes matching `ewai_knowledge_proposal_*` tools. Sources, status and prepare are read-only. Record and review are non-destructive mutations. Materialisation is additive and non-destructive. Recovery is marked destructive because it can remove transaction-owned incomplete files. No tool accepts `projectRoot`.
+
+Loopback HTTP provides `GET /api/knowledge-proposals?bundle=<id>`, plus `POST` routes for prepare, record, review, materialise and recover. Browser-safe preparation strips `modelContext` and reports only that host context is available. AI-host CLI and MCP preparation receive the bounded content. Unknown query/body fields are rejected and errors include the mandatory disclaimer.
+
+## Mind Palace behavior
+
+Knowledge proposals is a secondary Mind Palace mode, not primary navigation. The source rail shows eligible evidence and bundles. The centre shows review receipts, provenance/destination cards and additive/current/conflict state. The context rail always shows actively engaged personas with name, tier and engagement reason.
+
+The browser can prepare a safe host handoff, record a complete named review, separately materialise and recover. It cannot register arbitrary sources, preview source bodies, choose paths, sync premium content, create a downstream intent, approve Build, accept risk or release.
+
+At 960px the ledger and context rail stack. At 600px review fields, receipts and cards use one column with no fixed-width child requiring horizontal scroll.
+
+## Persona and model contract
+
+Standard host-model reasoning and installed project/core personas are the complete baseline. Premium and personal personas are optional installed enrichment. Selection is contextual and replacement-based. Interfaces display the active ensemble but never expose managed persona bodies.
+
+The host distinguishes source observation, interpretation and proposed knowledge. Only the final validated `ewai.knowledge-proposal-bundle/v1` enters evidence storage. Raw model output, prompts, chain-of-thought and discarded drafts are never stored.
+
+## Lifecycle boundary
+
+After canonical destination writes and the immutable ledger exist, EWAI publishes `ewai.knowledge-proposals.materialised` with bundle/materialisation identifiers and digests, added/current/conflict counts and timestamp. The event references the project-relative ledger and contains no source body, proposal body, prompt, credential or private path. Hook failure cannot veto, delete or roll back canonical truth. Consumers implement connectors through the generic hook contract.
+
+## Recovery and idempotency
+
+Before ledger persistence, an interrupted transaction retains its created paths and their original content digests. Recovery validates the complete destination list before deleting anything and inspects every path component from the workspace root, including ancestors of a nested SPECS directory. Only single regular files with unchanged bytes are removed.
+
+Missing files need no action. Changed, linked, unreadable or oversized files, and existing files from legacy journals without digests, are preserved. Recovery keeps the journal and throws `KNOWLEDGE_RECOVERY_REQUIRES_REVIEW`; its message identifies affected relative paths and tells the user to review and back up the files. The error also includes `preserved` and `removed` arrays for local callers. Existing dashboard and CLI error handling presents this as a paused recovery, not a successful completion.
+
+After ledger persistence, a remaining journal is stale runtime state and is removed without touching canonical destinations. Repeating a materialised bundle returns its existing result. These are local filesystem safeguards, not an atomic guarantee against another process changing paths concurrently; don't run recovery while another writer is modifying those destinations.
+
+These safeguards protect the publication boundary; they don't establish the correctness of generated knowledge. Preserve named review and separate materialisation approval in any integration.
+
+## Contract sources
+
+- [src/knowledge-proposals.mjs](../src/knowledge-proposals.mjs)
+- [config/knowledge-proposals-proposal.schema.json](../config/knowledge-proposals-proposal.schema.json)
+- [src/runtime/lifecycle-hooks.mjs](../src/runtime/lifecycle-hooks.mjs)
+- [src/cli.mjs](../src/cli.mjs)
+- [src/runtime/mcp-server.mjs](../src/runtime/mcp-server.mjs)
+- [src/runtime/dashboard-server.mjs](../src/runtime/dashboard-server.mjs)
+- `public/index.html`
+- `public/app.js`
+- `public/styles.css`
+- `tests/knowledge-proposals.test.mjs`
+- `tests/knowledge-proposals-cli.test.mjs`
+- `tests/lifecycle-hook-emissions.test.mjs`
+- `tests/runtime.test.mjs`