@thebackstoryis/engineering-with-ai 0.2.9

package/Docs/existing-project-onboarding-guide.md

@@ -0,0 +1,214 @@
+# Existing-project onboarding guide
+
+Use this guide when EWAI is joining a codebase whose behaviour, history, or purpose is not already represented by reliable project knowledge.
+
+Ask EWAI: “Help me set up this existing project. I'll explain what it's for, then we can decide whether to investigate the code and recover missing documentation.” You don't need to prepare an Archaeology bundle yourself. EWAI guides the setup and investigation; you supply the purpose, agree source permissions and review its conclusions. The commands below are available if you want to inspect or repeat individual steps.
+
+## Set up the workspace first
+
+If this project doesn't yet have EWAI configuration, EWAI asks where to keep its SPECS knowledge and initialises that structure after you agree. Check-in follows initialization. If it is already configured, EWAI uses the existing locator; you don't need a second knowledge tree.
+
+You provide a briefing and agree source permissions and context-import choices before an investigation. Those decisions apply whether or not you later choose Archaeology.
+
+If premium personas will be part of the investigation, [finish licence setup and installation](operations/premium-personas-setup.md) before starting it. Core personas remain available without a premium licence.
+
+## The governing principle
+
+Archaeology reconstructs what can be observed. It does not decide why the project ought to exist.
+
+Explain what the project is meant to achieve and check EWAI's summary before deep repository analysis. Current code, abandoned experiments and accidental behaviour aren't automatically evidence of what you want the project to do.
+
+## Agree the briefing and permissions
+
+EWAI asks you about:
+
+- purpose and business context;
+- primary users and desired outcomes;
+- important journeys and operational responsibilities;
+- known constraints and non-goals;
+- what is believed to be wrong, incomplete, or obsolete;
+- source material that may be examined;
+- confidentiality and cloud-processing constraints;
+- who can resolve disagreements between evidence and intent.
+
+For an initialized project, you can also run check-in directly:
+
+```bash
+ewai checkin --project .
+```
+
+Check-in reports the dashboard link, framework version, state integrity, standards policy, validators and persona-library status. Resolve any reported blocker before beginning the investigation.
+
+## Register supporting context safely
+
+If you have transcripts, emails, requirements or research, ask EWAI to register the folder with an explicit classification and processing decision. For direct registration, use:
+
+```bash
+ewai context register /path/to/source \
+  --project . \
+  --yes \
+  --label "Project discovery evidence" \
+  --classification confidential \
+  --cloud-processing denied
+```
+
+Registration does not make every statement true. When reviewing the findings, check that EWAI retains the source and distinguishes stated, proposed, agreed, implemented, superseded, contradicted, inferred and unknown material.
+
+## Choose whether to run Archaeology
+
+After you've explained the project and agreed which sources can be used, EWAI offers to investigate the existing code and reconstruct missing documentation. You decide whether that would help now. Archaeology doesn't start without your acceptance.
+
+If you decline, your briefing and permission decisions remain available. You can continue with [Guided Discovery](guided-discovery-facilitator-guide.md) and Doctor without reconstruction; the uninvestigated areas remain recorded as knowledge gaps. Context import is a separate choice, not a requirement to accept Archaeology. You can return to reconstruction later.
+
+The reconnaissance and reconstruction sections below describe what happens if you accept Archaeology. They don't replace the briefing or privacy checks above.
+
+## Run bounded reconnaissance
+
+EWAI first builds a broad map of:
+
+- repositories, languages, frameworks, and deployable units;
+- entry points, external integrations, data stores, and queues;
+- high-value user and operational workflows;
+- tests, schemas, documentation, and decision records;
+- ownership boundaries and likely knowledge gaps;
+- recent changes and historical seams worth deeper inspection.
+
+This first pass isn't an exhaustive file-by-file summary. Review the map with EWAI to choose where deeper investigation would be useful.
+
+EWAI uses the [Repository Source Map](repository-source-map-guide.md) during reconnaissance. To refresh it and inspect its coverage directly:
+
+```bash
+ewai index refresh --project . --json
+ewai index coverage --project . --json
+ewai index files --outcome analysis_failed --project . --json
+```
+
+Every non-excluded regular file remains visible even when EWAI has no deep parser for it. Treat `inventory_only`, `skipped_sensitive`, `skipped_oversized`, and `analysis_failed` as explicit limits on subsequent inference. Technology, stack, organisation, and project profiles may refine analysis, but they do not turn repository evidence into stakeholder truth.
+
+For already-extracted Power Platform or Salesforce projects, review the
+[platform export analysis guide](platform-export-analysis-guide.md), confirm the
+appropriate technology pack rather than relying on detection alone, and inspect
+the partial-platform count before drawing conclusions from Archaeology or Blast
+Radius. EWAI does not extract archives or connect to vendor environments.
+
+## Confirm purpose alignment
+
+Before deep reconstruction, EWAI shows how its inferred understanding compares with your briefing. Review each material difference using these classifications:
+
+| Classification | Meaning |
+| --- | --- |
+| Present | The repository supports the briefing. |
+| Partial | Some evidence exists, but the intended outcome is incomplete. |
+| Missing | The briefing expects behaviour with no supporting evidence. |
+| Conflicting | Current behaviour or history contradicts the briefing. |
+| Unknown | Available evidence cannot resolve the question. |
+
+If the code materially conflicts with the intended purpose, decide which interpretation is correct or explicitly bound what remains uncertain before continuing.
+
+## Select personas for investigation
+
+After reconnaissance, EWAI proposes a small group of relevant installed personas for the next investigation passes. You review the selection and reasons before proceeding. Useful perspectives may include product, user, architecture, operations, security, data, accessibility or assurance.
+
+Relevant project and premium personas can participate when available. EWAI shows the choice and reason; you can challenge a missing perspective. An installed persona is an analysis aid, not evidence about a real actor.
+
+The Archaeology workflow retains a persona-routing checkpoint. Its supporting validation commands include:
+
+```bash
+ewai archaeology prepare-personas SPECS/3.Evidence/archaeology/<bundle> --project .
+ewai archaeology validate-personas SPECS/3.Evidence/archaeology/<bundle> --project .
+```
+
+These commands operate on a prepared Archaeology bundle; they do not replace the conversational briefing and reconnaissance.
+
+## Deep reconstruction
+
+The investigation uses separate, bounded passes for:
+
+1. observable user and business behaviour;
+2. technology and deployment topology;
+3. domain language and data relationships;
+4. decisions, constraints, and historical change;
+5. standards and recurring implementation patterns;
+6. security, privacy, operations, and failure behaviour;
+7. risks, contradictions, and unresolved questions.
+
+Check the source paths, tests, commits, documents or human testimony cited for important conclusions. A missing source is a gap to investigate, not proof that the behaviour doesn't exist.
+
+## Review and curate
+
+EWAI validates the investigation bundle and prepares findings for your review before they can become canonical SPECS knowledge. To inspect those steps directly:
+
+```bash
+ewai archaeology validate SPECS/3.Evidence/archaeology/<bundle> --project .
+ewai archaeology prepare-review SPECS/3.Evidence/archaeology/<bundle> --project .
+```
+
+Review the proposed findings and reject, correct or narrow weak inferences. EWAI offers a guided filing walkthrough or you can review and file the material yourself. After the review, an explicit curation approval allows the following operation:
+
+```bash
+ewai archaeology curate SPECS/3.Evidence/archaeology/<bundle> \
+  --project . \
+  --yes \
+  --approved-by "Project Owner"
+
+ewai archaeology validate-completion SPECS/3.Evidence/archaeology/<bundle> --project .
+```
+
+Approved curation puts reviewed knowledge in its canonical home. Source evidence and investigation history remain under `SPECS/3.Evidence/archaeology/`. Check the proposed destinations before approving; curation isn't permission to overwrite an existing approved record without a separate change decision.
+
+## Decide what happens next
+
+Archaeology may reveal:
+
+- an intent ready for formalisation;
+- missing or stale standards;
+- architecture decisions that need confirmation;
+- project personas grounded in real evidence;
+- technical debt with a bounded blast radius;
+- an incident or risk requiring separate treatment;
+- contradictions that block delivery.
+
+After curation, EWAI offers to discuss upcoming features, interpret a roadmap you supply, or suggest changes grounded in the findings. You choose which ideas to develop. Materially different outcomes belong in separate intents; a large investigation report isn't automatically a single approved build.
+
+When Archaeology identifies a concrete change boundary, use [Blast Radius and Impact Routing](blast-radius-and-impact-routing-guide.md) to examine its bounded repository reach, possible consequences, relevant personas, and human review routes. Keep archaeology findings and the impact assessment distinct: Archaeology reconstructs broader project knowledge, while Blast Radius evaluates a specific proposed change against the current repository map.
+
+## When to pause the investigation
+
+Pause and resolve the issue with the appropriate owner if:
+
+- source material exceeds its approved processing classification;
+- credentials, secrets, or personal data appear unexpectedly;
+- repository evidence and owner purpose materially disagree;
+- generated findings lack traceable evidence;
+- a proposed persona is based on stereotype rather than observed actors;
+- curation would overwrite an existing approved record without a change decision.
+
+## Onboarding checklist
+
+- [ ] Owner briefing captured before deep analysis.
+- [ ] Context classification and processing permission recorded.
+- [ ] Archaeology was explicitly accepted or declined.
+- [ ] If accepted, the reconnaissance map was reviewed. If declined, known gaps were recorded and Discovery continued without claiming reconstruction.
+- [ ] Purpose discrepancies resolved or explicitly bounded.
+- [ ] Persona ensemble shown and confirmed.
+- [ ] If Archaeology ran, findings cite evidence and retain uncertainty.
+- [ ] If reconstruction is being curated, human review completed before that curation.
+- [ ] Follow-on work split into reviewable intents.
+
+## Related guides
+
+- [Guided Discovery facilitator guide](guided-discovery-facilitator-guide.md)
+- [Working with personas](working-with-personas.md)
+- [Repository Source Map](repository-source-map-guide.md)
+- [Blast Radius and Impact Routing](blast-radius-and-impact-routing-guide.md)
+- [Developer delivery guide](developer-delivery-guide.md)
+- [Troubleshooting and recovery](operations/troubleshooting-and-recovery.md)
+
+## Current contract sources
+
+- `README.md`
+- `src/context.mjs`
+- `src/archaeology.mjs`
+- `src/personas.mjs`
+- `tests/context.test.mjs`
+- `tests/archaeology.test.mjs`

