@thebackstoryis/engineering-with-ai 0.2.9

package/Docs/using-lifecycle-hooks.md

@@ -0,0 +1,381 @@
+# Using EWAI lifecycle hooks
+
+Lifecycle hooks let an organisation-owned executable receive selected EWAI milestones after EWAI has recorded them. They are a provider-neutral handoff boundary, not built-in deployment, ticketing, messaging, security-scanning, or certification connectors.
+
+The rule to remember is:
+
+> EWAI records the milestone first. Handlers are notified afterwards.
+
+A handler can acknowledge or reject an event, but it cannot approve, veto, complete, fail, or alter Discovery, an Intent, a delivery phase, Build approval, Manual QA, release readiness, or any canonical `SPECS/` evidence.
+
+
+<!-- editorial: contents -->
+## On this page
+
+- [Who this guide is for](#who-this-guide-is-for)
+- [The lifecycle event catalogue](#the-lifecycle-event-catalogue)
+- [1. Build a handler package](#1-build-a-handler-package)
+- [2. Validate before registration](#2-validate-before-registration)
+- [3. Register the reviewed package](#3-register-the-reviewed-package)
+- [4. Enable an explicit subscription](#4-enable-an-explicit-subscription)
+- [5. Understand the event envelope](#5-understand-the-event-envelope)
+- [6. Return a bounded acknowledgement](#6-return-a-bounded-acknowledgement)
+- [7. Make downstream work idempotent](#7-make-downstream-work-idempotent)
+- [8. Inspect delivery](#8-inspect-delivery)
+- [9. Retry a terminal delivery](#9-retry-a-terminal-delivery)
+- [10. Disable future delivery](#10-disable-future-delivery)
+- [Status and diagnostic reference](#status-and-diagnostic-reference)
+- [Retention and recovery](#retention-and-recovery)
+- [Security and governance checklist](#security-and-governance-checklist)
+- [Deliberate V1 exclusions](#deliberate-v1-exclusions)
+- [Contract references](#contract-references)
+
+## Who this guide is for
+
+- An organisation operator who validates, registers, subscribes, inspects, retries, or disables handlers.
+- A handler author implementing the local process that receives EWAI events.
+- A governance or security reviewer assessing the executable boundary, permissions, payload, and operational ownership.
+
+Handler installation and subscription are trusted terminal operations. The dashboard deliberately cannot accept executable paths, commands, endpoints, or credentials.
+
+To inspect hooks in the dashboard, enable **Hooks** in **Configuration** and save. This only shows the view: registering a handler and subscribing to events remain separate actions. See [dashboard configuration](operations/dashboard-configuration.md).
+
+The dispatcher runs with the local dashboard. If the dashboard isn't running, queued deliveries wait. `ewai checkin` starts or reuses it; inspecting a registration alone doesn't dispatch events. Check the delivery status after an event rather than assuming the downstream handler ran.
+
+## The lifecycle event catalogue
+
+EWAI supports these 15 lifecycle events:
+
+| Event | Meaning |
+| --- | --- |
+| `ewai.project.discovery.completed` | Reviewed project Discovery was committed. |
+| `ewai.project.starter.materialised` | An approved starter was added and its evidence saved. |
+| `ewai.meeting-evidence.promoted` | Reviewed meeting evidence was approved and saved. |
+| `ewai.knowledge-proposals.materialised` | Reviewed proposals were added to project knowledge and the result saved. |
+| `ewai.intent.created` | Intent Markdown and structured state were created. |
+| `ewai.policy.facts.confirmed` | Policy facts were confirmed and saved. |
+| `ewai.policy.evaluation.recorded` | A policy evaluation was saved. |
+| `ewai.policy.review.recorded` | A policy review was saved. |
+| `ewai.policy.exception.recorded` | A policy exception was saved. |
+| `ewai.delivery.phase.entered` | A guarded delivery phase entered its running state. |
+| `ewai.delivery.phase.completed` | A phase completed with passing gate evidence. |
+| `ewai.delivery.build.approved` | Named human Build approval was recorded. |
+| `ewai.delivery.manual-qa.approved` | Named human Manual QA approval was recorded. |
+| `ewai.delivery.completed` | The Delivery phase completed and handed off to Manual QA. |
+| `ewai.delivery.release-ready` | Delivery is complete and all required human gates are approved. |
+
+Run `ewai hook catalogue --project PATH --json` to inspect the installed catalogue. `release-ready` is derived from canonical EWAI state; it is never a handler decision.
+
+## 1. Build a handler package
+
+A package is a local folder containing:
+
+```text
+release-observer/
+├── lifecycle-handler.json
+└── handler
+```
+
+The entrypoint can use any language that the local machine can execute directly. EWAI starts the exact registered file with no arguments and `shell: false`, writes one JSON event to standard input, and expects one JSON acknowledgement on standard output.
+
+For example, a minimal Node.js entrypoint is:
+
+```js
+#!/usr/bin/env node
+
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => { input += chunk; });
+process.stdin.on('end', async () => {
+  const event = JSON.parse(input);
+
+  // Perform the organisation-owned, idempotent handoff here.
+  // Use event.idempotencyKey when recording or calling the downstream system.
+
+  process.stdout.write(JSON.stringify({
+    schema: 'ewai.lifecycle-hook-ack/v1',
+    status: 'accepted',
+    code: 'recorded',
+    message: `Recorded ${event.name}`
+  }));
+});
+```
+
+Make the entrypoint executable:
+
+```bash
+chmod +x release-observer/handler
+```
+
+Compute its SHA-256 digest. On macOS:
+
+```bash
+shasum -a 256 release-observer/handler
+```
+
+Put the digest and executable filename into `lifecycle-handler.json`:
+
+```json
+{
+  "schema": "ewai.lifecycle-handler/v1",
+  "id": "org.example.release-observer",
+  "name": "Release observer",
+  "publisher": {
+    "id": "org.example",
+    "name": "Example Organisation"
+  },
+  "version": "1.0.0",
+  "compatibility": {
+    "protocols": ["1"],
+    "eventSchemas": ["1"]
+  },
+  "entrypoint": "handler",
+  "digest": "sha256:REPLACE_WITH_THE_ENTRYPOINT_SHA256",
+  "events": [
+    "ewai.delivery.build.approved",
+    "ewai.delivery.manual-qa.approved",
+    "ewai.delivery.release-ready"
+  ],
+  "limits": {
+    "timeoutMs": 5000,
+    "maxOutputBytes": 16384
+  },
+  "description": "Records approved delivery milestones in an organisation-owned system."
+}
+```
+
+The root, manifest, and entrypoint must be regular files or directories rather than symbolic links. The entrypoint must remain inside the package root. After registration, changing the manifest or implementation makes queued delivery incompatible. Restore the registered bytes, or review the replacement as a new handler identity and subscription before disabling the old subscription. V1 does not update a registered package in place.
+
+## 2. Validate before registration
+
+Validation is read-only:
+
+```bash
+ewai hook validate ./release-observer --project . --json
+```
+
+It checks the bounded root, manifest shape, stable identities, semantic version, protocol/event compatibility, supported event patterns, entrypoint, executable permission, and digest. The safe result exposes calculated digests but not the trusted absolute path.
+
+Validation does not register or enable anything.
+
+## 3. Register the reviewed package
+
+Registration requires explicit confirmation:
+
+```bash
+ewai hook register ./release-observer --project . --yes --json
+```
+
+Registration pins the reviewed package identity, publisher, versions, root, entrypoint, manifest digest, and combined package digest in the project-local runtime. It still does not subscribe the project to events.
+
+Treat registration as executable installation. Review the source, dependency chain, operating-system account, filesystem and network permissions, credential source, downstream permissions, logging policy, and incident owner before confirming it.
+
+## 4. Enable an explicit subscription
+
+Subscribe the registered handler only to the events it needs:
+
+```bash
+ewai hook subscribe org.example.release-observer \
+  --events ewai.delivery.build.approved,ewai.delivery.manual-qa.approved,ewai.delivery.release-ready \
+  --project . \
+  --yes \
+  --json
+```
+
+An event wildcard such as `ewai.delivery.*` is allowed only when it matches the installed catalogue and the handler manifest declares support for every matching event.
+
+New matching events are queued after subscription. Reconciliation can record canonical milestones that are not yet in the hook ledger, but enabling a subscription is not a promise to replay every event previously recorded for another subscription.
+
+## 5. Understand the event envelope
+
+The handler receives an `ewai.lifecycle-event/v1` object:
+
+```json
+{
+  "schema": "ewai.lifecycle-event/v1",
+  "id": "bb48c5a4-0562-49ad-b09e-d1d36e99f807",
+  "name": "ewai.delivery.build.approved",
+  "occurredAt": "2026-08-20T09:53:57.169Z",
+  "project": {
+    "id": "project-52b901fef1364c71",
+    "name": "Example Product"
+  },
+  "scope": {
+    "intent": "platform/safe-delivery",
+    "delivery": "safe-delivery"
+  },
+  "facts": {
+    "status": "approved",
+    "decision": "approved"
+  },
+  "source": {
+    "key": "delivery:safe-delivery:build.approved:2026-08-20T09:53:57.169Z",
+    "revision": "2026-08-20T09:53:57.171Z"
+  },
+  "evidence": [
+    "SPECS/6.Build/safe-delivery/gates/build/build-approval.json"
+  ],
+  "personas": [
+    {
+      "id": "project.release-owner",
+      "name": "Release Owner",
+      "tier": "project",
+      "reason": "Engaged as accountable for this lifecycle moment."
+    }
+  ],
+  "stream": {
+    "id": "delivery:safe-delivery",
+    "sequence": 8
+  },
+  "idempotencyKey": "ewai-4e1f9c9b9d5882a1b9a764d38eb267dc77b301c3"
+}
+```
+
+The payload contains allowlisted semantic facts and project-relative evidence references, not evidence bodies. Persona context contains only ID, name, tier, and engagement reason. Premium and project personas are provenance and advisory context, not authority; proprietary persona bodies are never included.
+
+Prompts, transcript answers, credentials, commands, executable paths, raw evidence, cookies, authorisation values, and raw handler output are excluded.
+
+## 6. Return a bounded acknowledgement
+
+An accepted acknowledgement is:
+
+```json
+{
+  "schema": "ewai.lifecycle-hook-ack/v1",
+  "status": "accepted",
+  "code": "recorded",
+  "message": "The organisation ledger recorded the event.",
+  "metadata": {
+    "duplicate": false
+  }
+}
+```
+
+To refuse the event deliberately:
+
+```json
+{
+  "schema": "ewai.lifecycle-hook-ack/v1",
+  "status": "rejected",
+  "code": "policy-review",
+  "message": "Organisation review is required before this handoff can continue."
+}
+```
+
+Only the bounded status, code, message, scalar metadata, duration, and attempt timestamps are retained. Standard output is parsed and then discarded; standard error is counted against the output limit and discarded. Never depend on EWAI as the handler’s log store.
+
+## 7. Make downstream work idempotent
+
+Delivery is at least once. A handler can receive the same event more than once after timeout, process interruption, automatic retry, or an explicit manual retry.
+
+- Use `idempotencyKey` as the unique key for the downstream operation.
+- Return `accepted` when the same operation was already completed safely.
+- Do not generate a new external action merely because the attempt number changed.
+- Do not use an acknowledgement to imply an external deployment, notification, scan, or workflow succeeded unless the handler genuinely verified that outcome.
+
+The event ID and idempotency key stay stable across all attempts. Retry appends an attempt; it never reruns the EWAI source operation.
+
+## 8. Inspect delivery
+
+Use the CLI:
+
+```bash
+ewai hook list --project . --json
+ewai hook deliveries --project . --json
+ewai hook deliveries --status exhausted --project . --json
+ewai hook deliveries --event ewai.delivery.release-ready --project . --json
+ewai hook deliveries --handler org.example.release-observer --project . --json
+```
+
+Or open the project dashboard and choose **Hooks**. The workspace reads left to right as **Milestone → Handler → Delivery** and shows:
+
+- verified registered handlers and enabled or disabled subscriptions;
+- delivery status, attempt count, next eligibility, and sanitised diagnostic;
+- stable event, stream, handler, package, and idempotency identities;
+- safe scope and evidence references;
+- the core, premium, personal, and project personas recorded as active for that event;
+- a clear reminder that handler status does not change the EWAI milestone.
+
+`Delivered` means the handler returned a valid accepted acknowledgement. It does not certify what happened in a downstream system.
+
+## 9. Retry a terminal delivery
+
+Automatic delivery makes three attempts in total: immediately, after one second, and after a further five seconds. A deliberate rejection or package incompatibility stops automatic delivery immediately. Other repeated failures become `exhausted`.
+
+After diagnosing the handler, retry an `exhausted`, `rejected`, or `incompatible` delivery:
+
+```bash
+ewai hook retry DELIVERY_ID --project . --yes --json
+```
+
+The dashboard exposes the same action with a confirmation. A manual retry uses the same event and idempotency key and appends a manual attempt.
+
+## 10. Disable future delivery
+
+Disable an enabled project subscription:
+
+```bash
+ewai hook disable SUBSCRIPTION_ID --project . --yes --json
+```
+
+Disabling stops future matching deliveries and resolves outstanding non-running deliveries as disabled. Historical events and attempts remain visible. It does not remove the handler package, change its files, or alter canonical project state.
+
+## Status and diagnostic reference
+
+| Status | Meaning | Typical action |
+| --- | --- | --- |
+| `queued` | Eligible for its first or manual attempt. | Allow the dashboard dispatcher to run. |
+| `retrying` | An automatic retry is scheduled. | Inspect the safe diagnostic and wait for eligibility. |
+| `delivering` | The exact local executable is currently running. | Do not start a duplicate operation manually. |
+| `succeeded` | A valid `accepted` acknowledgement was received. | Verify downstream truth in the owning system where appropriate. |
+| `exhausted` | Automatic or manual delivery failed without acceptance. | Diagnose, then use explicit retry. |
+| `rejected` | The handler deliberately returned `rejected`. | Resolve its stated policy or business reason, then retry if appropriate. |
+| `incompatible` | Registered package identity or bytes no longer match. | Review the local package rather than bypassing the check. |
+| `disabled` | The subscription was disabled. | Re-enable only through a reviewed explicit subscription action. |
+
+Common safe codes include `handler-timeout`, `handler-output-too-large`, `handler-exit`, `handler-signal`, `handler-ack-invalid`, `handler-incompatible`, `worker-interrupted`, and `subscription-disabled`.
+
+## Retention and recovery
+
+- Successful and explicitly resolved deliveries have a 30-day runtime retention window.
+- Unresolved failures remain until they are retried successfully or disabled, then remain for 30 more days.
+- A `delivering` claim older than 60 seconds is recovered after restart as `worker-interrupted`. An automatic claim consumes one bounded attempt and resumes only when its budget remains. An interrupted manual claim returns to `exhausted` and requires a new explicit retry.
+- Runtime hook data lives in the rebuildable project-local SQLite projection under `.ewai-pipeline/`; it is not canonical `SPECS/` truth.
+- Cleanup never deletes canonical delivery evidence.
+
+If the dashboard is not running, queued delivery waits. `ewai checkin` starts or reuses the local dashboard; opening the Hooks workspace also reconciles canonical milestones with the hook ledger.
+
+## Security and governance checklist
+
+Before production use, confirm:
+
+1. The publisher, source, dependencies, entrypoint digest, and declared event set were reviewed.
+2. The operating-system account has only the filesystem, network, and downstream permissions it needs.
+3. Credentials come from the organisation’s protected runtime mechanism, never from the manifest, project content, browser, event, acknowledgement, or command arguments.
+4. Downstream operations enforce their own authorisation and use the EWAI idempotency key.
+5. Handler logs apply the organisation’s data classification and retention policy.
+6. Ownership, monitoring, incident response, package updates, revocation, and disaster recovery are explicit.
+7. People understand that handler success is not EWAI approval or external certification.
+
+## Deliberate V1 exclusions
+
+EWAI does not provide:
+
+- production connectors for deployment platforms, ticketing tools, messaging services, security products, or cloud providers;
+- browser-based handler installation, update, executable configuration, endpoint configuration, or credential entry;
+- remote webhook hosting or webhook-signing infrastructure;
+- pre-transition or veto hooks;
+- handler-driven Build, Manual QA, phase, release, or compliance approval;
+- deployment execution, release certification, or downstream outcome verification;
+
+Organisations can implement their own connector behaviour behind a reviewed handler. That code, its permissions, and its operational consequences remain organisation-owned.
+
+## Contract references
+
+- `config/lifecycle-handler.schema.json`
+- `config/lifecycle-event.schema.json`
+- `config/lifecycle-hook-ack.schema.json`
+- `SPECS/4.Constraints/standards/lifecycle-hook-safety.md`
+- `src/runtime/lifecycle-hooks.mjs`
+- `tests/lifecycle-hooks.test.mjs`
+- `tests/lifecycle-hook-emissions.test.mjs`

package/Docs/working-with-personas.md

@@ -0,0 +1,274 @@
+# Working with personas
+
+Personas give EWAI deliberate perspectives to apply during Discovery and delivery. They help expose blind spots, ask better questions, and translate consequences for different people.
+
+A persona is an advisory lens. It is not a real stakeholder, a source of factual evidence, an approval, or a grant of authority.
+
+For example, an export may look straightforward until an operator asks how a failed download is retried and a privacy lens asks which fields should be excluded. Those perspectives change the questions you put to the owner and the tests you plan. They don't decide the permission rules or claim real users approved them.
+
+## Choose the right persona source
+
+| Type | Owned by | Lives in | Best for | How it enters a project |
+| --- | --- | --- | --- | --- |
+| Core | EWAI maintainers | Bundled framework persona pack | General engineering and delivery disciplines | Available with EWAI. |
+| Premium | Managed persona-pack publisher | Local entitled pack cache under `~/.ewai/packs/…/premium-personas/` | Broader specialist perspectives maintained outside the public repository | Explicit entitlement check and user-approved sync. |
+| Personal | One practitioner | `~/.ewai/personas/` | A reusable working lens across several projects | Create once; the local catalogue can select it when relevant. |
+| Project | The project or team | Configured `SPECS/1.Scope/personas/project/` | Product, domain, organisation, or user knowledge that belongs with this project | Create in the project and version it with SPECS. |
+| Blueprint-derived project | Organisation pack publisher, then the approving project | Starts in an Organisation Blueprint Pack; materialises into the project-persona directory | A reviewed organisation perspective that should become project-owned truth | Previewed with the blueprint and created only after named Discovery approval. |
+
+Use the narrowest ownership that is true. If a perspective only makes sense for one product, it is a project persona—not a personal global default. If a team has developed a perspective beyond the managed premium version, create a project persona that states the project-specific stance rather than editing managed files.
+
+## Inspect the available catalogue
+
+List personas available to the current environment:
+
+```bash
+ewai persona list --project .
+```
+
+Narrow the list by a word found in the persona's metadata, tags, capabilities, or path:
+
+```bash
+ewai persona list --project . --query security
+ewai persona list --project . --query finance
+ewai persona list --project . --query accessibility
+```
+
+For a compact machine-oriented view, use:
+
+```bash
+ewai persona index --project . --query architecture
+```
+
+The index exposes public metadata such as ID, name, description, category, tier, tags, capabilities, and local path. It does not make the persona an authority over project decisions.
+
+## Create a personal persona
+
+Use a personal persona for a lens you own and expect to reuse:
+
+```bash
+ewai persona create security-reviewer \
+  --name "Security Reviewer" \
+  --category engineering
+```
+
+Locate the personal library with:
+
+```bash
+ewai persona path --scope personal
+```
+
+The default root is `~/.ewai/personas/`.
+
+## Create a project persona
+
+Use a project persona for product-specific stakeholders, domain roles, organisation conventions, or locally agreed decision lenses:
+
+```bash
+ewai persona create finance-controller \
+  --scope project \
+  --project . \
+  --name "Finance Controller" \
+  --category finance
+```
+
+Locate the configured project library with:
+
+```bash
+ewai persona path --scope project --project .
+```
+
+The default contract location is the configured SPECS root beneath `1.Scope/personas/project/`. Do not assume the SPECS root is literally `./SPECS`; `.ewai-pipeline/project.json` identifies it for the current project.
+
+The create command refuses to overwrite an existing persona unless `--force` is supplied. Review the existing project truth before using that replacement option.
+
+## Shape a useful persona
+
+The generator creates portable metadata and four body sections. A project persona can look like this:
+
+```markdown
+---
+schema: ewai.persona/v1
+id: project.finance-controller
+name: Finance Controller
+version: 0.1.0
+description: Tests product decisions against financial control, auditability, and month-end operations.
+category: finance
+pack: ewai.personas.project
+tier: project
+tags:
+  - finance
+  - audit
+  - reporting
+capabilities:
+  - control-design
+  - financial-reporting
+---
+
+# Finance Controller
+
+## Mission
+
+Make financial consequences and control obligations visible before delivery choices become expensive to reverse.
+
+## Operating stance
+
+- Trace every material figure to an accountable source.
+- Prefer explicit controls and reconciliation evidence over confident narrative.
+- State which conclusion is evidence and which is a working assumption.
+
+## Questions to keep asking
+
+- Who owns this control in normal operation?
+- What happens at month end, year end, or during an audit?
+- Can a user explain and reproduce this figure?
+
+## Boundaries
+
+- This persona advises; the real Finance Controller and Product Owner remain accountable.
+- Real stakeholder evidence takes priority over simulated feedback.
+```
+
+### Metadata that improves engagement
+
+Discovery matches each section's perspective signals against the persona's ID, name, category, description, tags, and capabilities. Make those fields specific enough to be discoverable:
+
+- Write a description around the decisions and risks the persona examines.
+- Use stable, plain-language tags such as `accessibility`, `privacy`, `finance`, `operations`, or `api`.
+- Use capabilities for concrete work such as `threat-modelling`, `control-design`, or `user-research`.
+- Avoid stuffing every possible keyword into one persona. A persona that matches everything adds little discrimination.
+
+The body should say what the persona is trying to protect, how it reasons, what evidence it expects, the questions it keeps asking, and where its authority stops.
+
+## Use premium personas safely
+
+For first-time setup, [enter your licence and install the pack](operations/premium-personas-setup.md). Setup installs immediately; later updates require your consent.
+
+A status check doesn't download content, but it can enforce confirmed team expiry by removing an unchanged managed pack. Individual expiry keeps installed personas; your personal and project libraries aren't touched. Read the current state when needed:
+
+```bash
+ewai persona premium status --project . --json
+```
+
+The normal EWAI check-in and explicit status command report three separate facts:
+
+1. whether premium access is available;
+2. whether the managed premium library is installed;
+3. whether an installed library is verified against its validated content and external receipt.
+
+Remote freshness is a further fact: a verified local library can remain installed while network access is unknown. Entitlement, installed state, verified state, and active persona engagement are not interchangeable.
+
+Check-in does not download premium content. If it offers an install or update, decide explicitly whether this project environment should receive it. Only after that decision run:
+
+```bash
+ewai persona premium sync --project . --yes
+```
+
+The `--yes` flag is an intentional consent boundary. Do not hide this command in unattended setup or run it merely because access exists.
+
+The sync process protects the managed cache and uses a fresh staged candidate:
+
+- it checks licence access with the configured website;
+- it verifies the downloaded ZIP against the advertised checksum and size;
+- it refuses to replace locally edited managed files;
+- it validates the manifest, safe paths, allowed text/data files, file count and bounded size;
+- it records a deterministic content digest in a receipt outside the pack;
+- it atomically promotes valid content and restores the prior pack if promotion fails.
+
+Do not edit premium definitions in place, copy them into public project history, or present them as project-owned evidence. If the project needs a durable local variation, author a new project persona that states what changed and why.
+
+The public persona schema uses its published ownership tiers. Guided Discovery presents personas loaded from the managed premium library with the user-facing tier `premium`. Do not hand-author a project file with `tier: premium`; use the supported sync path and preserve managed provenance.
+
+## Use blueprint-derived personas
+
+An [Organisation Blueprint Pack](designing-organisation-blueprint-packs.md) may contain persona templates. Selection does not immediately add them to the active ensemble.
+
+During Review, EWAI shows the persona consequences alongside the selected standards and boilerplate receipts. After named approval it materialises each template as a project persona with:
+
+- an ID in the form `project.<publisher>.<persona>`;
+- `tier: project`;
+- the source pack, version, digest, approver, and approval time;
+- project-owned Markdown under `SPECS/1.Scope/personas/project/`.
+
+From that point, the definition is a project-owned asset and can be improved through the project's normal reviewed change process. Its responses remain advisory; they aren't evidence from a real stakeholder.
+
+## How Discovery engages personas
+
+Discovery does not permanently activate every installed persona. For the current section it:
+
+1. compares the section's perspective signals with persona metadata;
+2. adds smaller relevance signals from existing answers;
+3. ranks candidates by match strength, then by tier and stable name/ID ordering;
+4. deliberately tries to include a relevant project persona and a relevant premium persona;
+5. fills the remaining places with the strongest relevant candidates, up to four.
+
+The tier tie-break order is project, premium, personal, then core. Relevance comes first: a high-tier persona with no match is not engaged.
+
+### What you'll see in Discovery
+
+At every Discovery section, EWAI shows the current personas. For each one you'll see:
+
+- **name** — who the lens represents;
+- **tier** — where it came from;
+- **engagement reason** — why it is relevant to this section;
+- **matched concerns** — the perspective signals that caused the match, when useful.
+
+The active list can change as the participant moves between sections or adds answers. That is expected: personas are being swapped in and out to fit the work at hand.
+
+Use this display to understand and challenge the selection. If a critical perspective is absent, ask EWAI to reconsider the focus. If the catalogue lacks the necessary project-specific perspective, you can review and improve its metadata or create a project persona; bring in real stakeholders wherever their evidence is needed. The [UI integration guide](personas/persona-engagement-ui.md) describes the presentation requirements for interface authors.
+
+## Use personas in a working session
+
+1. State the real decision and the real people affected.
+2. Check the active persona names, tiers, and reasons before answering the section.
+3. Invite the persona questions that expose a distinct risk, user need, or operational consequence.
+4. Label what comes from real evidence and what is a persona-generated hypothesis.
+5. Ask EWAI for a missing perspective. It handles contextual selection; you decide whether a new or improved project persona is needed and review its definition.
+6. Record the accountable human decision in project-owned SPECS.
+
+Personas should broaden the conversation, then get out of the way of evidence and ownership.
+
+## About overlays
+
+The project contract reserves a persona `overlays` area for future composition patterns. The current persona resolver does not automatically merge those files into active personas.
+
+For behaviour you need today, put the complete reviewed persona in the project-persona directory. Do not rely on an overlay file being discovered or composed automatically.
+
+## Maintain and review personas
+
+- Keep IDs stable; change names and descriptions deliberately.
+- Increase the version when the perspective or evidence standard changes.
+- Review project personas with the real roles they represent whenever practical.
+- Remove obsolete keywords rather than allowing stale personas to keep matching.
+- Check version control for unexplained changes to project personas.
+- Re-run `ewai persona list --project . --query <term>` after changes.
+- Confirm in Guided Setup that the expected names, tiers, and engagement reasons appear in the relevant sections.
+- Never interpret a persona response as approval.
+
+## Troubleshooting
+
+| Symptom | Likely cause | Recovery |
+| --- | --- | --- |
+| Persona is missing from the catalogue | Wrong scope/root, invalid Markdown metadata, or project path not supplied | Run `persona path`, inspect the file, and list again with `--project .`. |
+| Persona never becomes active | Its metadata does not match the section's signals or current answers | Make description, tags, and capabilities more specific to the intended decisions. |
+| Too many generic personas appear | Broad or duplicated keywords produce similar relevance scores | Narrow their missions and metadata; keep one accountable lens per distinct concern. |
+| Premium library is absent | Access may be unavailable or sync has not been explicitly approved | Read check-in status and choose whether to install it through [premium setup](operations/premium-personas-setup.md). |
+| Premium update is refused | Managed files were edited, the installed pack belongs to another seat, or archive validation failed | Preserve edits and read the specific error. Don't force replacement. Use the [setup and recovery guide](operations/premium-personas-setup.md). |
+| Overlay has no effect | Automatic overlay composition is not current behaviour | Move the complete reviewed perspective into a project persona. |
+
+## Related guides
+
+- [Designing Organisation Blueprint Packs](designing-organisation-blueprint-packs.md)
+- [Persona entitlement and pack providers](persona-entitlement-provider-guide.md)
+- [Product Owner guide](product-owner-guide.md)
+- [All EWAI guides](README.md)
+
+## Contract sources
+
+- `src/personas.mjs` — personal/project roots, creation template, parsing, listing, and indexing
+- `config/persona.schema.json` — public metadata contract
+- `src/checkin.mjs` — safe check-in and CLI entitlement adapters
+- `src/persona-entitlements.mjs` — provider access, pack validation, receipts, atomic promotion, and recovery
+- `src/runtime/dashboard-server.mjs` — core, premium, personal, and project catalogue assembly
+- `src/runtime/guided-discovery.mjs` — contextual matching, tier tie-breaks, maximum ensemble, and engagement reasons
+- `src/discovery.mjs` — blueprint persona materialisation and provenance