@thebackstoryis/engineering-with-ai 0.2.9

package/skills-src/ewai-design-system-apply/references/application-contract.md

@@ -0,0 +1,36 @@
+# Design-system application contract
+
+## Evidence flow
+
+The project pin resolves one root and its explicit dependencies. Contributions applicable to UI Design, Prototype, the affected surface, and the stated focus become candidates for the existing EWAI context assembler. Required contributions are mandatory; focus-matched contributions are relevant; the rest can be deferred. Mandatory overflow is non-ready and emits no provider payload.
+
+Contextual personas are selected from installed core, project-local, personal, and entitled premium catalogues. Their safe identity and reason are visible while their definitions remain private. Persona advice remains subordinate to observable product evidence and accountable human decisions.
+
+## Receipt and manifest
+
+Successful application creates immutable, digest-addressed JSON and Markdown evidence under:
+
+```text
+SPECS/6.Build/<delivery>/ui-design-assets/design-system/
+```
+
+The JSON uses `ewai.design-system-receipt/v1`. A newly stamped delivery uses `ewai.prototype-manifest/v3`; its design-system section declares:
+
+```json
+{
+  "designSystem": {
+    "receiptPath": "ui-design-assets/design-system/receipt-<digest>.json",
+    "receiptDigest": "sha256:<digest>",
+    "effectiveDigest": "sha256:<digest>"
+  }
+}
+```
+
+The v3 manifest also links the immutable reviewed prototype plan and final persona-guided design cycle. Historical v1 and v2 manifests remain readable. A newly stamped UI Design phase must complete the v3 review linkage before it can complete.
+
+## Recovery
+
+- `mandatory-overflow`: narrow focus, explicitly increase the bounded budget, or split the surface.
+- stale selected system: inspect, re-resolve, and obtain a new named selection approval.
+- receipt mismatch: do not edit immutable evidence; reapply and link the newly returned receipt.
+- missing premium personas: continue with applicable core/project/personal personas; premium access is never required for correctness.

package/skills-src/ewai-design-system-author/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: ewai-design-system-author
+description: Build or evolve a governed EWAI design-system pack from owner-declared and observable project evidence. Use when a team wants to capture reusable experience principles, foundations, tokens, components, interactions, content, states, accessibility, motion, prohibited patterns, or review rules without selecting or applying the pack.
+---
+
+# EWAI Design System Author
+
+Build a portable, data-only design-system pack whose evidence, contributors, and installation decision remain visible to its owner. Read [the authoring contract](references/authoring-contract.md) before authoring or changing a pack.
+
+## Workflow
+
+1. Confirm whether the candidate is intended for the project-local or personal catalogue. Do not infer permission to install, select, apply, publish, or release it.
+2. Gather owner-declared and observed evidence. Label inferred material explicitly, and preserve every conflict until the owner resolves it.
+3. Engage only the personas relevant to the design question. Show each active persona's safe reference, name, tier, matched signals, and reason while it is engaged.
+4. The standard path must work with core, project-local, and personal personas. Premium personas may improve the critique when entitlement and installation already exist, but you must not download them or copy premium persona bodies into the pack, receipts, logs, or output.
+5. Author `pack.yaml` and its referenced Markdown contributions. Use qualified `pack-id:contribution-id` replacement targets; never rely on filesystem precedence.
+6. Run `ewai design-system validate FOLDER --project PROJECT --json`. Resolve every schema, containment, compatibility, size, or digest error.
+7. Present the safe validation result and proposed scope. Pause for explicit confirmation.
+8. Only after confirmation, run `ewai design-system install FOLDER --scope project|personal --expected-digest DIGEST --yes --project PROJECT --json`.
+9. Report that installation does not select the pack. Selection and application are separate governed decisions.
+
+## Boundaries
+
+- Never overwrite an installed pack or silently resolve an identity conflict.
+- Never select or apply a newly installed pack.
+- Never treat persona advice, a generated design system, or a successful validation as owner approval.
+- Never place executable code, remote content, credentials, or premium persona bodies in the pack.
+- Never claim a pack is visually accepted, accessible, production-ready, published, or released without the corresponding human evidence.

package/skills-src/ewai-design-system-author/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "EWAI Design System Author"
+  short_description: "Build governed reusable design-system packs"
+  default_prompt: "Use $ewai-design-system-author to build or evolve a governed design-system pack from project evidence."

