@thebackstoryis/engineering-with-ai 0.2.9

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

@@ -0,0 +1,247 @@
+# Turn reviewed evidence into project knowledge
+
+A meeting or retrospective can reveal a missing requirement, a useful working practice or a risk nobody had recorded. Knowledge proposals helps you turn that learning into proposed project documents, check each one and add only the changes you've agreed to SPECS.
+
+The original evidence stays linked to the proposal. Reviewing a proposal and adding its file are separate decisions, so you can check the destination and content before anything becomes part of the project's working knowledge.
+
+In normal use, [ask EWAI to help](#ask-ewai-to-help). The later [terminal exercise](#prepare-and-record-proposals-from-the-terminal) is a complete scripting example, not a requirement to write JSON before discussing the evidence.
+
+
+<!-- editorial: contents -->
+## On this page
+
+- [What it produces](#what-it-produces)
+- [Eligible evidence](#eligible-evidence)
+- [How personas participate](#how-personas-participate)
+- [Ask EWAI to help](#ask-ewai-to-help)
+- [Prepare and record proposals from the terminal](#prepare-and-record-proposals-from-the-terminal)
+- [Review every proposal](#review-every-proposal)
+- [Approve adding the documents to SPECS](#approve-adding-the-documents-to-specs)
+- [Recover an interrupted write](#recover-an-interrupted-write)
+- [Ways to operate](#ways-to-operate)
+- [Related guidance](#related-guidance)
+
+## What it produces
+
+EWAI saves the proposed documents together under `SPECS/3.Evidence/knowledge-proposals/`. This is a **proposal bundle**, not an update to your working documentation. For each proposal you can see the source passage it refers to, the proposed file and location, why it's useful and what's still uncertain. A reviewer must decide on every proposal before an owner separately approves adding the agreed files to SPECS.
+
+The supported document types cover project personas, systems, processes, data concepts, journeys, pending requirements, feature candidates, risks, policies, constraints, standards, decisions, patterns, anti-patterns, runbooks and SOPs. Each type has an allowed location. A proposal can't invent another destination or change delivery state.
+
+## Eligible evidence
+
+Start with meeting evidence that's already been reviewed and promoted, or a retrospective saved in the project's SPECS. List the available sources below and use the returned source reference. A raw transcript, arbitrary folder or private review record isn't an eligible source; use [Meeting evidence](meeting-evidence-user-guide.md) first for a transcript. This workflow doesn't fetch material from an external connector.
+
+```bash
+ewai knowledge sources --project . --json
+```
+
+## How personas participate
+
+EWAI selects relevant personas for the source and the concern you're exploring. Your normal AI assistant and the project/core personas are enough to use the workflow. Installed premium or personal personas can add specialist perspectives; this operation never downloads them.
+
+Every interface shows active persona name, tier, matched signals and engagement reason. A Product Owner may question whether a feature candidate reflects an actual outcome; a Knowledge Curator may challenge its destination; an Archaeologist may distinguish current evidence from historical interpretation; and a project persona may apply local language or constraints.
+
+Personas remain advisory. They cannot turn inference into fact, supply absent stakeholder research, perform named review, approve materialisation, accept risk or authorise release.
+
+## Ask EWAI to help
+
+In your EWAI conversation, ask: “Use `$ewai-knowledge-proposals` to review this retrospective and suggest what we should add to our project docs.” Identify the source from the list above. You'll review the proposed content and destinations before deciding whether to add any files. You don't need to author JSON for the conversational route.
+
+To inspect a saved bundle, open **Mind Palace → Knowledge proposals**. The source document stays private; this view shows the proposed documents, their evidence references and any conflicts.
+
+## Prepare and record proposals from the terminal
+
+The following is a complete, fictional example for a disposable, initialised project. In real work, use a genuine reviewed source returned by `knowledge sources`; don't add fictional evidence just to make a command run. These paths assume the default `SPECS` location. If yours differs, use its actual relative path in the source and destination.
+
+Save this example as `SPECS/3.Evidence/retros/sprint-24.md`:
+
+<!-- example: knowledge-retrospective -->
+```markdown
+# Retrospective: Sprint 24
+
+## What we learned
+
+The team couldn't follow the recovery notes during a failed import.
+
+## Agreed follow-up
+
+Try recovery instructions with a colleague before the next release.
+```
+
+From the project root, prepare the source:
+
+```bash
+ewai knowledge prepare retrospective:sprint-24 --project . --json
+```
+
+Preparation doesn't create proposals or change files. Its JSON result includes `source.ref`, `source.digest` and `source.anchors`: the source identity, a fingerprint of its current contents and IDs for passages you can cite. Check the passage behind an anchor before using it. The AI host receives the allowed source context and format; the browser doesn't receive the source text.
+
+Create `proposal-bundle.json` in the project root with the following content. Replace `SOURCE_DIGEST_FROM_PREPARE` with `source.digest`, and both occurrences of `ANCHOR_ID_FROM_PREPARE` with the ID of the passage supporting the proposal. Preserve the outer `bundle` object: that's what the CLI reads.
+
+<!-- example: knowledge-proposal-bundle -->
+```json
+{
+  "bundle": {
+    "schema": "ewai.knowledge-proposal-bundle/v1",
+    "sourceRef": "retrospective:sprint-24",
+    "sourceDigest": "SOURCE_DIGEST_FROM_PREPARE",
+    "proposals": [
+      {
+        "id": "KNP-001",
+        "kind": "pattern",
+        "title": "Try recovery notes before release",
+        "destination": "SPECS/5.Strategy/patterns/try-recovery-notes.md",
+        "evidenceAnchors": ["ANCHOR_ID_FROM_PREPARE"],
+        "rationale": "The retrospective records difficulty following the recovery instructions.",
+        "uncertainty": "Confirm which changes need a recovery walkthrough.",
+        "relationships": [],
+        "proposedMarkdown": "# Try recovery notes before release\n\nAsk a colleague to try the recovery instructions before release.\n\n## Provenance\n\n- Source: retrospective:sprint-24\n- Anchor: ANCHOR_ID_FROM_PREPARE\n"
+      }
+    ]
+  },
+  "activePersonas": []
+}
+```
+
+This hand-written example has no persona contribution, so `activePersonas` is empty. When an AI host prepares the proposals, record the returned metadata for the personas actually used; don't invent contributors. Keep observation separate from interpretation in the proposal.
+
+Record the file:
+
+```bash
+ewai knowledge record retrospective:sprint-24 \
+  --input ./proposal-bundle.json \
+  --project . \
+  --json
+```
+
+The response returns a `bundleId`. Copy that value for the review and approval commands below. A successful record saves the proposals for review; it doesn't create `try-recovery-notes.md`.
+
+Input files must be inside the project; run these examples from its root so relative paths resolve correctly. EWAI doesn't store raw model output, discarded drafts, prompts or source bodies in the bundle. The input files you save yourself remain your responsibility—keep them free of private source text.
+
+## Review every proposal
+
+Inspect each proposed kind, destination, anchors, rationale, uncertainty and destination state in **Mind Palace → Knowledge proposals**. The active personas remain visible alongside the bundle.
+
+A named reviewer decides `accepted`, `rejected`, `amended` or `deferred` for every proposal. Rejected and deferred items need rationale. Amendments need replacement title, complete replacement Markdown and rationale.
+
+For the single proposal above, save this as `proposal-review.json` **only if the reviewer accepts it**:
+
+<!-- example: knowledge-review-accepted -->
+```json
+{
+  "dispositions": [
+    {"proposalId": "KNP-001", "decision": "accepted"}
+  ]
+}
+```
+
+`dispositions` means the decisions you've made. Include exactly one entry for each proposal ID in the bundle. Use the actual reviewer's name or accountable role in the command, not the example role unless that's who made the decision.
+
+```bash
+ewai knowledge review <bundle-id> \
+  --input ./proposal-review.json \
+  --reviewed-by "Product Owner" \
+  --project . \
+  --json
+```
+
+The response confirms the review and its decision counts. It still hasn't added the proposed document to SPECS.
+
+### If the reviewer wants a change
+
+Use this alternative `proposal-review.json` for the same one-proposal bundle. Replace the anchor placeholder with the same source anchor you checked earlier. An amendment replaces the whole proposed document, not a fragment; retain its `## Provenance` section and source reference.
+
+<!-- example: knowledge-review-amended -->
+```json
+{
+  "dispositions": [
+    {
+      "proposalId": "KNP-001",
+      "decision": "amended",
+      "rationale": "Limit this practice to changes that introduce or alter a recovery procedure.",
+      "replacementTitle": "Check changed recovery procedures",
+      "replacementMarkdown": "# Check changed recovery procedures\n\nWhen a change introduces or alters a recovery procedure, ask a colleague to follow it in a safe test environment before release.\n\n## Provenance\n\n- Source: retrospective:sprint-24\n- Anchor: ANCHOR_ID_FROM_PREPARE\n"
+    }
+  ]
+}
+```
+
+### If the reviewer rejects or defers it
+
+These are two alternative files for the same one-proposal bundle, not two decisions to submit together:
+
+<!-- example: knowledge-review-rejected -->
+```json
+{
+  "dispositions": [
+    {"proposalId": "KNP-001", "decision": "rejected", "rationale": "The existing release checklist already covers this practice."}
+  ]
+}
+```
+
+<!-- example: knowledge-review-deferred -->
+```json
+{
+  "dispositions": [
+    {"proposalId": "KNP-001", "decision": "deferred", "rationale": "The release owner needs to confirm which changes require a walkthrough."}
+  ]
+}
+```
+
+Choose the correct decision before recording the review. A recorded review can't be replaced. EWAI allows one bundle per version of a source: changing only the proposal or review doesn't create another bundle and will be refused. A new bundle needs genuinely changed eligible evidence or a new eligible source. Don't edit evidence just to bypass this restriction. If the source hasn't changed, keep the existing record and ask the project owner how to handle the follow-up outside this workflow. Rejected and deferred proposals aren't added to working documentation.
+
+If every proposal was rejected or deferred, stop here. There are no documents to add, and `materialise` will refuse the operation with “no accepted or amended records to materialise”.
+
+## Approve adding the documents to SPECS
+
+Check status with `ewai knowledge status <bundle-id> --project . --json`. Review the accepted content and destination conflicts. When the owner separately approves adding the documents, run the command below. **Materialise** is the CLI's name for this step; recording the review wasn't permission to do it.
+
+```bash
+ewai knowledge materialise <bundle-id> \
+  --project . \
+  --yes \
+  --approved-by "Product Owner" \
+  --json
+```
+
+EWAI handles each accepted or amended proposal independently:
+
+- absent destination: add it;
+- byte-identical destination: report it as current;
+- differing, linked or non-file destination: report a conflict and leave it unchanged.
+
+There is no automatic overwrite, model merge or deletion. Materialisation also does not create a ready intent automatically. A feature candidate remains a candidate until someone uses the normal intent and delivery workflow.
+
+## Recover an interrupted write
+
+If status reports `recovery-required`, inspect the bundle and ask an accountable person before running:
+
+```bash
+ewai knowledge recover <bundle-id> --project . --yes --json
+```
+
+Recovery removes a transaction-created file only when it is still a safe regular file and its bytes match the digest recorded at creation. It leaves edited files, symbolic links, hard-linked replacements and files with no original digest untouched. Older journals without digests therefore need manual review, not an automatic deletion.
+
+If anything is preserved, you'll see **Recovery paused** with the affected paths and reasons. The journal stays in place; unchanged transaction files may already have been removed. Retrying doesn't force deletion.
+
+Review and back up the listed files. If you choose to keep an edited document, move it to a safe location outside its proposed destination before retrying recovery. Once recovery finishes, restore your document; a later materialisation will report it as a conflict rather than overwrite it. Ask the project owner before moving shared work. Don't delete or rewrite the journal just to clear the warning.
+
+If the final materialisation ledger already exists, recovery removes only the stale journal and leaves the completed documents in place.
+
+## Ways to operate
+
+| Surface | Best use | Boundary |
+| --- | --- | --- |
+| CLI | Repeatable local operation and exact JSON | Project-relative inputs and the same human gates apply |
+| EWAI skill | Persona-led analysis and schema-valid drafting | It cannot approve its own proposals |
+| MCP | Typed AI-host preparation, record, review and materialisation | Server owns the project root; recovery is explicitly destructive |
+| Mind Palace | Source route, proposals, conflicts, review and active personas | It never shows private source bodies or grants release authority |
+
+Saving a reviewed proposal makes it project knowledge, not proof that its claims are correct. Review the source, intended meaning and applicability with the responsible people. Security concerns still need the separate [security validation workflow](security-validation-guide.md).
+
+## Related guidance
+
+- [Meeting evidence user guide](meeting-evidence-user-guide.md)
+- [Working with personas](working-with-personas.md)
+- [Human approval and assurance](human-approval-and-assurance-guide.md)
+- [Knowledge proposals implementer guide](knowledge-proposals-implementer-guide.md)

package/Docs/maintainers/context-benchmarks.md

@@ -0,0 +1,29 @@
+# Verify EWAI context preparation
+
+This page is for engineers changing the harness's context selection or performance. Run source-checkout commands in the EWAI repository, not your application. For everyday inspection, see [context management](../context-management-and-token-efficiency.md).
+
+## Run the regression corpus
+
+From the EWAI source checkout, run:
+
+```bash
+npm run context:benchmark
+```
+
+The packaged CLI also exposes the same corpus:
+
+```bash
+ewai context benchmark --json
+```
+
+The committed equal-input corpus contains exactly one fixture for each profile. The benchmark fails unless:
+
+- all seven profiles are present and individually ready;
+- every profile retains 100% mandatory recall;
+- median estimated input-demand reduction is at least 40%;
+- median local preparation is no more than 75 ms;
+- aggregate peak RSS growth is no more than 32 MiB.
+
+Run the normal syntax and full test suites as well. The benchmark controls a repeatable local regression surface; provider latency, model quality and production workload performance still need appropriate environment evidence.
+
+Estimated reduction must never be achieved by giving one profile an easier corpus, omitting a profile, suppressing overflow, or weakening mandatory markers.

package/Docs/maintainers/contributing.md

@@ -0,0 +1,58 @@
+# Contributing to EWAI
+
+This page is for engineers changing **the EWAI harness itself**. If you're using it in an application, start with [the installation guide](../operations/installation-updating-and-entitlements.md) instead.
+
+## Work from a source checkout
+
+Use Node.js 22.5 or newer. In your EWAI source checkout, install the locked dependencies and inspect the CLI:
+
+```bash
+npm ci
+node bin/ewai --help
+npm run check
+```
+
+Read the repository instructions and inspect your branch and uncommitted changes before editing. Keep test projects disposable and separate from active customer work. Don't install local changes over a global release as an incidental verification step.
+
+## Development commands
+
+```bash
+npm run build
+npm run check
+npm test
+npm run lint
+npm run typecheck
+```
+
+`npm run build` validates the portable source. Tests cover project discovery, initialisation, non-overwrite behaviour, global and project skill installation, pack and persona discovery, persona-grounded intent creation, SQLite projection, dashboard lifecycle, HTTP serving, and MCP stdio integration.
+
+## Repository layout
+
+```text
+bin/            EWAI CLI entry point
+config/         Schemas and delivery configuration
+packs/          Core, technology, stack, and persona packs
+scripts/        Setup and deterministic build utilities
+skills-src/     Portable agent skill sources
+agents-src/     Host-specific specialist agent definitions
+src/            CLI and runtime source
+templates/      Project output templates
+tests/          Automated tests
+```
+
+The harness's own `SPECS/` workspace is local and excluded from Git. It isn't included in a source checkout or the npm package. Public guides live in `Docs/`; reusable project-output files live in `templates/`. EWAI still creates and uses SPECS when you initialise a project.
+
+
+## Verify the change
+
+Follow [maintainer verification walkthroughs](verification-walkthroughs.md) for the relevant fixtures. A passing unit test, a successful package build and an observed user journey are different kinds of evidence. Record which you actually ran; don't infer a successful installation or human acceptance from a static check.
+
+## Write documentation for the reader
+
+Public operating guides address people using EWAI, including engineers who haven't seen this repository before. Instructions to the host AI belong in `skills-src/` or an explicitly labelled integration reference, not in a user walkthrough.
+
+For a guided task, explain the ordinary conversation or dashboard route before optional commands and schemas. Make clear what the reader supplies or chooses, what EWAI prepares, what they review or approve, and where the result is saved. Include meaningful failure and recovery guidance. Don't require users to perform host duties such as displaying persona metadata or presenting findings “to the owner”.
+
+Keep tutorials, task guides, explanation and technical reference distinct. Preserve exact commands, capabilities, consent and approval boundaries in the appropriate place; don't simplify by removing them. Use natural wording and contractions where they fit, without marketing claims.
+
+Before accepting a documentation change, read the whole changed guide as its intended user and check related pages for conflicting advice. Run `node --test tests/documentation-reader-journeys.test.mjs` for examples, navigation and known audience-regression checks. Those checks supplement editorial review; they can't prove that every sentence is clear or that a real user completed the workflow.

package/Docs/maintainers/evidence-depth-acceptance.md

@@ -0,0 +1,72 @@
+# Accept changes to EWAI evidence-depth behaviour
+
+This is feature acceptance for **EWAI maintainers**, not a requirement for every application team running Archaeology. Use a disposable, privacy-safe fixture. The [operator checklist](../quality/reproducible-archaeology-depth-review-checklist.md) covers reviewing an ordinary investigation.
+
+## Demonstrate reproducibility
+
+For formal Manual QA, use the same repository revision and owner declarations in
+at least three clean sessions:
+
+- [ ] Record the project revision, Source Map run, provider capability, installed persona tiers, and session condition.
+- [ ] Confirm all seven dimensions and their material coverage are equivalent.
+- [ ] Confirm stable gap IDs agree when their structured evidence is unchanged.
+- [ ] Compare the reviewed runs.
+- [ ] Confirm changes are explained in causal order: inputs, evidence, personas, depth, coverage, gaps, then grouping.
+- [ ] Treat wording and ordering differences as non-material when structured evidence agrees.
+- [ ] Treat a gap or coverage change without an upstream cause as unexplained variance and investigate it.
+- [ ] When testing grouping, change only the grouping strategy and confirm gap identity remains stable.
+
+
+
+## Check the interface
+
+At desktop width and 390 px:
+
+- [ ] Open Guided Setup and expand **Depth and evidence** with the keyboard.
+- [ ] Reach every selector, reviewer field, grouping field, and comparison control in a logical order.
+- [ ] Confirm keyboard focus is visible and status does not depend on colour alone.
+- [ ] Confirm dimension coverage, recommendation, selection, and active personas remain readable without horizontal page scrolling.
+- [ ] Confirm the fallback Design System is labelled as not organisation-approved when no approved pack applies.
+- [ ] Confirm advisory and authority notices remain visible.
+- [ ] Ask an owner to explain why each deep dimension is deep and why each active persona is present.
+
+## Stop conditions
+
+Do not approve Manual QA while any of these conditions remains:
+
+- stale or missing Source Map evidence;
+- unexplained comparison variance;
+- an unassigned stable gap;
+- a depth reduction without accountable rationale;
+- a hidden analysis failure, exclusion, contradiction, or unknown surface;
+- a persona presented as stakeholder confirmation or approval;
+- materially weaker engineering coverage than the known-good route;
+- inaccessible or unusable controls in a required viewport;
+- unresolved owner concern about missing or disproportionate content.
+
+## Evidence to retain
+
+- named participants and roles;
+- date, project revision, and safe Source Map run ID;
+- safe reviewed-run IDs and comparison outcome;
+- selected depths and reduction rationale;
+- persona identities, tiers, and engagement reasons;
+- content-quality ratings and owner comments;
+- viewport, keyboard, and accessibility observations;
+- screenshots that contain no sensitive information;
+- defects, corrective action, and retest evidence;
+- final pass or fail decision made through the canonical Manual QA operation.
+
+Do not describe this evidence as security certification, policy compliance,
+production readiness, deployment approval, or release acceptance.
+
+## Related guidance
+
+- [Reproducible Archaeology and Discovery Depth](../reproducible-archaeology-and-discovery-depth.md)
+- [Worked example](../examples/reproducible-archaeology-depth-example.md)
+- [Repository Source Map](../repository-source-map-guide.md)
+- [Guided Discovery facilitator guide](../guided-discovery-facilitator-guide.md)
+- [Manual QA and acceptance](../quality/manual-qa-and-acceptance.md)
+
+
+Keep feature acceptance and a project's investigation review separately labelled. A successful fixture run doesn't establish the quality of every real investigation.

package/Docs/maintainers/verification-walkthroughs.md

@@ -0,0 +1,104 @@
+# Verify changes to EWAI
+
+These checks are for engineers maintaining the EWAI harness. They aren't extra setup or acceptance tasks for someone using EWAI on their own project.
+
+Run the test commands from an EWAI source checkout with its development dependencies installed. They aren't npm scripts to add to a consuming application's package.json. Use disposable projects and synthetic records for failure-injection tests; don't run them against someone's active work.
+
+Automated checks and the manual walkthroughs below cover different things. Passing a suite doesn't mean a human has completed the walkthrough or approved a release.
+
+## Intent Studio
+
+User guide: [Intent Studio](../guided-intent-workspace-guide.md).
+
+Before accepting the feature for release, test it in the browser at desktop width and at 390 px:
+
+1. Create, save, leave, and resume a draft.
+2. Open the same draft in two tabs and confirm a stale save reports a revision conflict.
+3. Discard a draft and confirm no canonical intent was removed.
+4. Move through several sections and confirm the active persona names, tiers, matched signals and engagement reasons change appropriately.
+5. Confirm the Standard host-model baseline remains visible when premium personas are absent.
+6. Complete a new intent, inspect the exact destinations, and confirm unnamed or stale approval cannot materialise it.
+7. Reconcile an eligible draft intent and inspect the before and after comparison.
+8. Confirm an intent with active delivery is not offered for reconciliation.
+9. Copy the AI review hand-off and confirm no draft field or approval state changes.
+10. Confirm the approval copy clearly says it does not approve Build, Manual QA, certification, deployment, or release.
+
+Record the observed evidence through the EWAI Manual QA gate. Automated tests and persona review do not complete that human gate.
+
+## Solution Readiness Review
+
+User guide: [Solution Readiness Review](../solution-readiness-review-guide.md).
+
+Use a disposable initialized project and a real delivery slug.
+
+1. List all five profiles and explain why their requirements differ.
+2. Prepare `internal-only`; open at least three citations and compare their digests and limitations.
+3. Prepare `critical-regulated`; confirm every dimension and named specialist route is visible.
+4. Read **Active personas**. Confirm ID, tier and engagement reason are visible, premium is optional, and no persona is an approver.
+5. Record fixtures producing `ready-for-human-decision`, `conditional`, `blocked` and `insufficient-evidence`.
+6. Try to accept a missing required dimension. Confirm failure with no report written.
+7. Change one cited file, run status, and confirm staleness while the original report remains unchanged.
+8. Confirm every JSON, Markdown, text success and error path carries both notices.
+9. Confirm delivery phase, Build approval, Manual QA, security dispositions and release state did not change.
+
+Record the reviewer, date, environment, assessment IDs and observations in the delivery's Manual QA evidence. Do not approve Manual QA until the human walkthrough is satisfactory.
+
+## Team Hub
+
+User guide: [Team Hub](../team-hub-guide.md).
+
+The repository test suite exercises Team Hub as both a library and an operated service. It includes:
+
+- deterministic two-worker races against independent SQLite connections, proving exact publication becomes one acceptance plus one replay while changed bytes under the same identity produce one stable conflict;
+- late snapshot arrival and process restart, proving every receipt is retained without allowing older evidence to replace the newer portfolio projection;
+- real CLI subprocesses for managed service start, status, stop, contributor connection, publication and resource operations;
+- loopback HTTP authentication, payload limits, invalid envelopes, disabled publishing, service outage and corrupt-storage failure behaviour;
+- a real Chromium journey through the central and local dashboards at a 375-pixel viewport, including keyboard focus, session-only token storage, stale and empty states, exact installation confirmation and authority copy; and
+- an isolated smoke test of the exact `npm pack` artefact, including its installed CLI, managed Team Hub lifecycle and completed-evidence preview.
+
+Maintainers can run the whole suite and the focused transaction/coordination coverage gate with:
+
+```bash
+npx playwright install chromium
+npm test
+npm run test:team-hub:coverage
+```
+
+The focused coverage gate deliberately measures the two coordination-critical modules that own local installation state and the central SQLite ledger. The wider Team Hub service, CLI, package and browser surfaces remain mandatory behavioural tests but are not used to dilute or inflate that transactional percentage.
+
+## Team Hub Resource Registry
+
+User guide: [Team Hub Resource Registry](../team-hub-resource-registry-guide.md).
+
+The mandatory test suite proves exact replay and immutable-identity conflict using two
+independent workers and SQLite connections. It injects failures immediately before the
+installed-state and receipt writes, then verifies the prior active pack, state and
+receipt history are byte-for-byte preserved. It also covers live/dead/malformed leases,
+digest and identity disagreement, invalid JSON, request timeout, outside-owned pack
+collisions, symlink refusal, offline cache replay and safe outage rendering.
+
+The local dashboard test uses Chromium to inspect a release, complete the named human
+confirmation and install the exact digest. This is deliberately a browser journey—not a
+DOM string assertion—because form behaviour, keyboard submission and narrow-layout
+defects only exist in the rendered application.
+
+Run `npm test` for behavioural assurance and `npm run test:team-hub:coverage` for the
+enforced transaction/coordination coverage thresholds. Neither command selects or
+applies the installed resource, approves its organisational use, or replaces Manual QA.
+
+## Completed-phase evidence amendments
+
+User guide: [Completed-phase evidence amendments](../completed-phase-evidence-amendments.md).
+
+EWAI's automated suite invokes the public `ewai delivery evidence-amendment` command in real subprocesses rather than calling only its internal functions. It proves preview, missing-authority refusal, stale-digest refusal, exact ratification, deterministic replay and the final `no-changes` state.
+
+A deterministic two-worker barrier also launches two CLI processes against the same preview at the same moment. A process-owned mutation lease must leave one complete amendment decision, no partial ledger or SQLite state, and only governed replay or bounded in-progress refusal for the competing process. A dead lease owner is recoverable, while a live owner is never displaced. The exact packaged npm CLI repeats the preview against a fixture built with the public delivery APIs, which guards against files being present in the repository but absent or unusable in the published artefact.
+
+Run the relevant assurance directly with:
+
+```bash
+node --test tests/evidence-amendment-cli.test.mjs
+node --test tests/team-hub-package.test.mjs
+```
+
+These tests establish deterministic software behaviour. A named human must still inspect the corrected evidence, reason and preview digest before ratification; the suite cannot supply that authority.

package/Docs/meeting-evidence-implementer-guide.md

@@ -0,0 +1,132 @@
+# Meeting evidence implementer guide
+
+Meeting evidence is a project-local capability built around one domain contract and four adapters: CLI, MCP, loopback HTTP and the Mind Palace UI. The adapters do not implement their own review or promotion rules.
+
+Meeting-platform connectors, recording, transcription, diarisation, OCR and provider-specific model calls aren't part of this implementation.
+
+## Architecture
+
+`src/meeting-evidence.mjs` owns:
+
+- safe registration and private source records;
+- digest freshness and processing policy;
+- contextual persona selection across project, core, installed premium and personal libraries;
+- the host extraction contract;
+- candidate, anchor and named-disposition validation;
+- digest-bound review records;
+- paired evidence persistence, recovery and idempotency;
+- the safe public workspace projection;
+- post-persistence publication of `ewai.meeting-evidence.promoted`.
+
+The configured project root comes from EWAI. Browser and MCP callers cannot send an alternative root.
+
+## Storage model
+
+Private, gitignored runtime records live below:
+
+```text
+.ewai-pipeline/meeting-evidence/
+├── sources/<source-id>.json
+├── reviews/<source-id>.json
+└── transactions/<source-id>.json
+```
+
+The private source record is the only EWAI artefact containing the absolute file path. File mode is `0600`. The raw transcript remains at the user-supplied location and is never copied into the runtime database or SPECS.
+
+Promoted evidence is public project truth:
+
+```text
+<configured SPECS root>/3.Evidence/meeting-evidence/<source-id>/
+├── evidence.json
+└── evidence.md
+```
+
+Both files must exist. The JSON records source and review digests, named review and promotion, accepted/amended candidates, evidence digest and Markdown digest. Markdown includes the authority and security notices.
+
+## Domain operations
+
+| Function | Mutates | Boundary |
+| --- | --- | --- |
+| `registerMeetingSource` | Private source record | Explicit confirmation, regular supported file, no symlink/traversal, limits and policy |
+| `prepareMeetingExtraction` | Nothing | Current digest; denied/unknown processing returns manual-local route |
+| `recordMeetingReview` | Private review record | Strict allowlist, anchors in range, every candidate disposed exactly once, named reviewer |
+| `promoteMeetingEvidence` | Paired SPECS evidence and safe lifecycle event | Exact confirmation, named approver, current source/review digests, accepted/amended evidence only |
+| `readMeetingEvidenceWorkspace` | Nothing | Safe source, candidate, disposition, receipt and active-persona projection |
+
+An interrupted JSON-first write removes both targets and its staging journal. A later identical approved request is idempotent even when the retry time differs. A materially different source, review, approver or evidence set conflicts rather than overwriting the existing record.
+
+## CLI
+
+```bash
+ewai meeting register FILE --yes [--label NAME] [--classification CLASS] [--cloud-processing POLICY] --project . --json
+ewai meeting prepare SOURCE_ID [--focus TEXT] --project . --json
+ewai meeting review SOURCE_ID --input FILE --reviewed-by NAME --project . --json
+ewai meeting promote SOURCE_ID --yes --approved-by NAME --project . --json
+ewai meeting status [SOURCE_ID] [--focus TEXT] --project . --json
+```
+
+Review input must resolve inside the project. JSON errors include the mandatory assurance notice and must not echo raw source content or a private path.
+
+## MCP
+
+The stdio server exposes:
+
+- `ewai_meeting_status` as read-only;
+- `ewai_meeting_register` as a confirmed non-destructive mutation;
+- `ewai_meeting_prepare` as read-only;
+- `ewai_meeting_review` as a non-destructive mutation;
+- `ewai_meeting_promote` as a confirmed non-destructive mutation.
+
+Schemas constrain classifications, processing policy, candidates, anchors and dispositions before the domain validates them again. No tool accepts a project-root argument.
+
+## HTTP and UI
+
+The loopback server provides:
+
+- `GET /api/meeting-evidence?source=<id>`;
+- `POST /api/meeting-evidence/<id>/prepare`;
+- `POST /api/meeting-evidence/<id>/promote`.
+
+The server uses its configured root and rejects unknown query/body fields. Promotion revalidates confirmation and the named approver. Error responses include the exact mandatory assurance notice.
+
+Meeting evidence is a secondary mode inside Mind Palace, not a primary-navigation item. The browser escapes all safe fields. It has no upload control, review authoring, raw source preview, connector, transcription control, downstream canonical authoring or release action. At 960px the ledger and context rail stack; at 600px candidates and receipts become a single reading column. Existing focus-visible and reduced-motion rules apply.
+
+## Persona contract
+
+The standard host model and the installed project/core ensemble are sufficient. Premium and personal personas are optional enrichment only when already installed and contextually relevant. The active persona projection exposes name, tier, matched signals and engagement reason, never managed persona bodies.
+
+Preparation selects a fresh ensemble for its source and focus. Implementers must replace, not accumulate, that set when context changes. No persona can establish a fact, complete named review, approve promotion or satisfy Manual QA.
+
+## Lifecycle integration
+
+After both evidence files exist, EWAI safely publishes `ewai.meeting-evidence.promoted` with only:
+
+- `sourceId`;
+- `evidenceDigest`;
+- `candidateCount`;
+- `approvedAt`.
+
+The event references the two project-relative evidence paths. It contains no transcript text, source path, reviewer prompt or raw model output. Handler failure cannot veto, delete or roll back canonical evidence; delivery can be inspected and retried through the generic lifecycle-hook system.
+
+## Extension boundary
+
+External systems should subscribe through generic lifecycle hooks or call the published CLI/MCP contract. Do not add a vendor-specific connector to the domain module. If a future importer supplies transcripts, it must first materialise a supported local file and obtain the same explicit registration and processing decision.
+
+Keep future candidate schema revisions versioned and fail closed on unknown fields. Add tests for redaction, drift, transaction interruption, retry behaviour, annotations, project-root isolation and responsive no-preview behaviour.
+
+Registration and validation aren't evidence that a transcript's claims are true. Integrations must preserve source permissions, complete named review and separate promotion approval rather than treating generated candidates as accepted project knowledge.
+
+## Contract sources
+
+- `src/meeting-evidence.mjs`
+- `config/meeting-evidence-candidate.schema.json`
+- `src/runtime/lifecycle-hooks.mjs`
+- `src/runtime/mcp-server.mjs`
+- `src/runtime/dashboard-server.mjs`
+- `public/index.html`
+- `public/app.js`
+- `public/styles.css`
+- `tests/meeting-evidence.test.mjs`
+- `tests/meeting-evidence-cli.test.mjs`
+- `tests/lifecycle-hook-emissions.test.mjs`
+- `tests/runtime.test.mjs`