package/Docs/explanation/core-concepts.md

@@ -0,0 +1,26 @@
+# The parts you'll use in EWAI
+
+These terms turn up while you're working. You don't need to learn them all before [starting a project](../tutorials/first-session.md).
+
+| Term | What it means in your work |
+| --- | --- |
+| Host | The AI tool you're talking to, such as Codex or Claude Code. It runs the guided conversation and supporting tools. |
+| Skill | Instructions that help the host perform a particular job. You can ask naturally; you don't need to invoke every skill by name. |
+| ewai-deliver | The coordinating skill for feature delivery. It brings other skills into the fourteen-stage workflow. |
+| Runtime | The CLI and shared domain code that read project state, validate inputs and record permitted operations. It doesn't make a human decision for you. |
+| Dashboard | A local interface to your project's work. Its loopback URL isn't a remote team workspace. |
+| SPECS | Scope, Purpose, Evidence, Constraints and Strategy: readable files for project knowledge and delivery evidence. |
+| Intent | One proposed outcome, with its context, boundaries and acceptance criteria. `support/export-filtered-tickets` is an example identifier, not a universal command argument. |
+| Persona | An advisory perspective used to challenge a decision or find gaps. It isn't evidence of a real user's opinion or approval. |
+| Source Map | A derived index of repository files and relationships. Check its coverage and the underlying source before relying on a finding. |
+| Blueprint | Reviewed organisational guidance packaged for adoption by a project. It isn't required for every project. |
+| Gate | A check that the required evidence and approvals exist before work progresses. A failed gate calls for a correction or decision, not a manual status edit. |
+| Digest | A content fingerprint. A changed digest means the content differs; it doesn't tell you whether the change is good. |
+| Receipt | A saved record of an operation, such as selecting a particular pack version. It proves what was recorded, not that a person accepted every resulting change. |
+| Pack installation, selection and application | Installation makes a pack available. Selection records which approved pack the project uses. Application prepares its relevant guidance for particular work. These aren't interchangeable. |
+
+## Where to make a change
+
+Change requirements and decisions through their reviewed workflows. Rebuild an index when it is stale. Don't edit a derived database to manufacture an approval or change canonical project knowledge.
+
+The [dashboard and delivery state guide](../operations/dashboard-and-delivery-state.md) explains inspection and queued work. [Human approval and assurance](../human-approval-and-assurance-guide.md) explains who can accept which outcomes.