package/skills-src/ewai-design-system-author/references/authoring-contract.md

@@ -0,0 +1,38 @@
+# Design-system authoring contract
+
+## Candidate layout
+
+```text
+candidate/
+├── pack.yaml
+├── experience-promise.md
+├── principles.md
+└── components/
+    └── buttons.md
+```
+
+Only `pack.yaml` and files explicitly referenced by its contributions are installed. Symlinks, remote URLs, traversal, missing files, oversized content, duplicate identities, and incompatible EWAI majors are rejected.
+
+## Manifest essentials
+
+The manifest uses `schema: ewai.pack/v1`, `type: design-system`, a globally qualified ID, semantic version, explicit dependencies, EWAI compatibility, provenance, and one or more contributions. Each contribution declares its stable ID, kind, title, relative source, applicability, whether it is mandatory, and qualified replacement targets.
+
+## Evidence ledger
+
+Keep these classes separate:
+
+- `owner-declared`: an accountable owner states the intended experience or rule.
+- `observed`: repository, product, research, or rendered-interface evidence supports it.
+- `inferred`: a useful hypothesis that still needs confirmation.
+- `conflict`: evidence or stakeholder expectations disagree; do not erase the disagreement.
+
+## Review questions
+
+- What experience promise should remain true across features and channels?
+- Which existing components and patterns are already authoritative?
+- Which rules are mandatory, and which are contextual guidance?
+- Which states, responsive conditions, accessibility needs, and content behaviours are missing?
+- What is prohibited because it harms trust, clarity, usability, brand, or maintainability?
+- Which local or premium personas add a relevant perspective, and why are they active now?
+
+Persona output is advice. The project owner resolves conflicts and approves the pack digest, installation scope, later selection, later application, Manual QA, and release.

package/skills-src/ewai-design-system-review/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: ewai-design-system-review
+description: Review a prototype or implemented interface against the immutable EWAI design-system application receipt that shaped it. Use after a UI artefact exists, during UI Design iteration, before Manual QA, or when assessing whether a local deviation should remain local or be proposed for a later pack-authoring cycle.
+---
+
+# EWAI Design System Review
+
+Produce an evidence-cited, advisory conformance review without rewriting historical evidence or granting acceptance. Read [the review contract](references/review-contract.md) completely before reviewing.
+
+## Workflow
+
+1. Locate the selected artefact, its `ewai.prototype-manifest/v3`, the linked immutable design-system receipt, reviewed plan, and final persona review cycle. Stop if linkage or digests do not validate. Historical v1/v2 manifests remain readable but do not satisfy a newly stamped v3 delivery.
+2. Review the artefact against the contributions recorded as selected in that receipt—not against a newer pack that did not shape it.
+3. Separate evidence channels: source inspection, rendered viewport, interaction, assistive-technology, user research, Manual QA, and release. Mark an unperformed channel absent; missing evidence must remain missing.
+4. Swap in only relevant product, design, accessibility, content, domain, and engineering personas from the core, project-local, personal, and already installed premium catalogues. Show every active persona’s safe reference, name, tier, matched signals, and reason. The standard host-model path remains complete without premium access, and you must never expose or persist premium persona bodies.
+5. Use `$ewai-prototype-iteration` to recompute the relevant rendered-design ensemble, record its findings, and assess each finding exactly once. Then classify design-system conformance as `aligned`, `approved-deviation`, or `unresolved` using the exact rules in the reference.
+6. Distinguish delivery-local correction, explicitly approved local deviation, and reusable learning. Route reusable learning as a proposal for a later design-system authoring cycle.
+7. Present findings, evidence limitations, active personas, and named next decisions. The review does not approve a deviation, Build, Manual QA, accessibility, publication, deployment, or release.
+
+## Boundaries
+
+- Never edit or replace the installed or upstream pack during review.
+- Never rewrite the immutable receipt or review against unrecorded context.
+- Never turn persona agreement into evidence about real users.
+- Never infer rendered, responsive, keyboard, assistive-technology, user, Manual QA, or release evidence from source inspection alone.
+- Never use `approved-deviation` without existing cited evidence from a named accountable owner.

package/skills-src/ewai-design-system-review/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "EWAI Design System Review"
+  short_description: "Review surfaces against design receipts"
+  default_prompt: "Use $ewai-design-system-review to review this surface against its design-system receipt."

