@thebackstoryis/engineering-with-ai 0.2.9

package/Docs/governed-starter-project-materialisation-guide.md

@@ -0,0 +1,284 @@
+# Governed Starter-Project Materialisation
+
+Governed Starter-Project Materialisation turns an accepted Organisation Blueprint receipt into an immutable preview and, after named human approval, adds missing project files. It supports a single repository, a monorepo, and a workspace containing several independent Git repositories.
+
+The capability is additive-only. It never overwrites, merges, deletes, or forces an existing destination.
+
+> A starter source adapter is trusted local code. EWAI runs it with the invoking user's permissions and does not OS-sandbox it. EWAI independently verifies its staged output. The result is evidence, not security certification, code-quality approval, licence approval, business acceptance, or release approval.
+
+
+<!-- editorial: contents -->
+## On this page
+
+- [Use a supplied adapter](#use-a-supplied-adapter)
+- [Keep four concepts separate](#keep-four-concepts-separate)
+- [End-to-end flow](#end-to-end-flow)
+- [Define a Starter Pack in a Blueprint](#define-a-starter-pack-in-a-blueprint)
+- [Calculate the canonical digest](#calculate-the-canonical-digest)
+- [Configure repository topology](#configure-repository-topology)
+- [Implement a generic source adapter](#implement-a-generic-source-adapter)
+- [Validate and register an adapter](#validate-and-register-an-adapter)
+- [Prepare, review, and apply](#prepare-review-and-apply)
+- [Understand classifications](#understand-classifications)
+- [Persona engagement and human authority](#persona-engagement-and-human-authority)
+- [Evidence and lifecycle handoff](#evidence-and-lifecycle-handoff)
+- [Recovery](#recovery)
+- [Implementer checklist](#implementer-checklist)
+- [Related guides](#related-guides)
+
+## Use a supplied adapter
+
+Before starting, obtain the approved adapter package and starter receipt from its owner. EWAI doesn't ship a downloader for every source service. You'll need the accepted Blueprint, a current starter receipt and repository target mappings.
+
+For operation, follow [repository topology](#configure-repository-topology), [validate and register](#validate-and-register-an-adapter), then [prepare, review and apply](#prepare-review-and-apply). Preview runs the trusted adapter to obtain staging files; application is the separate approved step that adds them to repositories.
+
+If you're creating the reusable starter definition or writing the adapter, use the authoring sections below. Their code and configuration aren't extra prerequisites to implement yourself when an approved package has already been supplied.
+
+## Keep four concepts separate
+
+| Concept | What it owns | What it does not own |
+| --- | --- | --- |
+| Organisation Blueprint Pack | Organisation standards, persona templates, and Governed Starter Pack receipts | Project-specific repository placement or technology selection |
+| Governed Starter Pack | Versioned source identity, licence, compatibility, logical target roles, and one canonical aggregate digest | Credentials, provider integration, destination roots, or approval |
+| Technology Stack | Framework and platform guidance, constraints, commands, and patterns | Starter source provenance or local repository topology |
+| Repository Topology | Named local Git repositories and the destination path for each logical target role | Pack content, fetching, or technology policy |
+
+A Blueprint may recommend both a technology stack and a Starter Pack, but they remain independently reviewable decisions. A team can change its stack guidance without silently changing its starter content, or use the same starter across different repository layouts.
+
+## End-to-end flow
+
+1. An organisation publishes a reviewed Blueprint containing one or more `starter_packs` receipts.
+2. Guided Discovery resolves the Blueprint, materialises its standards and project personas, and records the accepted immutable receipt.
+3. The project maps every Starter Pack logical role to one configured repository and relative destination path.
+4. A technical operator validates and explicitly registers an organisation-owned source adapter.
+5. EWAI runs that trusted adapter only against a bounded staging directory.
+6. EWAI independently inventories the staged regular files and verifies the accepted digest.
+7. EWAI binds the receipt, adapter, topology, Git revisions, staged tree, destination classifications, and expiry into one immutable preview.
+8. The dashboard or CLI shows safe per-target `create`, `identical`, and `conflict` counts and the actively engaged personas.
+9. A named person approves the current preview.
+10. EWAI revalidates every bound input, creates only missing files, persists canonical evidence, then emits a non-authoritative lifecycle event.
+
+Preview does not change application repositories. Approval expires after 30 minutes. Drift or conflict requires a fresh preview.
+
+## Define a Starter Pack in a Blueprint
+
+Use `starter_packs`, not the legacy `boilerplates` field, for new packs:
+
+```yaml
+modules:
+  - id: application-foundation
+    name: Application foundation
+    description: Organisation-owned starting content for the application.
+    required: true
+    standards: []
+    personas: []
+    starter_packs:
+      - id: service-platform
+        name: Service platform
+        source: https://source.example.invalid/service-platform-4.2.0.tar.gz
+        version: 4.2.0
+        digest: sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+        licence: Apache-2.0
+        compatibility: EWAI 0.x; Node 22; deployment target reviewed separately
+        targets:
+          - role: api
+            source_path: services/api
+          - role: web
+            source_path: clients/web
+```
+
+Every target needs a unique lowercase `role` and a non-overlapping relative `source_path`. The adapter writes the complete staged output using those source paths. Files outside exactly one declared target are rejected.
+
+Legacy `boilerplates` remain readable as a one-role `application` receipt for compatibility. They should be migrated to explicit `starter_packs` before adding multi-target content.
+
+## Calculate the canonical digest
+
+Build the exact logical target folders locally, then run:
+
+```bash
+ewai starter digest api=./reviewed/services/api web=./reviewed/clients/web --json
+```
+
+The returned aggregate `digest` belongs in `pack.yaml`. Each target is independently canonicalised before the role and target digest are combined. The calculation rejects:
+
+- symbolic links, hard-link aliases, and special files;
+- unsafe, non-NFC, reserved, trailing-dot, or case-equivalent paths;
+- excessive depth, file size, total size, path length, or file count.
+
+The digest represents logical content. Do not substitute an archive checksum, Git commit, release tag, or adapter-reported digest.
+
+## Configure repository topology
+
+Repositories are configured under `repositories`. Each must resolve to its own Git working-tree root. Targets map Starter Pack roles to those repositories.
+
+### Single repository
+
+```yaml
+repositories:
+  - name: application
+    path: .
+    role: application
+starter_materialisation:
+  targets:
+    - role: application
+      repository: application
+      path: .
+```
+
+### Monorepo
+
+```yaml
+repositories:
+  - name: product
+    path: .
+    role: workspace
+starter_materialisation:
+  targets:
+    - role: api
+      repository: product
+      path: apps/api
+    - role: web
+      repository: product
+      path: apps/web
+```
+
+### Folder containing several repositories
+
+```yaml
+repositories:
+  - name: api
+    path: services/api
+    role: service
+  - name: web
+    path: clients/web
+    role: client
+starter_materialisation:
+  targets:
+    - role: api
+      repository: api
+      path: .
+    - role: web
+      repository: web
+      path: src
+```
+
+The last example assumes `services/api` and `clients/web` are independent Git working trees. Target destination paths may not overlap in one repository or enter protected content such as `.git`, `.ewai-pipeline`, `.codex`, `.claude`, `.agents`, the configured SPECS tree, `AGENTS.md`, `CLAUDE.md`, `.mcp.json`, `.env`, `.npmrc`, or `.netrc`.
+
+## Implement a generic source adapter
+
+If you're writing the adapter, use the [authoring reference](reference/starter-adapter-authoring.md) for the complete package and request/acknowledgement contracts. If your organisation supplies one, you can continue directly to validation and registration below.
+
+## Validate and register an adapter
+
+```bash
+ewai starter adapter-validate ./starter-source-adapter --project . --json
+ewai starter adapter-register ./starter-source-adapter --project . --yes --json
+ewai starter adapters --project . --json
+```
+
+Validation is read-only. Registration is an explicit trust decision. Review the publisher, source classes, entrypoint, package contents, version, and digests before `--yes`.
+
+The dashboard intentionally cannot register an adapter because that would require sending a filesystem path and executable authority through the browser.
+
+## Prepare, review, and apply
+
+For the dashboard workflow, enable **Starters** in **Configuration** and save first. See [dashboard configuration](operations/dashboard-configuration.md). This only shows the workspace; adapter registration and approval to add files remain separate steps.
+
+List the safe workspace:
+
+```bash
+ewai starter status --project . --json
+```
+
+Prepare:
+
+```bash
+ewai starter preview \
+  org.northstar.engineering:application-foundation:service-platform \
+  --adapter northstar.approved-source \
+  --project . \
+  --yes \
+  --json
+```
+
+The preview contains per-target counts and digests, classifications, repository roles and target roots, expiry, and active personas. It contains no source URL, file body, generated filename, staging root, trusted adapter path, or raw adapter output.
+
+Apply only the current preview:
+
+```bash
+ewai starter apply <preview-id> \
+  --project . \
+  --yes \
+  --approved-by "Delivery Owner" \
+  --json
+```
+
+The caller cannot resend or alter the file plan. EWAI re-resolves accepted Blueprint truth and rechecks adapter bytes, target mappings, Git revisions, staged content, destination state, preview digest, and expiry.
+
+## Understand classifications
+
+| Classification | Meaning | Effect |
+| --- | --- | --- |
+| `create` | No destination exists | Eligible for additive creation after approval |
+| `identical` | A regular destination file has the accepted content digest | Left untouched |
+| `conflict` | A destination exists but is different, symbolic, directory, special, protected, or case-equivalent | Blocks the complete application |
+
+EWAI never offers force or merge. Resolve a conflict deliberately outside materialisation, review the resulting project truth, then prepare a new preview.
+
+## Persona engagement and human authority
+
+The dashboard shows the personas engaged for the current moment and why. EWAI selects from:
+
+- relevant project-local personas materialised from the accepted Blueprint;
+- installed premium product, delivery, platform, or architecture personas;
+- core operator, maintainer, end-user, and SPECS curator lenses.
+
+Review, application, and recovery use different ensembles. Premium content is used only when already installed; this workflow never downloads or updates it.
+
+Personas advise. They do not approve the adapter, accept the product outcome, confirm licensing, certify security, or authorise release. The `--approved-by` person or dashboard approver remains accountable for materialisation.
+
+## Evidence and lifecycle handoff
+
+Successful application writes exact evidence beneath:
+
+```text
+SPECS/3.Evidence/starter-materialisations/<attempt-id>.json
+SPECS/3.Evidence/starter-materialisations/<attempt-id>.md
+```
+
+Evidence records the approved preview, named approver, canonical tree and target digests, repository revisions, repository-relative destinations, result counts, personas, and disclaimer. It is persisted before the attempt becomes completed.
+
+EWAI then publishes `ewai.project.starter.materialised`. The safe event contains only receipt and adapter IDs, aggregate digest, target/repository/result counts, completion time, evidence references, and safe persona projections. Hook failure cannot change materialisation truth.
+
+## Recovery
+
+Normal failure rolls back only content EWAI can prove it created. If a generated file changes after publication, EWAI preserves it and marks the attempt `recovery-required`.
+
+```bash
+ewai starter recover <attempt-id> --project . --yes --json
+```
+
+Recovery is idempotent and digest-sensitive. It removes only unchanged journal-owned files and empty journal-owned directories. It never removes a changed file merely to make the attempt look clean.
+
+## Implementer checklist
+
+- [ ] Blueprint uses `starter_packs` with unique, non-overlapping logical targets.
+- [ ] Canonical digest was produced from the reviewed logical target trees.
+- [ ] Licence and compatibility were reviewed by accountable people.
+- [ ] Project topology maps every role exactly once across real Git worktrees.
+- [ ] Adapter package has a stable publisher, semantic version, and protocol version.
+- [ ] Adapter receives credentials through its own approved mechanism, never from EWAI request fields.
+- [ ] Adapter writes only regular files beneath staging and does not execute retrieved content.
+- [ ] Adapter package validates and is explicitly registered.
+- [ ] Preview shows zero conflicts and the expected target/repository counts.
+- [ ] Active project, premium, and core persona lenses are appropriate for the moment.
+- [ ] Named approval is from someone authorised to add the project foundation.
+- [ ] Canonical evidence is retained and reviewed before any later delivery or release decision.
+
+## Related guides
+
+- [Designing Organisation Blueprint Packs](designing-organisation-blueprint-packs.md)
+- [Working with personas](working-with-personas.md)
+- [Human approval and assurance](human-approval-and-assurance-guide.md)
+- [Troubleshooting and recovery](operations/troubleshooting-and-recovery.md)
+- [CLI and configuration reference](reference/cli-and-configuration.md)

package/Docs/guide-catalogue.md

@@ -0,0 +1,117 @@
+# Complete guide catalogue
+
+[Back to the starting guide](README.md).
+
+Choose the section that matches your job. The optional team tools aren't prerequisites for working on a single project. User guides explain what to do. Integration references are also useful to engineers building adapters for their own organisations; that doesn't require becoming an EWAI maintainer.
+
+## Learning and explanation
+
+- [Your first session](tutorials/first-session.md)
+- [Your first delivery](tutorials/first-delivery.md)
+- [How delivery moves through fourteen stages](explanation/delivery-workflow.md)
+- [Core concepts](explanation/core-concepts.md)
+- [Capabilities and project layout](reference/capabilities-and-project-layout.md)
+
+## Everyday use: product owners, contributors and teams
+
+- [Start a project as its Product Owner](product-owner-guide.md)
+- [Contribute without an engineering background](adoption/non-technical-team-guide.md)
+- [Introduce EWAI to an existing codebase](existing-project-onboarding-guide.md)
+- [Facilitate project Discovery](guided-discovery-facilitator-guide.md)
+- [Create or revise an intent in Intent Studio](guided-intent-workspace-guide.md)
+- [Choose work with the Companion](context-aware-delivery-companion-user-guide.md)
+- [Contribute information to work in progress](guided-phase-evidence-drafting-guide.md)
+- [Review evidence from meeting notes or transcripts](meeting-evidence-user-guide.md)
+- [Turn reviewed evidence into project documents](knowledge-proposals-user-guide.md)
+- [Choose and create personas](working-with-personas.md)
+- [Decide what your design system should capture](design-systems/product-owner-guide.md)
+- [Select and apply design guidance](design-systems/design-system-user-guide.md)
+- [Create screen prototypes](screen-prototype-creation-guide.md)
+- [Challenge and refine prototypes with personas](persona-guided-prototype-iteration.md)
+- [See examples of the workflow](examples/worked-examples.md)
+- [Understand who approves what](human-approval-and-assurance-guide.md)
+
+## Engineering and checking your own application
+
+- [Take an intent through delivery](developer-delivery-guide.md)
+- [Assess what a change could affect](blast-radius-and-impact-routing-guide.md)
+- [Understand repository coverage and analysis limits](repository-source-map-guide.md)
+- [Choose and compare investigation depth](reproducible-archaeology-and-discovery-depth.md)
+- [Follow a worked investigation-depth example](examples/reproducible-archaeology-depth-example.md)
+- [Review investigation depth](quality/reproducible-archaeology-depth-review-checklist.md)
+- [Confirm technology and hosting findings](archaeology-technology-and-hosting-discovery.md)
+- [Analyse extracted Power Platform or Salesforce source](platform-export-analysis-guide.md)
+- [Create project standards](standards/project-standards-authoring.md)
+- [Develop tests from evidence and persona concerns](quality/persona-driven-test-scenarios.md)
+- [Perform Manual QA and acceptance](quality/manual-qa-and-acceptance.md)
+- [Run and review security validation](security-validation-guide.md)
+- [Review whether a solution has sufficient evidence](solution-readiness-review-guide.md)
+- [Inspect model context and token estimates](context-management-and-token-efficiency.md)
+- [Review a design against the guidance used](design-systems/design-system-review-guide.md)
+- [Ratify corrected evidence after phase completion](completed-phase-evidence-amendments.md)
+
+## Operating EWAI on your computer
+
+- [Install and update the harness](operations/installation-updating-and-entitlements.md)
+- [Set up a persona licence and get updates](operations/premium-personas-setup.md)
+- [Choose dashboard views](operations/dashboard-configuration.md)
+- [Inspect dashboard and delivery state](operations/dashboard-and-delivery-state.md)
+- [Diagnose failures and recover safely](operations/troubleshooting-and-recovery.md)
+- [Prepare and share an error report](error-reporting-guide.md)
+- [CLI and configuration reference](reference/cli-and-configuration.md)
+- [Error-reporting and Team Hub command details](cli-reference.md)
+
+## Team administration and shared guidance
+
+- [Introduce EWAI across an organisation](organisation-rollout-guide.md)
+- [Support several clients or projects](adoption/consultancy-and-multi-project-rollout.md)
+- [Govern delivery across a team](governance/governance-team-guide.md)
+- [Review projects and their dependencies](project-portfolio-orchestration-guide.md)
+- [Operate a Team Hub](team-hub-guide.md)
+- [Publish and install shared resources](team-hub-resource-registry-guide.md)
+- [Compare adoption across projects](consultancy-network-rollout-control-plane-guide.md)
+- [Author an Organisation Blueprint](designing-organisation-blueprint-packs.md)
+- [Maintain and release Blueprints](blueprints/maintaining-organisation-blueprints.md)
+- [Validate and troubleshoot Blueprints](blueprints/validation-and-troubleshooting.md)
+- [Maintain an internal Blueprint catalogue](blueprints/internal-blueprint-catalogue.md)
+- [Review and apply starter files](governed-starter-project-materialisation-guide.md)
+- [Author a reusable design-system pack](design-systems/design-system-pack-authoring-guide.md)
+- [Write a useful persona](personas/persona-authoring-cookbook.md)
+- [Capture organisation-specific perspectives](personas/organisation-specific-personas.md)
+- [Maintain and govern personas](personas/persona-governance.md)
+- [Understand the personas shown during work](personas/persona-engagement-ui.md)
+- [Connect approved lifecycle integrations](using-lifecycle-hooks.md)
+
+## Policy owners and reviewers
+
+- [Set up and use optional policy design gates](policies/organisation-policy-design-gates.md)
+- [Review policy as a Product Owner](policies/product-owner-guide.md)
+- [Inspect policy evidence as a Technical Owner](policies/technical-owner-guide.md)
+- [Own policy reviews and exceptions](policies/governance-owner-guide.md)
+- [Author a policy pack](policies/policy-pack-authoring-guide.md)
+
+## Maintaining EWAI
+
+These references are for changing or integrating the harness itself. Run repository test commands from an EWAI development checkout, not your application's folder.
+
+- [Verify changes to EWAI: test suites and manual walkthroughs](maintainers/verification-walkthroughs.md)
+- [Companion operating and implementation reference](context-aware-delivery-companion-guide.md)
+- [Knowledge-proposals implementation](knowledge-proposals-implementer-guide.md)
+- [Meeting-evidence implementation](meeting-evidence-implementer-guide.md)
+- [Design-system implementation](design-systems/design-system-implementation-guide.md)
+- [Policy-gate implementation](policies/implementation-guide.md)
+- [Persona provider and archive contracts](persona-entitlement-provider-guide.md)
+- [Support-provider integration](error-reporting-provider-guide.md)
+
+## Contributing to the harness
+
+- [Source checkout and contributor commands](maintainers/contributing.md)
+
+## Integration and maintainer references
+
+- [Contributions local API](reference/contributions-api.md)
+- [Starter adapter authoring](reference/starter-adapter-authoring.md)
+- [Context benchmark regression checks](maintainers/context-benchmarks.md)
+- [Evidence-depth feature acceptance](maintainers/evidence-depth-acceptance.md)
+
+- [Security adapter authoring](reference/security-adapter-authoring.md)

package/Docs/guided-discovery-facilitator-guide.md

@@ -0,0 +1,172 @@
+# Guided Discovery facilitator guide
+
+Use this guide to lead an EWAI Discovery conversation without allowing the framework—or an active persona—to become the decision-maker.
+
+This guide is for a human facilitating a discussion with a Product Owner and other stakeholders. If you're working alone, use the [first-session tutorial](tutorials/first-session.md) instead. EWAI prepares prompts, selects relevant installed personas and drafts summaries; you make space for real participants, test the evidence and help the authorised owner review the result.
+
+## Your outcome
+
+At the end of Discovery, the group should be able to explain:
+
+- why the project exists and what measurable outcome matters;
+- who experiences the problem and who has decision authority;
+- what is in scope, out of scope, constrained, assumed, or still unknown;
+- which organisational standards and technology directions apply;
+- what evidence supports each material statement;
+- exactly what will become project truth if the owner approves.
+
+The facilitator owns the quality of the conversation. The Product Owner owns the outcome and approval.
+
+## Current behaviour and recommended practice
+
+EWAI currently provides a guided, section-based Discovery flow, contextual persona selection, a Review stage, and named approval. The facilitation techniques in this guide are recommended practice: the CLI cannot guarantee that the right stakeholders attended or that the evidence is sufficient.
+
+## Prepare before the session
+
+Ask the Product Owner for:
+
+1. a one-paragraph purpose statement;
+2. the primary users and affected stakeholders;
+3. desired outcomes and known measures;
+4. firm boundaries and known constraints;
+5. existing evidence, including decisions already made;
+6. unresolved questions and disagreements;
+7. any candidate Organisation Blueprint Pack;
+8. the name of the person who may approve the result.
+
+Don't infer the project's purpose from its current implementation. If inherited code is involved, first offer the owner [existing-project onboarding](existing-project-onboarding-guide.md). Archaeology is optional: if they decline, record the limits of what you've inspected and continue with the owner's Discovery answers.
+
+## Establish the evidence hierarchy
+
+First distinguish **what the system does** from **what it should do**. Source code and an observed run support claims about current behaviour. The accountable owner and applicable obligations determine intended rules. Neither automatically overrides the other: a working implementation can violate a requirement, and an owner's recollection can be out of date. Record the conflict, source and decision owner before resolving it.
+
+Don't rank all sources in a single order. They answer different questions:
+
+| Question | Sources to examine |
+| --- | --- |
+| What is required? | Applicable legal obligations, mandatory standards, approved constraints and requirements. An owner decision can't waive an obligation outside that person's authority. |
+| What is intended? | Accountable human decisions, approved records and direct stakeholder or user evidence. |
+| What happens today? | Source inspection, observed system behaviour and operational evidence. Current behaviour can expose non-compliance; it doesn't override a requirement. |
+| What remains uncertain? | Inference, persona suggestions and model-generated hypotheses, clearly labelled for investigation. |
+
+When these disagree, record the conflict and the person authorised to resolve it. Don't silently replace a requirement with observed behaviour or a plausible suggestion.
+
+A persona can reveal that evidence is missing. It cannot fill the gap by pretending to be the user.
+
+## Work with the active persona ensemble
+
+EWAI selects a small contextual ensemble from the installed project, premium, personal, and core libraries. Selection is based on the current section and the answers already provided.
+
+For every active persona, EWAI shows:
+
+- its name;
+- its source tier;
+- the concerns that matched;
+- why it is engaged now.
+
+At each section transition, check the perspectives EWAI has selected with the group. Explain why their concerns matter to the discussion, and ask EWAI to reconsider the focus if an important perspective is missing. EWAI updates the selection as the subject changes; you don't need to rotate personas manually. Record any remaining gap instead of treating an imagined persona response as stakeholder testimony.
+
+See [Persona engagement UI](personas/persona-engagement-ui.md) for the presentation contract and [Working with personas](working-with-personas.md) for source tiers.
+
+## Facilitate one section at a time
+
+For each topic, use the same loop:
+
+1. **Ask:** invite the accountable person to describe the intended truth.
+2. **Evidence:** ask how they know, where the source is, and how current it is.
+3. **Challenge:** use relevant personas to surface omissions, risks, and alternate experiences.
+4. **Classify:** mark statements as observed, proposed, agreed, decided, inferred, contradicted, or unknown.
+5. **Reflect:** read back the proposed project statement in plain language.
+6. **Confirm:** establish whether the section is ready for Review or needs follow-up.
+
+Do not rush ambiguity into a clean-looking answer. “Unknown, owner and due date recorded” is safer than invented certainty.
+
+## Resolve disagreement
+
+When two sources conflict, record:
+
+| Field | Question |
+| --- | --- |
+| Statements | What does each source actually say? |
+| Authority | Who owns the decision? |
+| Evidence | What direct evidence supports each position? |
+| Consequence | What changes if either position is adopted? |
+| Resolution | Was one accepted, were both bounded, or is the issue still open? |
+| Follow-up | Who will resolve it, and by when? |
+
+Personas may test the consequences, but a named person resolves the decision.
+
+## Review an Organisation Blueprint
+
+If a Blueprint is proposed, pause to review:
+
+- publisher, identity, version, compatibility, and digest;
+- required modules that cannot be deselected;
+- optional modules selected for this project;
+- standards and project persona templates that will be materialised;
+- dependency packs and any collisions;
+- reference-only boilerplate entries;
+- exact destination paths and the durable project pin.
+
+Use the [Product Owner guide](product-owner-guide.md) and [Blueprint design guide](designing-organisation-blueprint-packs.md) for the full approval contract.
+
+## Run the final Review
+
+The Review should show the complete proposed project truth, not a celebratory summary. Ask:
+
+- Does this state the intended outcomes rather than merely describe a solution?
+- Are users and stakeholders represented by evidence?
+- Are assumptions, unknowns, and exclusions visible?
+- Are standards proportionate to the risk?
+- Are generated persona perspectives clearly advisory?
+- Are all file consequences and Blueprint provenance visible?
+- Is the named approver authorised to make this decision?
+
+Approval is not a facilitation shortcut. If the answers are incomplete, return to the relevant section.
+
+## Suggested session record
+
+Capture:
+
+- participants and decision roles;
+- evidence reviewed;
+- active personas by section and why they were engaged;
+- decisions and their owners;
+- unresolved questions, owners, and dates;
+- Blueprint modules accepted or declined;
+- the final Review outcome and named approval.
+
+## Stop and escalate when
+
+- the accountable owner is absent;
+- regulated, security-sensitive, or personal data is being discussed without the right expertise;
+- a persona response is being treated as user research;
+- a Blueprint conflicts with project evidence;
+- participants cannot distinguish a proposal from a decision;
+- approval consequences cannot be shown exactly.
+
+## Facilitator checklist
+
+- [ ] Purpose, users, outcomes, boundaries, and evidence were supplied by people.
+- [ ] Active personas and engagement reasons were visible.
+- [ ] Personas were swapped as the subject changed.
+- [ ] Conflicts and unknowns were retained rather than smoothed away.
+- [ ] Blueprint consequences were inspected in full.
+- [ ] The Review reflected the actual proposed project files.
+- [ ] Approval was given by a named authorised person.
+
+## Related guides
+
+- [Product Owner guide](product-owner-guide.md)
+- [Working with personas](working-with-personas.md)
+- [Human approval and assurance](human-approval-and-assurance-guide.md)
+- [Non-technical team guide](adoption/non-technical-team-guide.md)
+
+## Current contract sources
+
+- `src/discovery.mjs`
+- `src/runtime/guided-discovery.mjs`
+- `src/personas.mjs`
+- `src/organisation-blueprints.mjs`
+- `tests/discovery.test.mjs`
+- `tests/guided-discovery.test.mjs`