package/Docs/explanation/delivery-workflow.md

@@ -0,0 +1,48 @@
+# How delivery moves through fourteen stages
+
+Ask EWAI to work through a feature with you. The **ewai-deliver** skill coordinates specialist skills and follows the saved project state. The runtime checks whether the required evidence and approvals exist; people remain responsible for requirements, trade-offs, Build approval and acceptance.
+
+The CLI command `delivery continue` tells you what can happen next. It doesn't execute an entire stage. The host uses that result to continue the conversation and work.
+
+## One feature through the workflow
+
+This fictional example is a CSV export of a filtered support-ticket list. It illustrates the stages; it isn't evidence that any implementation or review has happened.
+
+| Stage | What it means for this feature |
+| --- | --- |
+| 1. Ideate — conditional | Establish who needs an export and what they'll do with it, if the initial idea needs shaping. |
+| 2. Intent | Agree columns, filters, permissions, excluded data and acceptance criteria. A draft can begin; the intent must be ready before this stage finishes. |
+| 3. Reconcile — conditional | Check existing filtering and permissions so the export doesn't invent different rules. |
+| 4. Plan | Agree implementation slices, interfaces, dependencies, test approach and stop conditions. |
+| 5. Pattern Validation | Check the proposal against the application's existing patterns and accepted standards. |
+| 6. Test Plan | Specify evidence for correct rows, denied access, empty data and applicable CSV safety cases. |
+| 7. External Plan Validation — provider-gated | Have an eligible, configured independent reviewer challenge the plan. |
+| 8. External Test Validation — provider-gated | Have an independent reviewer challenge the proposed tests. |
+| 9. Build — explicit approval | Implement the approved export slices and preserve unrelated work. |
+| 10. Standards Sweep | Check the completed change against the project's accepted standards. This is required even without an external reviewer. |
+| 11. Test Execute | Run the planned checks and record their actual results. Preparing a test isn't passing it. |
+| 12. External Code Validation — provider-gated | Obtain independent implementation review where a configured provider is available. |
+| 13. Delivery | Prepare the handoff, limitations, release evidence and a walkthrough a person can perform. |
+| 14. Retro — after Manual QA | Capture learning after human acceptance and route reviewed improvements into reusable knowledge. |
+
+Ideate and Reconcile depend on the work. External-review stages are recorded as `not-supported` when no eligible independent provider is configured; that isn't a pass. The active orchestrator isn't its own independent reviewer.
+
+## Decisions around the numbered stages
+
+**UI Design**, after Reconcile when interface work is in scope, lets you explore and select an interaction before Build. Prototype selection isn't acceptance of the implementation.
+
+**Build approval**, before stage 9, authorises a defined scope. Agreeing the idea or selecting a prototype doesn't grant it.
+
+**Fit Check**, before Build when resuming a shelved plan, tests whether the earlier plan still fits current requirements, code and constraints. If it doesn't, revise the affected work.
+
+**Manual QA**, after Delivery and before Retro, records a named person's observations and acceptance. Automated checks don't substitute for this.
+
+**Release** requires its own appropriate authority and evidence. A successful command or completed delivery record doesn't grant deployment permission.
+
+## Pause, resume or change direction
+
+EWAI saves the intent and phase evidence in SPECS. Ask it to show what's complete, what's blocked and what decision it needs. Use the guarded resume route for shelved work; don't change a status file or database row to skip a check.
+
+If the outcome changes materially, revisit the intent and plan. A new Build approval may be needed. If only an evidence reference needs a correction, follow the [amendment guide](../completed-phase-evidence-amendments.md), which explains the narrow permitted operations.
+
+Try the [first-delivery tutorial](../tutorials/first-delivery.md). For exact commands and evidence contracts, use the [developer delivery guide](../developer-delivery-guide.md).