package/skills-src/ewai-design-system-review/references/review-contract.md

@@ -0,0 +1,40 @@
+# Design-system conformance review contract
+
+## Inputs
+
+- The selected prototype or implemented surface.
+- Its validated `ewai.prototype-manifest/v3`, including the linked reviewed plan and final persona review cycle. Historical v1/v2 evidence can be inspected but does not satisfy a newly stamped v3 contract.
+- The linked immutable `ewai.design-system-receipt/v1`.
+- Any separately captured rendered, interaction, assistive-technology, research, owner-decision, Manual QA, or release evidence.
+
+Current pack content may inform a separately labelled change proposal, but it cannot silently replace the receipt as the historical baseline.
+
+## Finding classifications
+
+- `aligned`: cited artefact evidence satisfies a cited contribution recorded in the receipt.
+- `approved-deviation`: the artefact differs, and a named accountable owner has already approved that exact delivery-local deviation in cited evidence. The review cannot create this approval.
+- `unresolved`: the artefact differs, evidence is missing or contradictory, or no accountable deviation approval exists.
+
+Each finding records its classification, receipt contribution ID and digest, artefact location, evidence channel, observation, user or engineering impact, active persona references, and required owner action.
+
+## Evidence matrix
+
+Report each channel independently:
+
+| Channel | What it can support | What absence means |
+|---|---|---|
+| Source inspection | structure, declared semantics, implementation patterns | rendered behaviour is unknown |
+| Rendered viewport | visible hierarchy, layout, responsive appearance | visual conformance is unknown |
+| Interaction | focus, state transitions, error and recovery behaviour | interaction conformance is unknown |
+| Assistive-technology | practical screen-reader or equivalent behaviour | accessibility is not assured |
+| User research | observed representative-user needs and outcomes | persona simulation is not user evidence |
+| Manual QA | named human acceptance within its recorded scope | the feature remains unaccepted |
+| Release | authorised publication, deployment, or production decision | the result is not release-approved |
+
+Automated tests and static inspection can identify valuable findings. They do not certify accessibility or quality.
+
+## Persona and learning boundary
+
+Personas are advisory lenses. Record safe active references and reasons, never definitions or managed bodies. Project-local and personal personas may add context; installed premium personas may deepen critique but are optional.
+
+The review must not change an installed or upstream pack. A pattern likely to benefit other deliveries becomes a cited proposal for a later authoring cycle, where its evidence, conflicts, versioning, installation, selection, and owner approval can be governed separately.

package/skills-src/ewai-error-reporting/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: ewai-error-reporting
+description: Create, inspect, finalise and explicitly hand off privacy-safe local EWAI error-report packages. Use when an EWAI command, dashboard action, guided workflow or agent integration fails; when a user asks to report a problem; when local automatic draft capture needs to be configured; or when an exact finalised ZIP must be prepared for manual email or an explicitly registered generic provider adapter.
+---
+
+# EWAI Error Reporting
+
+Keep error reporting local-first, inspectable and honest about custody. The base capability requires no hosted service and never transmits a report automatically.
+
+## Method
+
+1. Inspect local state with `ewai error-report status --project . --json`.
+2. Create a bounded draft with `ewai error-report create`, or use **Report this problem** in the dashboard. Describe expected behaviour, actual behaviour and reproducible steps without secrets, absolute paths, client data, source, prompts, persona bodies or raw logs.
+3. Read the draft with `ewai error-report show REPORT --project . --json`. Inspect its description, diagnostics and redaction summary before finalising it.
+4. Revise incorrect narrative fields with `ewai error-report update`. A changed finalised report becomes a new draft revision; never rewrite an immutable package.
+5. Finalise with `ewai error-report finalise REPORT --project . --json`. Retain the returned exact archive digest.
+6. Choose one explicit handoff:
+   - Prepare a manual email with `ewai error-report prepare-email REPORT --expected-digest DIGEST --launch --project . --json`. Treat `prepared-not-sent` literally. Reveal the ZIP, attach the ZIP manually, review the recipients and send it yourself.
+   - List registered providers, then use `ewai error-report send REPORT --provider ID --expected-digest DIGEST --yes --project . --json`. Confirm that the provider is trusted local code before sending.
+7. Read attempts and receipts with `ewai error-report receipts REPORT --project . --json`. An accepted receipt proves transport of that digest only, not issue resolution.
+8. Archive or delete local material only with explicit confirmation. Explain that external provider material cannot be recalled by deleting a local report.
+
+## Automatic local drafts
+
+Automatic local draft capture is opt-in:
+
+```bash
+ewai error-report settings --automatic-local-drafts true --project . --json
+```
+
+This setting creates deduplicated local drafts only. It does not finalise, email, invoke a provider, attach a file or send anything. Keep the setting separate from every remote handoff decision.
+
+## Custody boundaries
+
+- Store operational material under `.ewai-pipeline/error-reports/`; do not promote it into `SPECS/` or commit it as project truth.
+- Use only the closed diagnostic fields supplied by EWAI. Never add environment values, credentials, absolute paths, repository names, source, SPECS bodies, prompts, responses, personas or raw logs.
+- Require the exact finalised digest for email or provider handoff. If the report changes, prepare and approve the new revision separately.
+- Never claim an email was sent, a ZIP was attached, or a provider accepted a report without the corresponding evidence.
+- Treat provider adapters as trusted local code. Registration is an authority decision; package validation is not a security certification.
+- Keep error reporting separate from Manual QA, security acceptance, deployment and release authority.
+
+Read [references/provider-contract.md](references/provider-contract.md) only when validating, registering, authoring or troubleshooting a generic provider adapter.
+
+## Stop conditions
+
+Stop before finalisation or handoff when the draft contains sensitive or ambiguous material, the package digest is stale, the intended recipient or provider is unclear, or explicit confirmation is absent. Preserve failure attempts; do not turn them into success receipts.

