@thebackstoryis/engineering-with-ai 0.2.9

package/Docs/blueprints/validation-and-troubleshooting.md

@@ -0,0 +1,168 @@
+# Blueprint validation and troubleshooting
+
+Use this guide to diagnose an Organisation Blueprint Pack that is missing, rejected, incomplete, or unable to materialise during Discovery.
+
+Start with the full [Blueprint design guide](../designing-organisation-blueprint-packs.md) if you have not yet authored a strict `ewai.pack/v1` manifest.
+
+## Diagnose the failing layer
+
+Work from discovery toward application:
+
+1. **Discovery:** Is the pack stored under a supported local root?
+2. **Manifest parsing:** Is the YAML valid and the root object complete?
+3. **Strict schema:** Are all required fields present and all undeclared fields absent?
+4. **Resolution:** Are identity, compatibility, dependencies, and selected modules valid?
+5. **Content:** Are referenced Markdown files safe, bounded, and readable?
+6. **Review:** Does the preview show the intended modules and outputs?
+7. **Application:** Are there destination conflicts or a stale review revision?
+8. **Drift:** Does the project pin still match the installed pack content?
+
+Fix the earliest failing layer first. Later errors may be consequences rather than separate defects.
+
+For a missing pack, correct its [installation root](#confirm-the-installation-root) and reopen selection. For a rejected pack, fix the specific manifest/content error in the candidate and resolve it again. For a stale preview, preserve any unsaved decisions, prepare a fresh preview and obtain a new approval. For destination conflicts, inspect the existing files rather than using overwrite flags.
+
+Resolver checks in a disposable project validate your pack. Running EWAI's full regression suite is a separate harness-maintainer task, not a requirement for every pack consumer.
+
+## Confirm the installation root
+
+EWAI discovers local Organisation Blueprint Packs from:
+
+1. the package `packs/` root;
+2. the user's `~/.ewai/packs/` root;
+3. the project's `.ewai-pipeline/packs/` root.
+
+The project root is resolved from its locator; do not assume that the configured SPECS directory is `./SPECS`.
+
+There is no dedicated public `blueprint validate` command in the current CLI. Validate through Guided Setup in a safe test project and, for maintained packs, add resolver-level tests using the repository's organisation-blueprint test patterns.
+
+## Strict manifest failures
+
+The organisation manifest is strict. Common failures include:
+
+| Failure | Check |
+| --- | --- |
+| Unsupported schema | Root `schema` must be `ewai.pack/v1`. |
+| Wrong pack type | Root `type` must be `organisation`. |
+| Invalid identity | Use a publisher-scoped lowercase pack ID and matching `blueprint.publisher.id`. |
+| Missing version | Provide a valid pack `version` and a compatibility range. |
+| Unknown field | Remove fields not declared by the V1 schema; keep catalogue metadata outside the strict manifest. |
+| Duplicate module ID | Give every module a stable unique ID. |
+| Invalid Source Map profile | Use a registered analyser, safe patterns and supported data-only fields; don't include commands or executable paths. |
+| Invalid source | Standard and persona entries must reference bounded relative Markdown paths. |
+
+Empty content arrays are permitted in a module. As an authoring choice, give each required module a clear purpose; that recommendation isn't a schema requirement for a minimum number of standards or personas.
+
+Do not “fix” strict validation by weakening the schema or adding an ignore flag. The strict surface protects portability and makes the digest meaningful.
+
+## Identity and compatibility
+
+Check these values together:
+
+- pack `id`;
+- pack `version`;
+- `blueprint.publisher.id`;
+- `blueprint.publisher.name`;
+- `blueprint.compatibility.ewai`.
+
+If the compatibility range excludes the current EWAI version, update the pack only after confirming the current runtime contract. Do not widen the range merely to suppress the error.
+
+## Dependency failures
+
+`requires` lists organisation pack IDs, not per-dependency version ranges. Each required pack must be installed and compatible with the running EWAI major version. The reviewed pack content and digests identify the actual inputs.
+
+Check for:
+
+- a missing dependency pack;
+- a dependency whose `blueprint.compatibility.ewai` doesn't match the running EWAI major version;
+- circular dependencies;
+- two locally installed packs with confusing or colliding identities;
+- content collisions after dependency modules are combined.
+
+Optional module choice applies to the selected root pack. Dependency modules are requirements, not an opportunity for the consuming project to silently weaken the dependency contract.
+
+## Path and content safety failures
+
+All referenced content must remain inside its pack. Reject:
+
+- absolute paths;
+- `..` traversal outside the pack;
+- symbolic links that escape the real pack directory;
+- non-Markdown standard or persona sources;
+- missing or unreadable files;
+- oversized content.
+
+Current bounds are:
+
+- 256 KiB per manifest;
+- 1 MiB per referenced content file;
+- 5 MiB of referenced content per pack;
+- eight directory levels when discovering manifests, not eight dependency levels.
+
+Split genuinely separate concerns into modules instead of raising limits or hiding large reference material inside a standard.
+
+## Digest surprises
+
+The deterministic digest changes when resolved material changes, including relevant manifest data, selected content, dependencies, or modules.
+
+If a digest changes unexpectedly:
+
+1. compare the installed pack with the reviewed source revision;
+2. check dependency versions and content;
+3. confirm the selected optional modules;
+4. inspect line-ending or content changes in referenced Markdown;
+5. do not reuse an old approval against the new digest.
+
+The digest identifies reviewed inputs; it is not a publisher signature or malware scan.
+
+## Preview and application failures
+
+Guided Setup separates preview from named approval. A preview can fail because required Discovery answers are incomplete. Application can then fail because:
+
+- a newer draft revision exists;
+- generated destinations already exist;
+- a selected pack or module changed after Review;
+- the approver name or confirmation is missing;
+- a write failed and the transaction rolled back.
+
+Do not delete destination files just to make the transaction pass. Compare them with the proposed output and decide whether to retain, migrate, or supersede the existing project truth.
+
+## Drift after application
+
+The project receipt and pipeline pin preserve the accepted pack ID, version, modules, digest, approver, and time. An upstream pack change does not automatically rewrite the project.
+
+When drift is reported:
+
+1. retain the existing project files;
+2. locate the exact installed version and digest;
+3. review the newer pack and release notes;
+4. compare materialised standards and personas;
+5. decide whether to adopt, defer, or reject the change;
+6. record the new project decision.
+
+## Minimal diagnostic record
+
+Capture:
+
+- pack root and manifest path;
+- pack ID, version, publisher, and compatibility;
+- selected modules and dependencies;
+- error text and failing layer;
+- current and expected digest where available;
+- destination conflicts;
+- recovery decision and owner.
+
+Do not include proprietary content or secrets in a public issue report.
+
+## Related guides
+
+- [Designing Organisation Blueprint Packs](../designing-organisation-blueprint-packs.md)
+- [Maintaining Organisation Blueprints](maintaining-organisation-blueprints.md)
+- [Troubleshooting and recovery](../operations/troubleshooting-and-recovery.md)
+
+## Current contract sources
+
+- `src/organisation-blueprints.mjs`
+- `src/discovery.mjs`
+- `config/pack.schema.json`
+- `tests/organisation-blueprints.test.mjs`
+- `tests/discovery.test.mjs`

package/Docs/cli-reference.md

@@ -0,0 +1,113 @@
+# Operational CLI reference
+
+For installation, personas, delivery and the full command-family map, use the [CLI and configuration reference](reference/cli-and-configuration.md). This page covers the detailed error-report and Team Hub commands.
+
+This quick reference covers local error reports and the optional self-operated Team Hub. No paid service or vendor connector is required for either capability. Use `--json` for machine-readable output and `--project PATH` when not running at the project root.
+
+## Local lifecycle
+
+```bash
+ewai error-report status [--status draft|finalised|archived] --project . --json
+ewai error-report create \
+  --capability guided-discovery \
+  --error-code EWAI-DISCOVERY-INVALID \
+  --command "ewai discover" \
+  --installation-source npm \
+  --title "Discovery did not validate" \
+  --expected "A valid project brief" \
+  --actual "Validation stopped" \
+  --step "Run guided discovery" \
+  --project . --json
+ewai error-report show REPORT --project . --json
+ewai error-report update REPORT --title TEXT --expected TEXT --actual TEXT --step TEXT --project . --json
+ewai error-report finalise REPORT --project . --json
+```
+
+EWAI supplies its version, Node version and operating-system class itself. The create command accepts only bounded safe fields; it does not accept raw logs, environment dumps, source or arbitrary attachments.
+
+## Email handoff
+
+```bash
+ewai error-report prepare-email REPORT \
+  --expected-digest sha256:... \
+  [--recipient support@example.com] \
+  [--launch] \
+  --project . --json
+```
+
+`--launch` asks the operating system to reveal the ZIP and open the default email client. The returned state remains `prepared-not-sent`; attach the ZIP manually and send it yourself.
+
+## Provider handoff
+
+```bash
+ewai error-report providers --project . --json
+ewai error-report adapter-validate FOLDER --project . --json
+ewai error-report adapter-register FOLDER --yes --project . --json
+ewai error-report send REPORT --provider ID --expected-digest sha256:... --yes --project . --json
+ewai error-report receipts REPORT --project . --json
+```
+
+Adapters are generic trusted local code. Registration does not execute them. `send` requires the exact finalised digest and explicit confirmation. Accepted receipts prove transport only.
+
+## Settings and local retention
+
+```bash
+ewai error-report settings --project . --json
+ewai error-report settings --automatic-local-drafts true --project . --json
+ewai error-report settings --support-email support@example.com --project . --json
+ewai error-report archive REPORT --yes --project . --json
+ewai error-report delete REPORT --yes --project . --json
+```
+
+Automatic capture is local-only. Archive and delete affect local material only; they cannot recall email or provider data.
+
+## Team Hub contributor lifecycle
+
+```bash
+ewai team status --project . --json
+ewai team disclosure --project . --json
+ewai team connect https://hub.example.org --project-id example --token-env EWAI_TEAM_HUB_TOKEN --acknowledge-disclosure --yes --project . --json
+ewai team sync --yes --project . --json
+ewai team resources --project . --json
+ewai team resource inspect org.example.baseline 1.2.0 --project . --json
+ewai team resource install org.example.baseline 1.2.0 --expected-digest sha256:<digest> --approved-by "Named owner" --yes --project . --json
+ewai team resource receipts --project . --json
+ewai team disconnect --yes --project . --json
+```
+
+Connection stores no token value and sends nothing. `sync` is the explicit publication boundary.
+
+## Team Hub service lifecycle
+
+```bash
+ewai team-hub start --data /srv/ewai-team-hub --token-env EWAI_TEAM_HUB_TOKEN --publisher-token-env EWAI_TEAM_HUB_PUBLISHER_TOKEN --json
+ewai team-hub status --data /srv/ewai-team-hub --json
+ewai team-hub stop --data /srv/ewai-team-hub --json
+ewai team-hub resource publish ./organisation-blueprint --data /srv/ewai-team-hub --publisher-token-env EWAI_TEAM_HUB_PUBLISHER_TOKEN --yes --json
+```
+
+A non-loopback bind also requires `--allow-network`. Shared deployment requires an organisation-managed TLS reverse proxy. The publisher credential is optional and must differ from the reader credential. See the [Team Hub guide](team-hub-guide.md) for disclosure, backup, recovery and authority boundaries, and the [Team Hub Resource Registry guide](team-hub-resource-registry-guide.md) for immutable resource publication and exact-digest installation.
+
+## Completed delivery evidence
+
+Preview a narrow amendment when a completed phase references evidence that was legitimately regenerated or corrected:
+
+```bash
+ewai delivery evidence-amendment <slug> --project . --json
+```
+
+Apply only the exact previewed substitutions with named human authority:
+
+```bash
+ewai delivery evidence-amendment <slug> --project . --yes \
+  --approved-by "Name or role" \
+  --reason "Reason for the correction" \
+  --expected-state-digest <preview-stateSha256> \
+  --json
+```
+
+This does not reopen the phase or approve Manual QA. It refuses a directly edited completed gate ledger and writes an immutable receipt. See [Completed-phase evidence amendments](completed-phase-evidence-amendments.md).
+
+## Choose the correct evidence amendment
+
+Use [Which amendment operation?](completed-phase-evidence-amendments.md#which-amendment-operation) to distinguish pre-Build `ratify-amendments` from `evidence-amendment` for stale nested evidence references. They aren't interchangeable, and neither supplies approval to implement or release.

package/Docs/completed-phase-evidence-amendments.md

@@ -0,0 +1,74 @@
+# Completed-phase evidence amendments
+
+EWAI treats a completed phase gate as durable delivery authority. If a referenced evidence file is legitimately corrected after phase completion, the delivery must not silently accept the new bytes and an operator must not edit the gate ledger by hand. The completed-phase evidence amendment command provides a narrow, reviewed recovery path.
+
+This capability does not reopen the completed phase, repeat its Build approval, move the delivery, waive a gate, or approve Manual QA. It only replaces stale nested evidence hashes in an otherwise unchanged completed gate ledger, validates the resulting candidate with the normal deterministic phase checker, and records an immutable receipt.
+
+## Which amendment operation?
+
+| Situation | Operation | What it changes |
+| --- | --- | --- |
+| Approved pre-Build evidence and its completed gate ledgers have been amended; you're at Build before authorising implementation | `delivery ratify-amendments` | Revalidates completed pre-Build gates and records their updated fingerprints. See [Build approval operations](developer-delivery-guide.md#preserve-the-build-approval-boundary). |
+| A referenced evidence file was corrected after phase completion, but the completed gate ledger itself is unchanged | `delivery evidence-amendment` | Previews and replaces only stale nested evidence hashes, subject to the original checker. Follow the steps below. |
+
+Neither operation can turn failed evidence into a pass, rewrite outcomes or supply Build approval. Inspect which operation failed and what changed before choosing a recovery route. If the condition doesn't match either row, stop and investigate.
+
+## When to use it
+
+Use it only when all of these are true:
+
+- the phase is already completed;
+- the gate ledger itself is unchanged from the digest stored in `delivery-state.json`;
+- one or more evidence files referenced by passing gate items were corrected or regenerated;
+- the corrected evidence still passes the canonical deterministic gate contract; and
+- a named person is prepared to ratify the exact previewed changes.
+
+Do not use it to alter a gate result, conceal failed evidence, change an approval, reopen delivery work, or satisfy Manual QA. If the completed ledger itself changed, EWAI refuses the amendment and the delivery requires a different governed decision.
+
+## Preview first
+
+```sh
+ewai delivery evidence-amendment <slug> --project . --json
+```
+
+The preview is read-only. It returns:
+
+- `deliveryStateSha256`: the digest of the current durable state file;
+- `stateSha256`: an amendment revision digest binding the durable state and exact proposed hash substitutions;
+- each affected phase and gate item;
+- the previous and current evidence hashes; and
+- no evidence bodies or absolute filesystem paths.
+
+Review the named paths and hashes. If anything changes after preview, the apply operation will reject the stale digest.
+
+## Ratify the exact preview
+
+```sh
+ewai delivery evidence-amendment <slug> \
+  --project . \
+  --yes \
+  --approved-by "Name or accountable role" \
+  --reason "Why the completed evidence was corrected" \
+  --expected-state-digest <stateSha256-from-preview> \
+  --json
+```
+
+On success, EWAI:
+
+1. confirms the original completed gate ledger still matches durable state;
+2. rebuilds only the stale nested evidence hashes;
+3. runs the canonical deterministic phase validator against the candidate ledger;
+4. atomically updates the ledger, durable state, intent copies, and SQLite projection; and
+5. writes an immutable receipt under `SPECS/6.Build/<slug>/evidence-amendments/`.
+
+The receipt is deterministic for the slug, preview digest, approver, and reason. Repeating the exact successful command returns the existing receipt rather than creating a second decision.
+
+## Failure and recovery behaviour
+
+The amendment is all-or-nothing. If any write or projection update fails, EWAI restores the prior gate ledger, durable state, intent copies, operational projection, and receipt directory. Run the preview again after resolving the cause.
+
+After a successful ratification, retry the originally blocked guarded operation. The next phase still starts only when every completed gate is fresh and the normal phase-order rules permit it.
+
+## For EWAI maintainers
+
+The [maintainer verification notes](maintainers/verification-walkthroughs.md#completed-phase-evidence-amendments) cover CLI, concurrency and package tests. They aren't additional commands an operator must run to ratify corrected evidence.

package/Docs/consultancy-network-rollout-control-plane-guide.md

@@ -0,0 +1,202 @@
+# Review EWAI adoption across projects
+
+Use **Governed Rollout** to see which projects use your organisation's agreed setup, which need reviewing and who should follow up. It compares the Organisation Blueprint each project has adopted with the version you've agreed for its group. A Blueprint is a bundle of reusable standards and guidance; a group of projects sharing an expected setup is called a **cohort** in the configuration.
+
+The view also shows whether required evidence is present and current. It doesn't judge whether that evidence is good enough: the named reviewer still needs to read it. Relevant personas help that reviewer identify questions worth asking. The CLI and technical references call this capability the **Rollout Control Plane**.
+
+It does not centralise client repositories, replace project governance, modify any child project, or issue an assurance verdict.
+
+
+<!-- editorial: contents -->
+## On this page
+
+- [Read presence separately from quality](#read-presence-separately-from-quality)
+- [What it produces](#what-it-produces)
+- [Prerequisites](#prerequisites)
+- [Supported repository topologies](#supported-repository-topologies)
+- [Define the policy](#define-the-policy)
+- [Blueprint adoption is exact](#blueprint-adoption-is-exact)
+- [Validate and review](#validate-and-review)
+- [Evidence and interpretation](#evidence-and-interpretation)
+- [Standard LLM and personas](#standard-llm-and-personas)
+- [Isolation and redaction](#isolation-and-redaction)
+- [Recovery](#recovery)
+- [Human authority and mandatory notices](#human-authority-and-mandatory-notices)
+
+## Read presence separately from quality
+
+Here, **structural evidence** means that a record is present, has the expected shape and refers to the expected project/version. It doesn't mean the plan is sound, the implementation is safe or the client accepted it. Open material evidence in the owning project and ask the accountable reviewer to judge it.
+
+## What it produces
+
+`ewai rollout status` returns an `ewai.rollout-workspace/v1` snapshot containing:
+
+- the rollout, Portfolio, cohorts, baselines, assignments, owners, and review dates;
+- exact Blueprint adoption states: `aligned`, `review-required`, `not-adopted`, `unavailable`, `stale`, or `invalid`;
+- structural state for required `blueprint`, `delivery`, `standards`, `manual-qa`, and `security` evidence;
+- a selected-project assurance view that is structural-only and has no adequacy verdict;
+- safe next-action routing to named owners;
+- standard LLM review questions and the active personas, tiers, matched signals, and engagement reasons; and
+- mandatory advisory and security notices.
+
+The dashboard presents the same read-only ledger and focused project context. The CLI, HTTP API, MCP tool, and dashboard share one server-side projection rather than reimplementing rollout logic.
+
+## Prerequisites
+
+Before configuring rollout:
+
+1. initialise the host as an EWAI project;
+2. configure repository topology in `SPECS/pipeline.yaml`;
+3. create a valid `SPECS/1.Scope/portfolio.yaml` whose project members have stable IDs and named owners; and
+4. ensure each readable child is itself an EWAI project if you expect Blueprint or delivery evidence from it.
+
+The Rollout policy refers only to Portfolio project IDs. It does not repeat repository paths.
+
+## Supported repository topologies
+
+Topology belongs to `pipeline.yaml` and Portfolio configuration, not `rollout.yaml`.
+
+### Single repository
+
+The host repository can also be the only project. Configure the repository root as `.` and give its Portfolio project member a stable ID. Assign that ID to a rollout cohort.
+
+### Monorepo
+
+Register safe subpaths such as `services/api` and `apps/web` in `SPECS/pipeline.yaml`. Portfolio project members select the configured repository and, when needed, a bounded project path. Rollout assignments still use only the member IDs.
+
+### Folder with repository subfolders
+
+A host folder can coordinate Git repository subfolders such as `clients/alpha` and `clients/beta`. Register every allowed repository root in `SPECS/pipeline.yaml`, then map each Portfolio project to one of those names. The Rollout reader never discovers arbitrary sibling folders.
+
+### Several separately configured repositories
+
+Where the host configuration already names several allowed repositories, Portfolio provides the safe project mapping and Rollout consumes that resolution. An unavailable repository is reported as `unavailable`; Rollout does not fetch, clone, authenticate, or repair it.
+
+See [Project and Portfolio Orchestration](project-portfolio-orchestration-guide.md) for complete topology examples.
+
+## Define the policy
+
+Create `SPECS/1.Scope/rollout.yaml` beneath the configured SPECS root:
+
+```yaml
+schema: ewai.rollout/v1
+id: client-delivery-rollout
+name: Client delivery rollout
+owner: Network Delivery Director
+stale_after_days: 30
+baselines:
+  - id: regulated-web-baseline
+    name: Regulated web baseline
+    owner: Architecture Council
+    pack:
+      id: org.example.regulated-web
+      version: 2.1.0
+      digest: sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
+cohorts:
+  - id: autumn-adoption
+    name: Autumn adoption cohort
+    baseline: regulated-web-baseline
+    owner: Cohort Lead
+    review_by: 2026-10-31
+    required_evidence:
+      - blueprint
+      - delivery
+      - standards
+      - manual-qa
+      - security
+    projects:
+      - id: client-portal
+        owner: Client Portal Owner
+        review_owner: Assurance Lead
+```
+
+The schema permits at most 25 baselines, 50 cohorts, and 100 unique project assignments. A project can belong to one cohort only. Every baseline, cohort, assignment, and review route needs a named owner.
+
+## Blueprint adoption is exact
+
+The checker compares the exact Blueprint ID and version, plus the digest when the baseline declares one. It does not infer semantic-version precedence or compatibility:
+
+- exact match: `aligned`;
+- different ID, version, or required digest: `review-required`;
+- no project-owned Blueprint pin: `not-adopted`.
+
+A difference may be intentional, safe, unsafe, or mid-migration. Only the named review owner can decide that; the control plane identifies the decision rather than making it.
+
+## Validate and review
+
+```bash
+ewai rollout validate --project . --json
+ewai rollout status --project . --json
+ewai rollout status --focus "projects with stale Manual QA evidence" --project . --json
+ewai rollout assurance client-portal --project . --json
+```
+
+- `validate` checks the policy and Portfolio membership without changing either.
+- `status` returns the bounded whole-rollout workspace.
+- `status --focus` reruns contextual persona selection for the stated concern.
+- `assurance PROJECT_ID` returns the same safe workspace with a structural selected-project view.
+
+The equivalent MCP operation is `ewai_rollout_status` with optional `focus` and `projectId`. The HTTP surfaces are `GET /api/rollout` and `GET /api/rollout/projects/:projectId/assurance`. None accepts a repository-root override or mutation.
+
+Start or reuse the dashboard with:
+
+```bash
+ewai dashboard --project .
+```
+
+Enable **Governed Rollout** in **Configuration** and save, then open it to inspect cohort progress, choose a baseline or cohort, and focus a project. See [dashboard configuration](operations/dashboard-configuration.md). The UI identifies the active personas and displays both authority notices.
+
+## Evidence and interpretation
+
+Keep these classes separate:
+
+| Evidence class | Use |
+| --- | --- |
+| `declared-policy` | The governed baseline, cohort, assignment, evidence requirement, or owner. |
+| `observed-project-evidence` | Allowlisted structural evidence read from a child project. |
+| `automated-check` | Exact Blueprint comparison or deterministic freshness state. |
+| `persona-hypothesis` | A concern or possible consequence raised by a persona lens. |
+| `human-decision` | An actual named human decision within its recorded authority. |
+
+The evidence checks are intentionally structural. Standards `present` means standards files were observed, not that they are adequate. Security evidence exposes configuration and run state, not findings or certification. Manual QA exposes the named-human gate state, not acceptance of a different release.
+
+## Standard LLM and personas
+
+The standard host LLM can perform the complete bounded review. Installed project and core personas can sharpen the baseline analysis. Premium and personal personas are optional: when already installed and relevant, they can join the active ensemble.
+
+Every focused review shows each active persona's name, tier, matched signals, and engagement reason. Change the focus or selected project and refresh the snapshot so EWAI can swap lenses in and out. A premium persona that is absent is never approximated or treated as a blocker, and this feature does not trigger premium installation or synchronisation.
+
+Personas can identify questions and possible blind spots. They cannot impersonate a client, create stakeholder evidence, approve adoption, judge evidence adequacy, accept risk, or replace the named reviewer.
+
+## Isolation and redaction
+
+The public projection exposes stable IDs and bounded structural facts. It excludes:
+
+- absolute roots and unrestricted repository content;
+- raw rollout, Blueprint, intent, persona, test, security, or approval documents;
+- prompts, credentials, tokens, adapter entrypoints, and validator output;
+- detailed security findings, dispositions, accepted risk, and release authority.
+
+Unknown query parameters, unsafe focus values, unknown project IDs, symbolic policy files, excessive files, and topology escapes fail closed with stable errors and both notices.
+
+## Recovery
+
+| State | What it means | Next action |
+| --- | --- | --- |
+| `not-configured` | No rollout policy exists. | Ask the rollout owner whether one should be created. |
+| `invalid` | Policy, Portfolio, topology, or project evidence cannot be safely interpreted. | Fix the reported source contract; do not override the result. |
+| `unavailable` | The configured child root or evidence cannot be read. | Route topology to the Portfolio owner and project access to the project owner. |
+| `stale` | Delivery evidence is older than `stale_after_days`. | Ask the project owner to refresh project-owned evidence through its normal workflow. |
+| `not-adopted` | No exact project Blueprint pin exists. | Ask the project owner and cohort owner whether adoption is intended. |
+| `review-required` | The project pin differs from the exact baseline. | Route compatibility or migration judgement to the named review owner. |
+| evidence `missing` or `not-configured` | A required class has no qualifying structural evidence. | Use its limitation and owner route; do not reinterpret absence as success. |
+
+Rollout remains read-only during recovery. Make any approved correction in the canonical host or child project, then request a fresh snapshot.
+
+## Human authority and mandatory notices
+
+The control plane does not approve Build or Manual QA, accept risk, certify security, decide Blueprint compatibility, dispatch work, alter project state, deploy, or release. Those decisions remain with the named accountable people in the relevant project and governance process.
+
+> Rollout and persona analysis is advisory. Organisation Blueprint adoption, evidence adequacy, accepted risk, Manual QA, deployment and release decisions remain with named accountable humans.
+
+> Security validation is evidence, not certification or proof that this system is secure. Tools can miss vulnerabilities and produce false positives. A qualified human must review the scope, findings, limitations and residual risk before release.