package/Docs/governance/governance-team-guide.md

@@ -0,0 +1,139 @@
+# Governance team guide
+
+Use this guide to govern EWAI-enabled work through explicit policy, evidence, exceptions, and human accountability without becoming the delivery bottleneck for every project.
+
+## Govern decisions, not AI activity volume
+
+Focus on:
+
+- what outcomes and risks the organisation is accepting;
+- which data and systems AI may access;
+- how reusable standards and personas are owned;
+- which delivery evidence is mandatory at each risk level;
+- who can approve Build, exceptions, Manual QA, and production release;
+- how incidents, changes, and learning alter the baseline.
+
+Token counts, prompt counts, or the number of generated artefacts are weak governance measures on their own.
+
+## Define a minimum control model
+
+At minimum, specify:
+
+| Control | Governance question |
+| --- | --- |
+| Purpose and ownership | Is a named person accountable for the outcome? |
+| Data boundary | Which classifications and sources may each AI host process? |
+| Project truth | Are approved decisions and evidence retained under canonical SPECS? |
+| Reusable content | Who owns Blueprints, standards, and organisation personas? |
+| Validation | Which deterministic, independent, and human checks apply? |
+| Exceptions | Who may approve, what controls compensate, and when does it expire? |
+| Acceptance | Who performs Manual QA and what evidence is required? |
+| Operations | How are changes observed, recovered, and supported? |
+| Learning | How do incidents and retrospectives update the control model? |
+
+## Use risk tiers proportionately
+
+Recommended practice is to scale evidence according to data sensitivity, external exposure, decision impact, reversibility, operational criticality, novelty, and regulatory context.
+
+For each tier, define:
+
+- mandatory standards and Blueprint modules;
+- required human roles;
+- independent-review expectations;
+- security, privacy, accessibility, and resilience evidence;
+- Manual QA depth;
+- release and rollback authority;
+- retention and audit periods.
+
+Avoid treating one heavy process as appropriate for both a small reversible internal tool and a sensitive public service.
+
+## Review the evidence chain
+
+For a delivery, trace:
+
+```text
+human purpose and evidence
+→ approved intent and constraints
+→ implementation and test plan
+→ explicit Build approval
+→ task evidence and standards sweep
+→ configured independent review
+→ Delivery and Manual QA evidence
+→ acceptance, operation, and learning
+```
+
+Every arrow should have a durable record or an explicit not-applicable/not-supported reason.
+
+## Distinguish validation types
+
+- **Deterministic checks:** schemas, tests, static analysis, hashes, and gate contracts.
+- **Independent review:** a configured provider or reviewer other than the producing orchestrator.
+- **Human judgement:** applicability, trade-offs, exceptions, user acceptance, and production readiness.
+
+One cannot silently substitute for another. In particular, unavailable independent validation is not a pass, and a persona is not an approver.
+
+## Govern Blueprints and personas
+
+For shared Blueprints, require publisher ownership, versioning, compatibility, immutable releases, provenance, release notes, and deprecation. Projects must review before adoption; upstream changes must not overwrite local truth automatically.
+
+For personas, require ownership, evidence grounding, visible provenance, advisory boundaries, review triggers, and safe retirement. Managed premium definitions remain within their entitled library and must not be copied into public governance packs.
+
+## Review exceptions
+
+An exception record should identify:
+
+- rule and exact scope;
+- reason and alternatives considered;
+- risk and affected people;
+- compensating controls;
+- approver and owner;
+- start, expiry, and review dates;
+- closure evidence.
+
+Look for recurring exceptions. They may indicate an unrealistic standard, missing platform capability, inadequate training, or a genuine risk concentration.
+
+## Audit without relying on the dashboard alone
+
+The dashboard is a rebuildable projection. Audit durable records:
+
+- intent Markdown and adjacent structured state;
+- delivery-state and hashed gate ledgers;
+- approvals and evidence paths;
+- task reports and command evidence;
+- standards and external validation reports;
+- Blueprint receipts and pins;
+- Manual QA evidence;
+- retrospectives, risks, incidents, and exceptions.
+
+Use the operational projection to navigate, then verify the canonical files.
+
+## Useful governance measures
+
+- material decisions with identified evidence and owner;
+- unresolved high-risk questions at Build approval;
+- exception volume, age, and recurrence;
+- validation unavailability by risk tier;
+- failures found in automated review, Manual QA, and production;
+- time to detect and recover from incidents;
+- Blueprint and persona review currency;
+- learning adopted into standards or operating practice.
+
+## Governance review checklist
+
+- [ ] Outcome, users, and accountable owner are clear.
+- [ ] Data and AI-processing boundaries are explicit.
+- [ ] Applicable standards and risk tier are recorded.
+- [ ] Personas are visible, attributable, and advisory.
+- [ ] Build scope has named approval.
+- [ ] Tests, standards, independent review, and human QA are distinct.
+- [ ] Exceptions and unavailable checks are visible.
+- [ ] Operational ownership and recovery are adequate.
+- [ ] Durable evidence supports the dashboard view.
+- [ ] Learning has an owner and destination.
+
+## Related guides
+
+- [Human approval and assurance](../human-approval-and-assurance-guide.md)
+- [Organisation rollout](../organisation-rollout-guide.md)
+- [Project standards authoring](../standards/project-standards-authoring.md)
+- [Persona governance](../personas/persona-governance.md)