package/skills-src/ewai-error-reporting/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "EWAI Error Reporting"
+  short_description: "Create and hand off privacy-safe local reports"
+  default_prompt: "Use $ewai-error-reporting to create, inspect and hand off a local EWAI error report."

package/skills-src/ewai-error-reporting/references/provider-contract.md

@@ -0,0 +1,74 @@
+# Generic error-report provider contract
+
+Use this contract only for organisation-owned or commercial adapters that transport an already-finalised EWAI error-report ZIP. An adapter is trusted local code. EWAI ships no built-in vendor connector and no hosted reporting service.
+
+## Package shape
+
+The adapter folder must be a real, non-symbolic directory containing `error-report-provider.json`:
+
+```json
+{
+  "schema": "ewai.error-report-provider/v1",
+  "id": "example.support",
+  "name": "Example support transport",
+  "publisher": { "id": "example", "name": "Example Ltd" },
+  "version": "1.0.0",
+  "protocolVersion": "1",
+  "entrypoint": "bin/send-report"
+}
+```
+
+Only those fields are accepted. The entrypoint must be a relative, executable, regular file inside the adapter root. Symbolic links, path escape, oversized packages and unsafe identifiers are rejected.
+
+Validation reads and digests the package but does not trust or execute it:
+
+```bash
+ewai error-report adapter-validate ./adapter --project . --json
+```
+
+Registration requires `--yes` because it trusts local code. Registration does not execute the adapter:
+
+```bash
+ewai error-report adapter-register ./adapter --project . --yes --json
+```
+
+EWAI rejects same-version package digest drift. Submission re-reads the current manifest and package and refuses execution when either digest differs from the registered record.
+
+## Submission protocol
+
+EWAI writes one JSON object to the adapter's stdin:
+
+```json
+{
+  "schema": "ewai.error-report-submission/v1",
+  "attemptId": "uuid",
+  "reportId": "report_example",
+  "revision": 1,
+  "archiveDigest": "sha256:...",
+  "packagePath": "/absolute/runtime/path/report_example-r1.zip",
+  "packageSize": 1234
+}
+```
+
+The path is supplied only to the explicitly trusted local process. The process receives a minimal environment and must treat the ZIP as immutable. It must emit exactly one bounded JSON acknowledgement to stdout:
+
+```json
+{
+  "schema": "ewai.error-report-provider-ack/v1",
+  "attemptId": "uuid",
+  "archiveDigest": "sha256:...",
+  "status": "accepted",
+  "externalReference": "provider-ticket-123"
+}
+```
+
+The `attemptId` and `archiveDigest` must exactly match the request. `status` may be `accepted` or `rejected`; EWAI records only an exact accepted acknowledgement as a receipt. Extra fields, malformed JSON, timeout, oversized output, non-zero exit, digest mismatch and rejection produce a retained failed attempt.
+
+## Security and assurance boundary
+
+- Use `shell: false` behaviour in the entrypoint and never reinterpret request fields as shell syntax.
+- Do not read files other than the supplied finalised ZIP.
+- Do not return credentials, response bodies or sensitive provider errors on stdout.
+- Apply provider authentication inside the adapter's own secure configuration boundary; do not add secrets to the EWAI report or manifest.
+- Treat the receipt as transport evidence, not resolution, certification, security acceptance, Manual QA or release approval.
+- Version and review adapter code. Re-register every intentional code change under a new version.

