@thebackstoryis/engineering-with-ai 0.2.9

package/Docs/developer-delivery-guide.md

@@ -0,0 +1,224 @@
+# Developer delivery guide
+
+Ask EWAI to work through an intent with you. The **ewai-deliver** skill coordinates planning, implementation and review, checks what each stage needs, and asks for your approval before Build. You can start with a draft; its outcome and acceptance criteria need to be ready before the Intent stage finishes.
+
+Try the [first-delivery tutorial](tutorials/first-delivery.md) for a guided example. This guide provides the operational detail and commands when you need direct control.
+
+
+<!-- editorial: contents -->
+## On this page
+
+- [Before delivery begins](#before-delivery-begins)
+- [Start through the guarded workflow](#start-through-the-guarded-workflow)
+- [Understand the fourteen stages](#understand-the-fourteen-stages)
+- [Use personas to expand test coverage](#use-personas-to-expand-test-coverage)
+- [Plan vertical slices](#plan-vertical-slices)
+- [Preserve the Build approval boundary](#preserve-the-build-approval-boundary)
+- [Build with evidence](#build-with-evidence)
+- [Run standards and tests separately](#run-standards-and-tests-separately)
+- [Prepare Delivery and Manual QA](#prepare-delivery-and-manual-qa)
+- [Shelf and resume](#shelf-and-resume)
+- [Definition of done](#definition-of-done)
+- [Related guides](#related-guides)
+- [Current contract sources](#current-contract-sources)
+
+## Before delivery begins
+
+Use these checks to establish what you know and what needs work. They aren't a requirement to arrive with a finished intent; resolve the outcome and acceptance gaps during Intent.
+
+Confirm:
+
+- the intent describes an outcome rather than only a requested implementation;
+- acceptance criteria, constraints, dependencies, and non-goals are explicit;
+- attached personas are relevant and advisory;
+- repository work and unrelated local changes are understood and protected;
+- the repository index is fresh enough for impact and standards claims;
+- the configured validation policy is known.
+
+Inspect or refresh repository knowledge:
+
+```bash
+ewai index freshness --project .
+ewai index refresh --project .
+ewai index coverage --project .
+ewai index standards-coverage <intent-slug> --project .
+```
+
+Review the [Repository Source Map](repository-source-map-guide.md) when inventory-only, shallow, sensitive, oversized, or failed evidence could limit a claim. When changing existing behaviour, use [Blast Radius and Impact Routing](blast-radius-and-impact-routing-guide.md) to inspect the bounded dependency reach, possible consequences, active perspectives, and required human review routes. Treat partial coverage as uncertainty. Repeat the assessment if implementation crosses the assessed boundary.
+
+## Start through the guarded workflow
+
+Normally, ask your host to use `ewai-deliver`. For direct operation, replace `<intent-slug>` with the saved identifier, such as `support/export-filtered-tickets`:
+
+```bash
+ewai delivery begin <intent-slug> --project . --tool codex
+ewai delivery continue <intent-slug> --project .
+```
+
+`begin` creates the delivery run; `continue` inspects it and reports the next permitted step. Neither command performs the whole phase. Continue the work in your AI host using that result.
+
+Use the canonical delivery operations. Never hand-edit a phase status, completion percentage, approval, or SQLite work item to move delivery forward.
+
+## Understand the fourteen stages
+
+[Follow one feature through every stage](explanation/delivery-workflow.md). The table below is the operational summary.
+
+| Stage | Engineering purpose |
+| --- | --- |
+| Ideate | Convert a rough idea when no sufficient intent exists. |
+| Intent | Establish outcome, evidence, acceptance, constraints, and relationships. |
+| Reconcile | Compare intent with inherited or existing behaviour. |
+| Plan | Define vertical slices, contracts, dependencies, tests, and stop conditions. |
+| Pattern Validation | Verify the plan against repository patterns and project standards. |
+| Test Plan | Establish red/green/refactor and acceptance evidence before Build. |
+| External Plan Validation | Obtain independent review when configured and available. |
+| External Test Validation | Independently review the test design when configured. |
+| Build | Implement only the explicitly approved scope. |
+| Standards Sweep | Check the complete change against project standards. |
+| Test Execute | Run the planned tests and retain results. |
+| External Code Validation | Independently review the change when configured. |
+| Delivery | Prepare the handoff, release evidence, and Manual QA walkthrough. |
+| Retro | Capture learning after human acceptance. |
+
+Conditional and provider-gated stages may be skipped or marked not supported by the contract. That is evidence, not permission to invent a review.
+
+The workflow also includes conditional **UI Design** for interface work and **FitCheck** when resuming shelved work. Follow the phase sequence returned by EWAI rather than jumping directly from this overview to Build. After Delivery, **Manual QA** remains a separate human acceptance gate before Retro can close the work.
+
+## Use personas to expand test coverage
+
+During Test Plan, use [Persona-driven test scenarios](quality/persona-driven-test-scenarios.md) when role-specific lenses can materially challenge the accepted journeys, criteria, constraints, impact evidence, standards, or test obligations. Before recording a scenario, have the named reviewer agree what it should demonstrate and which requirement or other accepted evidence supports that result. That agreed expected result is the test's **oracle**.
+
+During Build, implement accepted automated or hybrid scenario IDs only when their planned test belongs to the leased task. Write the failing test first, preserve the accepted oracle, and keep Manual QA, specialist assurance, and representative-user routes open for human evidence.
+
+## Plan vertical slices
+
+A good task produces a user-visible or operator-visible outcome and owns a non-overlapping write set. Record:
+
+- claim and slice IDs;
+- repository and branch;
+- read and write sets;
+- dependencies and execution wave;
+- module or interface contract;
+- first failing test or an explicit rationale;
+- allowed commands;
+- stop conditions;
+- completion evidence;
+- fresh-context review expectations.
+
+Do not split work only by technical layer when doing so creates partially usable or untestable changes.
+
+## Preserve the Build approval boundary
+
+Build cannot start until pre-Build phases pass and an authorised person approves an exact scope:
+
+```bash
+ewai delivery approve-build <intent-slug> \
+  --project . \
+  --yes \
+  --approved-by "Product Owner" \
+  --scope "The files and outcomes approved for this build"
+```
+
+If a human-approved correction changes completed pre-Build gate evidence, ratify the amended ledgers before recording Build approval:
+
+```bash
+ewai delivery ratify-amendments <intent-slug> \
+  --project . \
+  --yes \
+  --approved-by "Product Owner" \
+  --scope "The corrected intent, plan, UI and test contracts"
+```
+
+For the distinction between this operation and narrow completed-evidence corrections, see [Which amendment operation?](completed-phase-evidence-amendments.md#which-amendment-operation).
+
+Ratification revalidates every completed phase, records the old and new gate hashes, and updates the stored fingerprints atomically. It cannot start Build or substitute for the separate Build approval.
+
+Approval is a durable record, not a conversational implication. If the implementation needs a material new outcome, return to Intent or Plan and obtain fresh approval.
+
+## Build with evidence
+
+For each task:
+
+Use `$ewai-deliver` to acquire and maintain an execution lease for the task before writing code. The lease identifies its current worker; it isn't Build approval. The task graph defines the allowed files, commands and stop conditions. Release the lease only with the actual completion or handoff outcome.
+
+1. run the recorded red check and retain the expected failure;
+2. make the smallest coherent implementation;
+3. run the green check;
+4. refactor within the approved contract;
+5. review tests before implementation details in a fresh context;
+6. record changed files, commands, hashes, and completion checks;
+7. stop when a declared stop condition occurs.
+
+Protect unrelated work. Do not use destructive Git operations or automatic stashing to make the worktree look clean.
+
+## Run standards and tests separately
+
+A test suite demonstrates selected behaviour. A standards sweep examines whether the whole change conforms to project constraints. Both are mandatory when the project policy requires them.
+
+External validation is also distinct. EWAI excludes the active orchestrator from the independent reviewer set and honours the configured cycle limit. If no independent provider remains, record the checkpoint as not supported; do not call self-review independent.
+
+## Prepare Delivery and Manual QA
+
+Delivery should include:
+
+- implementation summary and changed files;
+- exact automated checks and results;
+- accepted limitations and residual risks;
+- operational or migration notes;
+- rollback or recovery guidance where relevant;
+- a reproducible Manual QA walkthrough;
+- the decision the human tester is being asked to make.
+
+Manual QA is a separate named gate:
+
+```bash
+ewai delivery approve-manual-qa <intent-slug> \
+  --project . \
+  --yes \
+  --approved-by "Product Owner" \
+  --evidence SPECS/6.Build/<intent-slug>/qa-evidence.md
+```
+
+Only the person who performed or accepted the walkthrough should approve it.
+
+## Shelf and resume
+
+Shelf mode prepares validated planning evidence and stops before Build. Resume must re-enter through the guarded resume/FitCheck path:
+
+```bash
+ewai delivery begin <intent-slug> --project . --tool codex --mode shelf
+ewai delivery resume <intent-slug> --project . --tool codex
+```
+
+Do not resume blocked, corrupt, or ambiguous work by editing state files.
+
+## Definition of done
+
+The work is not done until:
+
+- planned tasks have complete evidence;
+- mandatory standards and tests pass; any permitted exception follows its specific reviewed process, and recording a risk alone doesn't waive a required gate;
+- configured independent review is complete or honestly unavailable;
+- Delivery evidence and a Manual QA walkthrough exist;
+- the human acceptance gate is approved;
+- the retrospective records reusable learning.
+
+## Related guides
+
+- [Human approval and assurance](human-approval-and-assurance-guide.md)
+- [Blast Radius and Impact Routing](blast-radius-and-impact-routing-guide.md)
+- [Persona-driven test scenarios](quality/persona-driven-test-scenarios.md)
+- [Manual QA and acceptance](quality/manual-qa-and-acceptance.md)
+- [Dashboard and delivery state](operations/dashboard-and-delivery-state.md)
+- [Project standards authoring](standards/project-standards-authoring.md)
+
+## Current contract sources
+
+- `src/delivery.mjs`
+- `src/delivery-gates.mjs`
+- `src/delivery-artifacts.mjs`
+- `src/task-graph.mjs`
+- `src/validation-config.mjs`
+- `config/delivery-artifacts.yaml`
+- `tests/delivery.test.mjs`
+- `tests/task-graph.test.mjs`

package/Docs/error-reporting-guide.md

@@ -0,0 +1,110 @@
+# Local Error Reporting guide
+
+EWAI can create privacy-safe diagnostic packages without a paid service or hosted reporting backend. Reports remain on the user's machine until a person explicitly prepares an email or invokes a registered provider adapter.
+
+This capability reports problems in the EWAI design-time pipeline. It is not production monitoring, application telemetry, incident management, security certification or a runtime engine for software built with EWAI.
+
+## Where reports live
+
+EWAI keeps operational material under:
+
+```text
+.ewai-pipeline/error-reports/
+├── drafts/
+├── packages/
+├── receipts/
+├── archive/
+└── adapters/
+```
+
+The folder is excluded by the managed `.ewai-pipeline/.gitignore`. Do not move reports into `SPECS/` or source control: they are local operational evidence, not canonical project truth.
+
+## Quick start
+
+1. Run `ewai dashboard --project .` and open the reported loopback URL.
+2. Choose **Error Reporting**.
+3. Create and review a local draft.
+4. Finalise the draft only when its safe projection contains enough information and no unnecessary sensitive detail.
+5. Either prepare a manual email or, when your organisation has explicitly registered one, invoke a provider adapter.
+
+Nothing leaves the machine during steps 1–4.
+
+## Use the dashboard
+
+Open the local dashboard and choose **Error Reporting**. The workspace provides:
+
+- a list of draft, finalised and archived reports;
+- a graphical viewer for safe diagnostics, reproduction steps, exclusions, package digests, attempts and receipts;
+- **Create report** for a manual draft;
+- contextual **Report this problem** actions when an EWAI dashboard surface fails;
+- an **Automatic local drafts** opt-in;
+- **Finalise ZIP**, **Prepare email**, provider, archive and delete actions when their preconditions are met.
+
+Creating a report never transmits it. Automatic local drafts are opt-in and create deduplicated drafts only; they never finalise, email or invoke a provider.
+
+## Understand custody states
+
+| State | Meaning | What it does not prove |
+|---|---|---|
+| `draft` | Local editable report material exists. | That a complete package or external report exists. |
+| `finalised` | An immutable digest-bound ZIP exists locally. | That the ZIP was attached, sent, accepted or reviewed. |
+| `prepared-not-sent` | EWAI revealed the ZIP and requested the default email client. | That the ZIP was attached or the email was sent or delivered. |
+| `attempted` or `failed` | A registered provider invocation was recorded. | That the provider accepted or retained the package. |
+| `accepted` | The provider acknowledged the exact package digest. | That anyone triaged, resolved or closed the issue. |
+| `archived` | The safe report record was retained locally and removed from active work. | That its ZIP remains available or any external copy was recalled. |
+
+## Automatic local drafts
+
+Automatic local drafts are disabled by default. When enabled, supported EWAI failures create bounded, path-free, deduplicated local drafts. Capture failures are isolated so they cannot replace or mask the original EWAI error.
+
+Review an automatic draft before finalising it. Automatic capture never adds raw logs, prompts, responses, source files, environment values, credentials or persona bodies, and it never performs a transport action.
+
+## Review and finalise
+
+Before finalising:
+
+1. Check the title, expected behaviour, actual behaviour and reproduction steps.
+2. Remove client information, secrets, personal data and other unnecessary detail.
+3. Inspect the exclusion summary. EWAI excludes credentials, environment values, absolute paths, repository names, source and SPECS content, raw logs, prompts and responses, and persona bodies.
+4. Finalise only when the bounded content explains the problem without exposing project material.
+
+Finalisation creates a deterministic immutable ZIP containing a manifest, summary, bounded diagnostics and redaction report. EWAI shows both the logical package digest and exact archive digest. Editing a finalised report creates a new draft revision and leaves the earlier ZIP unchanged.
+
+## Prepare a manual email
+
+Select a finalised report and choose **Prepare email**. EWAI confirms the exact digest, asks the operating system to reveal the ZIP and opens the default email client with a subject and safe body.
+
+The state is `prepared-not-sent`. EWAI cannot prove that the ZIP was attached or the message was sent. You must:
+
+1. inspect the recipient and email body;
+2. attach the revealed ZIP manually;
+3. confirm the attached filename and digest correspond to the selected revision;
+4. send the message yourself.
+
+If the operating system cannot open one of those applications, copy the package location from the dashboard and create the email manually. No paid service is required.
+
+## Use a provider adapter
+
+A registered generic provider adapter can transport the exact ZIP to a commercial or organisation-owned system. EWAI includes the interface, not vendor connectors. Registration is an explicit trusted-code decision, and sending requires confirmation plus the exact archive digest.
+
+The dashboard distinguishes attempts from receipts. A failed attempt remains visible. An accepted receipt proves that the provider acknowledged the exact digest; it does not prove that anyone reviewed, fixed or closed the problem.
+
+See [Error Reporting provider guide](error-reporting-provider-guide.md) for implementation and trust requirements.
+
+## CLI equivalents
+
+Use [Error Reporting CLI reference](cli-reference.md) for automation and troubleshooting. The `$ewai-error-reporting` skill follows the same lifecycle and custody boundaries.
+
+## Archive and deletion
+
+Archiving retains a safe archived report record and removes the working draft and package material. If the ZIP must be retained, copy it to an approved location before archiving. Deletion removes local report material and requires explicit confirmation. Neither action recalls an email attachment or deletes material already accepted by an external provider. Provider attempts and receipts remain as transport evidence.
+
+## Troubleshooting
+
+- If the dashboard does not show a newly created report, refresh the workspace and compare it with `ewai error-report status --project . --json`.
+- If email preparation cannot reveal the ZIP or open a client, use the package location shown by EWAI and prepare the email manually.
+- If a provider attempt fails, inspect its bounded reason class and the provider's own safe operational logs. Retrying creates a new attempt rather than rewriting history.
+- If a finalised package needs different content, create a new draft revision. Do not modify the existing ZIP.
+- If automatic drafts are too noisy, disable the setting; existing drafts remain local until explicitly archived or deleted.
+
+For accountable acceptance of the complete workflow, follow the project delivery's `qa-walkthrough.md`. Automated checks and provider receipts do not substitute for Manual QA.

package/Docs/error-reporting-provider-guide.md

@@ -0,0 +1,49 @@
+# Error Reporting provider guide
+
+EWAI exposes a generic provider adapter boundary so an organisation can integrate its chosen commercial error tracker, ticketing tool or support service. The core product ships no connector, requires no paid service and provides no hosted reporting backend.
+
+## Responsibility split
+
+EWAI owns safe local drafting, review, deterministic ZIP finalisation, exact digests, explicit submission approval, bounded adapter invocation, and local attempt/receipt evidence.
+
+The adapter owns provider authentication, network calls, provider-specific field mapping, rate limits and the external reference. It must not expand the report by collecting source, environment values, logs or other local material.
+
+## Build an adapter
+
+Create a self-contained folder with `error-report-provider.json` and one executable entrypoint. The manifest declares a stable provider ID, publisher, semantic version, protocol version `1` and relative entrypoint. Read the [complete versioned request and acknowledgement protocol](../skills-src/ewai-error-reporting/references/provider-contract.md). The [minimal non-sending adapter](examples/error-report-adapter.md) supplies a complete manifest and executable you can validate locally. It deliberately rejects sending; it isn't a built-in vendor integration.
+
+The entrypoint reads one `ewai.error-report-submission/v1` JSON line from stdin. It transports only the supplied immutable ZIP, then writes one `ewai.error-report-provider-ack/v1` JSON object to stdout. The acknowledgement must repeat the exact attempt ID and archive digest and provide a bounded external reference.
+
+Keep credentials in the adapter or provider's established secure configuration. Never put them in the manifest, report, command arguments, stdout or acknowledgement.
+
+## Validate and register
+
+```bash
+ewai error-report adapter-validate ./my-adapter --project . --json
+ewai error-report adapter-register ./my-adapter --project . --yes --json
+```
+
+Validation checks the bounded package shape, entrypoint and digests. Registration requires explicit confirmation because the adapter becomes trusted local code. It isn't OS-sandboxed and runs with your operating-system permissions. Registration does not execute the adapter. It records the reviewed package and manifest digests, and rejects same-version digest drift.
+
+## Send and verify
+
+```bash
+ewai error-report providers --project . --json
+ewai error-report send report_example \
+  --provider example.support \
+  --expected-digest sha256:... \
+  --yes \
+  --project . \
+  --json
+ewai error-report receipts report_example --project . --json
+```
+
+EWAI revalidates the registered package immediately before execution, supplies a minimal environment, disables shell interpretation, bounds time and output, and records every attempt. It creates a receipt only for an accepted acknowledgement with the exact digest.
+
+A receipt is transport evidence, not issue resolution, security acceptance, Manual QA, certification, deployment permission or release approval. Provider dashboards remain authoritative for their own downstream workflow.
+
+## Upgrade and recovery
+
+Publish intentional adapter changes with a new semantic version and register that version explicitly. If execution fails, inspect the reason class and the provider's own safe logs; do not expose credentials or raw provider responses through EWAI. Retrying creates a new attempt and never rewrites history.
+
+Deleting or archiving an EWAI report affects local material only. External provider content cannot be recalled through this interface.

package/Docs/examples/error-report-adapter.md

@@ -0,0 +1,70 @@
+# A minimal, non-sending error-report adapter
+
+This example lets you validate an adapter package without a vendor account or network access. It **always rejects transport**. It must never report a ticket as created when nothing was sent.
+
+For a real integration, implement transport and return acceptance only after the provider accepts the immutable ZIP. Use the [versioned request and acknowledgement contract](../../skills-src/ewai-error-reporting/references/provider-contract.md).
+
+## Create the package
+
+Create `example-adapter/error-report-provider.json`:
+
+<!-- example: error-adapter-manifest -->
+```json
+{
+  "schema": "ewai.error-report-provider/v1",
+  "id": "example.support",
+  "name": "Example non-sending adapter",
+  "publisher": {"id": "example", "name": "Example Organisation"},
+  "version": "1.0.0",
+  "protocolVersion": "1",
+  "entrypoint": "bin/send-report"
+}
+```
+
+Create `example-adapter/bin/send-report`:
+
+<!-- example: error-adapter-script -->
+```javascript
+#!/usr/bin/env node
+let input = '';
+for await (const chunk of process.stdin) {
+  input += chunk;
+  if (Buffer.byteLength(input) > 65536) process.exit(1);
+}
+try {
+  const request = JSON.parse(input);
+  if (request.schema !== 'ewai.error-report-submission/v1' ||
+      typeof request.attemptId !== 'string' ||
+      !/^sha256:[a-f0-9]{64}$/.test(request.archiveDigest)) {
+    process.exit(1);
+  }
+  process.stdout.write(JSON.stringify({
+    schema: 'ewai.error-report-provider-ack/v1',
+    attemptId: request.attemptId,
+    archiveDigest: request.archiveDigest,
+    status: 'rejected',
+    externalReference: 'example-no-transport'
+  }) + '\n');
+} catch {
+  process.exitCode = 1;
+}
+```
+
+Make the entrypoint executable and validate the folder:
+
+```bash
+chmod +x ./example-adapter/bin/send-report
+ewai error-report adapter-validate ./example-adapter --project . --json
+```
+
+Validation reads the package and returns its identity and digests. It doesn't execute or trust the adapter. You don't need to register or submit a real report to complete this example.
+
+## Before building real transport
+
+The adapter receives one JSON request through stdin. Only the supplied finalised ZIP may be sent; don't collect extra logs, source or environment values. Never expose provider credentials or raw error responses through stdout.
+
+Registration explicitly trusts local code. The process has your operating-system permissions and **isn't OS-sandboxed**. Time/output limits and a minimal environment don't change that.
+
+A real accepted acknowledgement must repeat the exact attempt ID and archive digest and contain a bounded provider reference. Rejection, mismatches or execution errors leave a failed attempt, not a transport receipt.
+
+Use a new version and explicit registration when adapter code changes. See the [provider guide](../error-reporting-provider-guide.md) for registration, sending and receipt inspection.

package/Docs/examples/meeting-review.md

@@ -0,0 +1,76 @@
+# Review and promote one meeting statement
+
+This complete example uses fictional notes in a disposable, initialised EWAI project. It demonstrates the file handoff; no meeting platform, model call or real person's approval is involved. In real work, the named people must actually review and approve the material.
+
+## Create the source
+
+Save this as `meeting.md` in the project:
+
+<!-- example: meeting-source -->
+```markdown
+The support team agreed that the first export should include the ticket number and current status only.
+```
+
+Register and prepare it:
+
+```bash
+ewai meeting register ./meeting.md --classification internal --cloud-processing allowed --yes --project . --json
+ewai meeting prepare <source-id> --project . --json
+```
+
+Replace `<source-id>` with `source.sourceId` from registration. Save `source.digest` too. This example permits cloud processing only because the text is fictional. For real material, make the actual classification and processing decision before inspection.
+
+## Prepare and review the input
+
+In normal use, the meeting-evidence skill helps prepare candidates from the allowed source. A reviewer compares each proposed statement with the source and chooses a disposition. Here the complete one-candidate input is shown so you can see the handoff.
+
+Save this as `meeting-review.json`, replacing the two capitalised values with registration's actual ID and digest:
+
+<!-- example: meeting-review -->
+```json
+{
+  "bundle": {
+    "schema": "ewai.meeting-candidate-bundle/v1",
+    "sourceId": "SOURCE_ID_FROM_REGISTER",
+    "sourceDigest": "SOURCE_DIGEST_FROM_REGISTER",
+    "candidates": [
+      {
+        "id": "MEC-001",
+        "type": "decision",
+        "observedStatement": "The first export is limited to ticket identifiers and status.",
+        "interpretation": "Additional columns need a separate scope decision.",
+        "lineAnchors": [{"start": 1, "end": 1}],
+        "confidence": "high"
+      }
+    ]
+  },
+  "dispositions": [
+    {"candidateId": "MEC-001", "decision": "accepted"}
+  ]
+}
+```
+
+The observation is a concise paraphrase, not a pasted transcript excerpt. The interpretation remains distinct. For an amendment, include `replacementText` and `rationale`; rejected and deferred decisions need a rationale too. The [candidate schema](../../config/meeting-evidence-candidate.schema.json) and [implementation contract](../meeting-evidence-implementer-guide.md) specify the full boundary.
+
+Record the review:
+
+```bash
+ewai meeting review <source-id> --input ./meeting-review.json --reviewed-by "Example reviewer" --project . --json
+ewai meeting status <source-id> --project . --json
+```
+
+**At this point:** the review is saved privately, but there is no promoted evidence file. A review isn't a promotion.
+
+## Promote the accepted statement
+
+After the separate approval decision:
+
+```bash
+ewai meeting promote <source-id> --yes --approved-by "Example owner" --project . --json
+```
+
+Look under `SPECS/3.Evidence/meeting-evidence/<source-id>/` for `evidence.md` and `evidence.json`. They contain the accepted statement and provenance, not the raw source file. Promotion doesn't create an intent or approve Build.
+
+If the source changes, the old digest no longer matches. Prepare and review the current material; don't replace hashes in old evidence to force it through.
+
+Return to the [meeting guide](../meeting-evidence-user-guide.md).

package/Docs/examples/minimal-design-system.md

@@ -0,0 +1,67 @@
+# Install and select a small design-system pack
+
+Use a disposable initialised project for this exercise. It shows the distinction between a candidate folder, an installed pack and an approved project selection. In a real project, review the guidance with its owner before selecting it.
+
+## Create two files
+
+Create `example-design/pack.yaml` inside the project:
+
+<!-- example: design-manifest -->
+```yaml
+schema: ewai.pack/v1
+id: org.example.product-design
+name: Example Product Design
+description: A small reviewed design example for a support tool.
+version: 1.0.0
+type: design-system
+requires: []
+design_system:
+  compatibility:
+    ewai: 0.x
+  provenance:
+    kind: owner-declared
+    summary: Fictional example for learning the pack workflow.
+  contributions:
+    - id: recovery
+      kind: principles
+      title: Recover from a failed action
+      source: recovery.md
+      applicability: [prototype, review]
+      required: true
+```
+
+Create `example-design/recovery.md`:
+
+<!-- example: design-content -->
+```markdown
+# Recover from a failed action
+
+Keep the user's entered information when an action fails. Explain what didn't complete and provide a clear retry route. Don't show a success message until the action succeeds.
+
+Review the error and empty states as well as the successful screen.
+```
+
+## Validate, install, then resolve
+
+```bash
+ewai design-system validate ./example-design --project . --json
+ewai design-system install ./example-design --scope project --expected-digest <digest-from-validation> --yes --project . --json
+ewai design-system resolve org.example.product-design --project . --json
+```
+
+Copy the complete `digest` value, including `sha256:`, from validation. Installation should report `installed`. Resolve the **installed ID**, not the candidate folder.
+
+Resolve returns an `effectiveDigest` for the resolved guidance. This can differ from the candidate's installation digest. Review the dependencies and contributions before proceeding.
+
+## Select the resolved guidance
+
+```bash
+ewai design-system select org.example.product-design --expected-digest <effectiveDigest-from-resolve> --approved-by "Example owner" --yes --project . --json
+ewai design-system status --project . --json
+```
+
+Status should now show a selected root, and `SPECS/5.Strategy/design-system.md` records the selection. This is a tutorial selection, not evidence that a real product owner approved this example.
+
+To apply it, you need an existing UI-bearing delivery. Continue with [application and review](../design-systems/design-system-user-guide.md#apply-it-to-ui-work); installing this pack doesn't create that delivery.
+
+An edited candidate or changed installed content needs fresh validation and review. Don't reuse an old digest, overwrite an installed version or silently substitute the bundled fallback for the intended project pack.