package/skills-src/ewai-evidence-depth/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: ewai-evidence-depth
+description: Prepare, review, record, and compare reproducible seven-dimensional Archaeology and Discovery depth using a fresh EWAI Source Map, attributed owner evidence, stable gaps, and contextual core, project, personal, and optional installed premium personas. Use when deciding how deeply to investigate an existing project, repeating Archaeology or Discovery across people or model sessions, explaining different outputs from the same project, or verifying that context and token reductions have not reduced engineering evidence coverage.
+---
+
+# EWAI Evidence Depth
+
+Choose investigation depth from governed evidence rather than repository size, ticket count, or model confidence. Keep observed repository facts, owner declarations, persona advice, named depth decisions, and gap grouping visibly separate.
+
+Read [the evidence-depth contract](references/evidence-depth-contract.md) completely before creating inputs, recording a review, comparing runs, or validating another implementation.
+
+## Prepare the run
+
+1. Resolve the project and configured SPECS root from `.ewai-pipeline/project.json`.
+2. Inspect Source Map freshness with `ewai archaeology depth-status --project <path> --json`.
+3. If missing or stale, run `ewai index refresh --project <path> --json`. Do not prepare from stale repository evidence.
+4. Capture owner evidence as bounded identifiers, authority, answer and reason codes, and evidence digests. Never put free-text answers, source bodies, secrets, absolute paths, or managed persona bodies in the input.
+5. Run `ewai archaeology depth-prepare --project <path> --input <project-relative-input.json> --json`. Omit `--input` when no attributed owner evidence exists.
+6. Present all seven recommendations, coverage, exclusions, failures, stable gaps, adaptive questions, and active personas. Do not collapse dimensions into one overall depth.
+
+The dimensions are architecture, data, security, product, delivery, governance, and operations. A recommendation is advisory until a named person selects every dimension.
+
+## Engage personas contextually
+
+Use the returned active ensemble for the current dimension. Swap relevant core, project, personal, and installed premium personas in and out as the evidence concern changes.
+
+- Show persona name, tier, engagement reason, and the concern where it is active.
+- Keep the standard-model baseline complete when premium personas are absent.
+- Never download or sync premium personas as part of this workflow.
+- Treat personas as advisory lenses. They cannot create owner evidence, choose depth, group gaps, approve Build, accept Manual QA, or release software.
+
+## Review and record
+
+Ask a named accountable owner to:
+
+1. select `bounded`, `standard`, or `deep` independently for every dimension;
+2. give a substantive rationale whenever reducing the recommendation;
+3. review contradictions and unresolved questions;
+4. assign every stable gap to an explicit group and disposition;
+5. confirm the exact preparation digest being reviewed.
+
+Record the complete review with:
+
+```bash
+ewai archaeology depth-record --project <path> --input <project-relative-review.json> --json
+```
+
+Recording creates immutable evidence under the configured `SPECS/3.Evidence/discovery-depth/runs/` root. It is not delivery, security, Manual QA, deployment, or release approval.
+
+## Compare repeated runs
+
+Compare exact stored runs without rescanning the repository:
+
+```bash
+ewai archaeology depth-compare <left-run-id> <right-run-id> --project <path> --json
+```
+
+Explain change in this order: governed inputs, evidence, personas, selected depth, coverage, stable gaps, then grouping. Do not treat wording variation as material when the structured identity is unchanged. Do not call a comparison reproducible when a derived fingerprint changes without an upstream explanation.
+
+## Preserve the performance boundary
+
+Use the Source Map projection and bounded identifiers rather than loading repository bodies into the depth ledger. Compare stored fingerprints rather than repeating analysis. Treat exclusions, inventory-only files, sensitive files, oversized files, and analysis failures as visible coverage facts.
+
+Token reduction is acceptable only when the same material engineering surfaces, constraints, standards, gaps, and tests remain discoverable. If coverage decreases or unexplained variance appears, restore the missing evidence context before continuing.
+
+## Use the available surfaces
+
+- CLI: `ewai archaeology depth-status|depth-prepare|depth-record|depth-compare`
+- MCP: `ewai_evidence_depth_status|prepare|record|compare`
+- Dashboard: Guided Setup → Evidence depth
+
+Keep hosted feedback collection, production code interception, runtime policy enforcement, and automatic persona installation outside this workflow.

package/skills-src/ewai-evidence-depth/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "EWAI Evidence Depth"
+  short_description: "Reproducible archaeology and discovery depth"
+  default_prompt: "Use $ewai-evidence-depth to prepare and review a reproducible evidence-depth run for this project."

package/skills-src/ewai-evidence-depth/references/evidence-depth-contract.md

@@ -0,0 +1,127 @@
+# Evidence-depth contract
+
+## Authority model
+
+| Concern | Authority |
+|---|---|
+| Repository state | Fresh EWAI Source Map; observed or inferred only |
+| Business purpose and intended behaviour | Attributed owner declaration or confirmation |
+| Investigation lenses | Contextual personas; advisory only |
+| Selected depth | Named accountable reviewer |
+| Stable gap identity | Deterministic structured condition and evidence references |
+| Gap grouping | Explicit named review; separate from gap identity |
+| Build, Manual QA, deployment, release | Existing EWAI gates; never an evidence-depth run |
+
+## Preparation input
+
+The normalized preparation records:
+
+- project fingerprint;
+- fresh Source Map run, digest, profile digest, and coverage;
+- contract, pack, and provider capability revisions;
+- explicit exclusions;
+- predecessor run when applicable;
+- bounded active persona identifiers, tiers, and reason codes;
+- bounded evidence identifiers, authority, kind, and digests;
+- exactly seven dimension recommendations, drivers, evidence references, and coverage;
+- deterministic gap conditions;
+- a proposed grouping strategy, which does not modify gap identity.
+
+Do not include prompt text, generated answer text, transcript or source bodies, absolute paths, secrets, raw premium persona content, or unbounded model output.
+
+## Owner evidence input
+
+An optional preparation input file has this form:
+
+```json
+{
+  "focus": "security and recovery",
+  "ownerEvidence": [
+    {
+      "id": "owner:security-boundary",
+      "dimension": "security",
+      "authority": "confirmed",
+      "evidenceDigest": "sha256:bounded-evidence-identifier",
+      "answerCode": "internal-users-only",
+      "reasonCode": "named-owner-review",
+      "contradiction": "none"
+    }
+  ]
+}
+```
+
+Allowed authority values are `declared` and `confirmed`. Allowed contradiction values are `none`, `declared-versus-observed`, `observed-versus-observed`, `declared-versus-declared`, and `unresolved`.
+
+## Review input
+
+A review must bind to one exact preparation digest, name the reviewer, cover every dimension exactly once, and assign every eligible gap exactly once.
+
+```json
+{
+  "schema": "ewai.evidence-depth-review/v1",
+  "expectedPreparationDigest": "sha256:...",
+  "reviewedBy": "Named owner",
+  "dimensions": [
+    {
+      "id": "architecture",
+      "selectedDepth": "deep",
+      "rationale": ""
+    }
+  ],
+  "grouping": {
+    "strategy": "user-outcome",
+    "assignments": [
+      {
+        "gapId": "GAP-ARC-...",
+        "groupId": "platform-boundary",
+        "disposition": "owned"
+      }
+    ]
+  }
+}
+```
+
+Repeat the dimension object for architecture, data, security, product, delivery, governance, and operations. Allowed depths are `bounded`, `standard`, and `deep`. Reducing a recommendation requires a substantive rationale. Allowed grouping dispositions are `owned`, `shared`, `deferred`, and `excluded`.
+
+## Stable identity
+
+Exclude timestamps, filesystem roots, ordering differences, and generated prose from preparation identity. Include the project and Source Map fingerprints, contract and pack versions, provider capability revision, exclusions, persona identities, evidence identities, dimension structure, coverage, and structured gaps.
+
+A stable gap ID is derived from:
+
+- dimension;
+- condition;
+- current-state code;
+- intended-state code;
+- sorted evidence references.
+
+Owner assignment, contradiction state, disposition, and later grouping are reviewable state around the gap; grouping never replaces or renames the gap.
+
+## Comparison order
+
+Compare fingerprints in this order:
+
+1. governed inputs;
+2. evidence;
+3. personas;
+4. owner-selected depth;
+5. coverage;
+6. stable gaps;
+7. grouping.
+
+A changed grouping with unchanged gaps is explainable. A changed coverage or gap fingerprint without a material upstream change is unexplained variance and makes the comparison non-reproducible.
+
+## Failure and recovery states
+
+| State | Required action |
+|---|---|
+| `source-map-missing` | Run `ewai index refresh --project <path> --json` |
+| `source-map-stale` | Refresh the Source Map and prepare again |
+| `not-prepared` | Prepare a run after confirming evidence inputs |
+| stale preparation digest | Read the latest workspace and repeat named review |
+| missing depth decision | Add exactly one decision for every dimension |
+| reduced depth without rationale | Capture accountable rationale or restore the recommendation |
+| unassigned gap | Assign an explicit group and disposition |
+| unexplained comparison variance | Restore missing evidence context or retain the run as non-reproducible |
+
+Never recover by silently dropping a failed, excluded, contradictory, or unknown surface.

package/skills-src/ewai-intent/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: ewai-intent
+description: Turn an idea, problem, request, or existing feature into a project-local EWAI intent with explicit outcomes, journeys, constraints, evidence, acceptance criteria, and persona attachments. Use when Codex needs to create, enrich, reconcile, or review a file under SPECS/2.Purpose/intents before planning or implementation.
+---
+
+# EWAI Intent
+
+Resolve the SPECS root from `.ewai-pipeline/project.json`, then create intent truth under its `2.Purpose/intents/` directory. Do not assume SPECS is at the workspace root and do not write application code during Intent.
+
+If the request spans several independently valuable outcomes or the user wants to shape an initiative, use `$ewai-shape-intents` before refining any individual intent. When an intent belongs to an approved map, read that map and preserve its relationship contract.
+
+## Create the intent
+
+When the local dashboard is available, **Intent Studio** is the preferred guided route for one intent. It implements the same portable contract as the CLI while keeping a recoverable project-local draft:
+
+1. Open **Intent Studio** and choose **Create a new intent** or **Reconcile an eligible draft intent**.
+2. Work through the evidence spine. Each save advances the project-local draft revision; stale browser revisions must be reloaded rather than overwritten.
+3. Treat the standard host-model baseline as complete. Actively engaged personas from project, core, installed premium, and personal libraries are optional contextual lenses. The interface must show their tier, matching signals, and engagement reason as the section changes.
+4. Use **Copy AI review hand-off** when a host-model conversation would help. The copied prompt is advisory and must not alter the draft, make an approval, or invoke a hidden model endpoint.
+5. In Review, resolve blocking omissions, check exact canonical destinations, and, for reconciliation, compare the proposed before and after values.
+6. Require a named person to approve the current revision. That decision creates or reconciles intent truth only; it does not approve Build, Manual QA, certification, deployment, or release.
+
+If premium personas are not installed, continue with the standard baseline and any available project or core personas. Never sync or download premium content as a side effect of intent work.
+
+1. Read `pipeline.yaml` and applicable constraints from the configured SPECS root.
+2. Check for an existing intent with the same or overlapping outcome.
+3. Identify the primary user or operator and any decision-maker, affected, assurance, or adversarial personas.
+4. Before finalising the draft, create a delivery-shape preview:
+   - `single` when the intent is one coherent, reviewable delivery slice;
+   - `split` when it spans independently valuable outcomes that should become child intents before delivery;
+   - `decision-required` when one or more owner decisions are needed before the split is safe.
+5. Show the preview to the user with three choices: keep as one intent, split into the suggested child intents, or refine the split. Record the reviewed decision if the user gives one; otherwise keep it as `not-reviewed`.
+6. Create the draft with:
+
+```bash
+ewai intent create <slug> \
+  --domain <domain> \
+  --title "<title>" \
+  --persona <persona-ref>:<role>:<depth> \
+  --delivery-shape <reviewed-delivery-shape.yaml>
+```
+
+7. Replace the generated section prompts with evidence-backed content, including its approved dependencies, relationships, and delivery-shape preview.
+8. Keep unresolved product choices visible under Open decisions.
+
+## Delivery-shape discipline
+
+Do not wait until Plan or Build to discover that an intent is too large. An intent should normally be split before delivery when it contains multiple user journeys, actor groups, bounded capabilities, data ownership changes, integrations, security or compliance decisions, or acceptance evidence that cannot be verified cleanly in one pass.
+
+Suggested child intents must be product or operational outcomes, not technical layers. Use `$ewai-shape-intents` when the user accepts a split or wants to refine a broader set of related work. If the user explicitly chooses to keep a large intent together, record the rationale in `delivery_shape.reviewed_decision` and keep the delivery risk visible.
+
+## Persona discipline
+
+Use depth 1 for awareness through depth 5 for a burning, evidence-grade need. Persona attachments describe design and acceptance needs; they do not grant permissions.
+
+Use project persona references from `SPECS/1.Scope/personas/` or installed pack identifiers. Do not assume professional personas are licensed.
+
+Persona output is a hypothesis or challenge, not participant evidence. Record interview, workshop, repository, policy, or research evidence separately and preserve named human accountability for decisions.
+
+## Conditional policy design facts
+
+When the project has an enabled organisation policy baseline, use `$ewai-organisation-policy` to identify policy-material design facts while refining the intent. Preserve whether each fact is observed evidence, a model proposal, or a persona hypothesis. Show the active persona tier and engagement reason, then require a named human to confirm or reject every proposed fact. Do not delay material facts until Build, and do not create policy work for a `not-configured` project.
+
+## Completion boundary
+
+An intent is ready for Plan only when its desired outcome, personas, journeys, acceptance criteria, constraints, dependencies, delivery shape, and open decisions are explicit enough to test. Mark uncertainty rather than inventing repository behaviour.
+
+Read [intent contract](references/intent-contract.md) for the portable schema and completion rules.

package/skills-src/ewai-intent/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "EWAI Intent"
+  short_description: "Create persona-grounded project intents"
+  default_prompt: "Use $ewai-intent to turn this idea into a project-local, persona-grounded EWAI intent."

package/skills-src/ewai-intent/references/intent-contract.md

@@ -0,0 +1,42 @@
+# Intent contract
+
+Intent files use `ewai.intent/v1` frontmatter and live at:
+
+```text
+SPECS/2.Purpose/intents/<domain>/<slug>.md
+```
+
+Required metadata:
+
+- `slug`: stable lower-kebab identifier.
+- `title`: human-readable outcome name.
+- `status`: `draft`, `ready`, `superseded`, or `retired`.
+- `intent_map`: optional approved intent-map slug.
+- `personas`: zero or more `{ ref, role, depth, reason? }` attachments.
+- `relationships`: zero or more `{ type, target, rationale? }` connections using an exact `<domain>/<slug>` target.
+- `delivery_shape`: early preview of whether this should deliver as one intent, split before delivery, or pause for a split decision.
+
+`delivery_shape` uses:
+
+- `recommendation`: `single`, `split`, or `decision-required`.
+- `reason`: why the current shape is or is not a manageable delivery unit.
+- `suggested_children`: possible child intent slices, each with optional `domain`, `slug`, `title`, `outcome`, and `depends_on`.
+- `blocking_questions`: owner questions that must be answered before a safe split or delivery.
+- `reviewed_decision`: `keep-as-one`, `split`, `refine-split`, `defer`, or `null` when not yet reviewed.
+
+Required narrative sections:
+
+- Problem
+- Desired outcome
+- Users and personas
+- Journeys
+- Acceptance criteria
+- Constraints
+- Dependencies and relationships
+- Delivery shape preview
+- Evidence
+- Open decisions
+
+An intent should normally be split before delivery when it contains multiple independently valuable outcomes, materially different user journeys, separate actor groups, separate integrations, load-bearing security or compliance decisions, or acceptance criteria that cannot be verified cleanly in one delivery cycle.
+
+Use `config/intent.schema.json` from the EWAI installation as the machine-readable metadata schema.