@thebackstoryis/engineering-with-ai 0.2.9

package/Docs/repository-source-map-guide.md

@@ -0,0 +1,381 @@
+# Repository Source Map guide
+
+The Repository Source Map is EWAI's project-local inventory and analysis layer. It records every regular file found in the configured repositories, gives each file an explicit analysis outcome and depth, and uses deeper Tree-sitter evidence where a supported grammar is registered.
+
+The Source Map evolves the existing Repository Index; it does not replace it. Search, dependency graphs, standards coverage, Blast Radius, and the dashboard all consume the same rebuildable SQLite projection.
+
+> The Source Map is advisory repository evidence. A fresh map is not complete understanding, security certification, product acceptance, or release approval. Dynamic behaviour, external systems, generated assets, runtime configuration, and undocumented human processes can remain outside its evidence.
+
+
+<!-- editorial: contents -->
+## On this page
+
+- [Start with a question about a change](#start-with-a-question-about-a-change)
+- [What gets mapped](#what-gets-mapped)
+- [Understand outcomes and depths](#understand-outcomes-and-depths)
+- [Core analysers and file coverage](#core-analysers-and-file-coverage)
+- [Refresh and inspect the Source Map](#refresh-and-inspect-the-source-map)
+- [Add a project profile](#add-a-project-profile)
+- [Add profiles through packs](#add-profiles-through-packs)
+- [Configure repository topologies](#configure-repository-topologies)
+- [Profile contract and safety limits](#profile-contract-and-safety-limits)
+- [Personas in discovery and impact work](#personas-in-discovery-and-impact-work)
+- [Relationship to Blast Radius](#relationship-to-blast-radius)
+- [Power Platform and Salesforce exports](#power-platform-and-salesforce-exports)
+- [Troubleshooting](#troubleshooting)
+- [Operational checklist](#operational-checklist)
+- [Related guides](#related-guides)
+- [Current contract sources](#current-contract-sources)
+
+## Start with a question about a change
+
+For example: “Where does the application check export permissions?” Ask EWAI to inspect the relevant source and its callers. For direct inspection:
+
+```bash
+ewai index freshness --project . --json
+ewai index refresh --project . --json
+ewai index search "export" --project . --json
+```
+
+Choose a returned file or symbol, inspect its graph through the [commands below](#refresh-and-inspect-the-source-map), then read the source. Check coverage before claiming you've found every caller. No search result may mean unsupported analysis, different naming or genuinely absent code.
+
+## What gets mapped
+
+EWAI walks every configured repository and inventories each regular file except:
+
+- symbolic links;
+- unreadable directories;
+- the configured canonical `SPECS` tree, which is indexed separately by the Mind Palace and delivery projections;
+- generated or dependency directories that EWAI excludes by name, including `.git`, `.nuxt`, `.output`, `.ewai-pipeline`, `.phpunit.cache`, `.vite`, `build`, `coverage`, `dist`, `node_modules`, `storage`, and `vendor`.
+
+An uncommon file type is not silently discarded. The core fallback profile records it as inventory-only evidence. Technology, stack, organisation, and project profiles can opt matching files into a registered deeper analyser.
+
+Keeping canonical SPECS out of the Source Map prevents a normal evidence write from making implementation evidence stale. It does not hide project knowledge: the Mind Palace, intent, standards, and delivery projections remain its authoritative readers.
+
+## Understand outcomes and depths
+
+Every file has one outcome:
+
+| Outcome | Meaning |
+| --- | --- |
+| `analysed` | The selected registered analyser completed. |
+| `inventory_only` | EWAI recorded bounded file metadata but did not interpret content. |
+| `skipped_sensitive` | The filename is credential-shaped, so EWAI did not open it. |
+| `skipped_oversized` | The file exceeded the selected profile's size ceiling, so EWAI did not open it. |
+| `analysis_failed` | EWAI retained the file in coverage but its bounded analyser could not complete. |
+
+Analysis depth is separate:
+
+| Depth | Current meaning |
+| --- | --- |
+| `deep` | A registered deep analyser extracts syntax or declared metadata symbols and relationships. Tree-sitter handles supported source code; reviewed platform analyzers handle finite metadata catalogues. |
+| `shallow` | EWAI records structural keys or content-shape summary data, not scalar values. |
+| `inventory` | EWAI records file classification and bounded metadata only. |
+
+Deep means deeper structural evidence, not semantic completeness. Shallow structured analysis stores key paths rather than configuration values. Sensitive and oversized files receive metadata-derived fingerprints; EWAI does not hash their content.
+
+## Core analysers and file coverage
+
+Profiles may select only these registered analysers:
+
+| Analyser | Intended evidence |
+| --- | --- |
+| `tree-sitter` | Syntax-aware PHP, JavaScript, JSX, TypeScript, TSX, and Vue analysis. |
+| `power-platform-metadata` | Allowlisted solution, component, canvas and declared dependency facts from supported already-extracted Power Platform source. |
+| `salesforce-metadata` | Allowlisted package, component, object, field, flow and permission facts from supported Salesforce source. |
+| `structured-keys` | JSON/JSONC, YAML, TOML, XML/SVG, INI/properties, and safe environment-template key shapes. |
+| `text-summary` | Documentation and common source/configuration text shapes such as line counts. |
+| `inventory-only` | File presence, classification, size, profile, and outcome. |
+
+Core profiles cover common source, structured, documentation, build, query, shell, styling, and configuration file extensions. Unknown and binary files remain visible through inventory-only profiles. Packs should add a profile when the file's role or framework context matters, not merely to make the count look deeper.
+
+## Refresh and inspect the Source Map
+
+Refresh before substantive repository, Blast Radius, or standards claims:
+
+```bash
+ewai index freshness --project . --json
+ewai index refresh --project . --json
+ewai index coverage --project . --json
+```
+
+Inspect the effective profile catalogue:
+
+```bash
+ewai index profiles --project . --json
+ewai index profiles --source organisation --limit 50 --project . --json
+ewai index profiles --analyser tree-sitter --project . --json
+```
+
+Inspect safe file projections:
+
+```bash
+ewai index files --outcome analysis_failed --project . --json
+ewai index files --outcome skipped_sensitive --project . --json
+ewai index files --classification framework-routing --project . --json
+ewai index files --profile project:api-contracts --project . --json
+ewai index files --repository api --query contracts --limit 50 --project . --json
+```
+
+The profile projection includes a `matchCount`; zero means the profile was active in the completed catalogue but selected no files. The file projection returns repository name, repository-relative path, parser state, counts, classification, profile, analyser, depth, and outcome. It does not expose repository roots, file content, stored analysis metadata, or fingerprints. Filters and result limits are bounded consistently for CLI and MCP callers.
+
+The equivalent read-only MCP tools are:
+
+- `ewai_source_map_coverage`;
+- `ewai_source_map_profiles`;
+- `ewai_source_map_files`.
+
+The dashboard's **Impact** tab shows coverage, effective profile provenance, a bounded sample needing attention, and the personas actively engaged for the selected work item.
+
+## Add a project profile
+
+Add project-specific rules under `source_map.profiles` in `SPECS/pipeline.yaml`:
+
+```yaml
+source_map:
+  profiles:
+    - id: api-contracts
+      patterns:
+        - contracts/**/*.json
+      analyser: structured-keys
+      classification: api-contract
+      repositories:
+        - backend
+      priority: 100
+      max_bytes: 500000
+```
+
+`repositories` may contain a configured repository name or role. Omit it when the profile should apply to every configured repository.
+
+After changing profiles, refresh the map. The effective profile catalogue has a deterministic digest; changing a profile, pack version, or active pack makes the previous map stale.
+
+## Add profiles through packs
+
+Technology, stack, and Organisation Blueprint Packs use the same declarative `source_map` shape:
+
+```yaml
+schema: ewai.pack/v1
+id: org.northstar.engineering
+name: Northstar engineering
+description: Reviewed organisation repository conventions.
+version: 1.2.0
+type: organisation
+requires: []
+blueprint:
+  publisher:
+    id: northstar
+    name: Northstar Digital
+  compatibility:
+    ewai: 0.x
+  modules:
+    - id: repository-conventions
+      name: Repository conventions
+      description: Classify organisation policy files for repository analysis.
+      required: true
+source_map:
+  profiles:
+    - id: decision-policies
+      patterns:
+        - policies/**/*.yaml
+      analyser: structured-keys
+      classification: organisation-policy
+      priority: 90
+```
+
+The example is a complete organisation manifest. `source_map` belongs to the pack, not an individual module. Profiles take effect when the pack is selected in the project configuration; installing a folder alone doesn't activate it.
+
+The Blueprint parser validates profile fields and types, registered analysers, safe patterns and size limits. It rejects executable fields and duplicate profile IDs. Changing a profile changes the pack digest and the effective profile catalogue, so refresh the index after an approved change.
+
+Non-core profile IDs are namespaced when resolved:
+
+- project profile `api-contracts` becomes `project:api-contracts`;
+- pack profile `decision-policies` becomes `org.northstar.engineering:decision-policies`.
+
+The effective catalogue includes configured packs and their dependencies. Profile selection is deterministic:
+
+1. project;
+2. organisation;
+3. stack;
+4. technology;
+5. core.
+
+Within the same source level, higher `priority` wins, then profile ID provides a stable tie-break. Core safety treatment for sensitive filenames cannot be overridden.
+
+## Configure repository topologies
+
+Source Map profiles use the same `repositories` topology as indexing, starter materialisation, and Blast Radius.
+
+### Single repository
+
+```yaml
+repositories:
+  - name: application
+    path: .
+    role: application
+source_map:
+  profiles:
+    - id: application-contracts
+      patterns: [contracts/**/*.json]
+      analyser: structured-keys
+      classification: api-contract
+      repositories: [application]
+```
+
+### Monorepo
+
+```yaml
+repositories:
+  - name: product
+    path: .
+    role: workspace
+source_map:
+  profiles:
+    - id: frontend-pages
+      patterns: [apps/web/pages/**/*.vue]
+      analyser: tree-sitter
+      classification: user-interface
+      repositories: [product]
+    - id: backend-routes
+      patterns: [apps/api/routes/**/*.php]
+      analyser: tree-sitter
+      classification: framework-routing
+      repositories: [product]
+```
+
+Patterns are relative to the configured repository root. In a monorepo, include the application subfolder in the pattern.
+
+### Folder containing repository subfolders
+
+```yaml
+repositories:
+  - name: web-app
+    path: clients/web
+    role: frontend
+  - name: api-app
+    path: services/api
+    role: backend
+source_map:
+  profiles:
+    - id: frontend-pages
+      patterns: [pages/**/*.vue, app/pages/**/*.vue]
+      analyser: tree-sitter
+      classification: user-interface
+      repositories: [frontend]
+    - id: backend-routes
+      patterns: [routes/**/*.php]
+      analyser: tree-sitter
+      classification: framework-routing
+      repositories: [backend]
+```
+
+Here each pattern is relative to its repository subfolder. Repository selectors may use `web-app`/`api-app` names or `frontend`/`backend` roles.
+
+## Profile contract and safety limits
+
+A profile supports only:
+
+- `id`;
+- one or more safe relative `patterns` using `*`, `**`, and `?`;
+- one registered `analyser`;
+- a lower-kebab-case `classification`;
+- optional integer `priority` from `-10000` to `10000`;
+- optional repository name/role selectors;
+- optional `max_bytes` from 1 to 900,000.
+
+Absolute, negated, traversal, backslash, brace, bracket, and parenthesised patterns are rejected. Profiles cannot contain shell commands, module paths, executable hooks, credentials, or network configuration. The 900,000-byte ceiling is global; a profile may lower it but cannot raise it.
+
+Use profiles to select an existing safe analysis behaviour. If a new analyser is needed, it requires a reviewed EWAI implementation change with its own tests and safety model.
+
+## Personas in discovery and impact work
+
+Personas do not change which bytes are indexed. They challenge how the resulting evidence is interpreted.
+
+Attach relevant lenses to the intent during Discovery, including:
+
+- core personas;
+- installed premium personas;
+- reusable personal personas;
+- project-local personas, including approved Blueprint-derived personas.
+
+The dashboard identifies every active persona by name, tier, role, depth, and engagement reason. An attached premium or local reference remains visible as unavailable if its library content cannot currently be resolved. This avoids silently dropping a perspective.
+
+Persona conclusions remain advisory. Real stakeholders and accountable specialists provide acceptance, assurance, and approval.
+
+## Relationship to Blast Radius
+
+The Source Map is the evidence base. Blast Radius resolves supplied paths or symbols and traverses supported relationships from that evidence.
+
+Blast Radius reports partial coverage when the map includes inventory-only, shallow, sensitive, oversized, failed, or explicitly partial platform evidence, when a target is unresolved or ambiguous, or when traversal reaches its bound. A small graph under partial coverage is uncertainty, not proof of low impact.
+
+See [Blast Radius and Impact Routing](blast-radius-and-impact-routing-guide.md) for the review-routing workflow.
+
+## Power Platform and Salesforce exports
+
+The installed `ewai.technology.power-platform` and
+`ewai.technology.salesforce` packs add finite semantic profiles for supported
+already-extracted source layouts. Their symbols and relationships use the same
+Source Map and graph as Tree-sitter evidence. Unsupported families remain
+generic, inventory, failed or explicitly partial evidence rather than being
+silently discarded.
+
+EWAI does not extract ZIP or `.msapp` archives, run vendor CLIs, connect to a
+tenant or org, import, deploy, or retain arbitrary configuration values. See the
+[Power Platform and Salesforce export analysis guide](platform-export-analysis-guide.md)
+for supported layouts, topology examples, redaction rules and troubleshooting.
+
+## Troubleshooting
+
+### The map is stale after no source-code change
+
+Profile catalogue changes also invalidate freshness. Inspect `ewai index freshness`; if the reason is `profile-catalogue-changed`, review the current packs and profiles, then refresh.
+
+### A file is inventory-only
+
+Inspect its selected profile. The outcome is expected for unknown or binary content. Add a safe profile only if a registered analyser matches the format and the classification provides useful project context.
+
+### A structured file failed
+
+Filter `--outcome analysis_failed`. Confirm the document is valid for its extension. Failure remains visible in Source Map coverage and limits downstream claims.
+
+### A sensitive file was skipped
+
+That is the intended safety behaviour. Do not rename or copy credentials to force analysis. Use a value-free `.env.example`, `.env.sample`, or `.env.template` when configuration-key evidence is genuinely needed.
+
+### The wrong profile won
+
+Inspect `ewai index profiles`, the repository name/role selector, source provenance, and priority. Prefer a narrower pattern to a high global priority. Refresh after correction.
+
+## Operational checklist
+
+- [ ] Every repository root is explicit and correct.
+- [ ] Source Map profiles are declarative and use registered analysers only.
+- [ ] Organisation and project classifications have named owners.
+- [ ] Repository selectors match configured names or roles.
+- [ ] Sensitive, oversized, inventory-only, and failed counts were reviewed.
+- [ ] Relevant premium and project-local personas are visibly engaged.
+- [ ] Partial coverage is carried into Blast Radius, planning, and QA decisions.
+- [ ] Human reviewers understand that the Source Map is evidence, not approval.
+
+## Related guides
+
+- [Existing-project onboarding](existing-project-onboarding-guide.md)
+- [Blast Radius and Impact Routing](blast-radius-and-impact-routing-guide.md)
+- [Designing Organisation Blueprint Packs](designing-organisation-blueprint-packs.md)
+- [Governed Starter-Project Materialisation](governed-starter-project-materialisation-guide.md)
+- [Working with personas](working-with-personas.md)
+- [CLI and configuration reference](reference/cli-and-configuration.md)
+- [Troubleshooting and recovery](operations/troubleshooting-and-recovery.md)
+
+## Current contract sources
+
+- `src/repository-source-map.mjs`
+- `src/platform-metadata-analysis.mjs`
+- `src/power-platform-source-map.mjs`
+- `src/salesforce-source-map.mjs`
+- `src/runtime/repository-index.mjs`
+- `src/runtime/impact-analysis.mjs`
+- `config/project.schema.json`
+- `config/pack.schema.json`
+- `tests/repository-index.test.mjs`
+- `tests/repository-index-profiles.test.mjs`
+- `tests/repository-source-map-cli.test.mjs`

package/Docs/reproducible-archaeology-and-discovery-depth.md

@@ -0,0 +1,292 @@
+# Reproducible Archaeology and Discovery Depth
+
+EWAI can make the depth of Archaeology and Discovery explicit, proportionate, and repeatable. It does this without treating a long backlog as evidence of depth and without depending on identical prose from different model sessions.
+
+The capability is local and optional. It does not send feedback to a hosted service, execute production code, enforce runtime policy, install premium personas, or grant Build, Manual QA, deployment, or release approval.
+
+
+<!-- editorial: contents -->
+## On this page
+
+- [Decide how far to investigate](#decide-how-far-to-investigate)
+- [What it produces](#what-it-produces)
+- [How consistency is achieved](#how-consistency-is-achieved)
+- [The seven dimensions](#the-seven-dimensions)
+- [Before you begin](#before-you-begin)
+- [Use it in Guided Setup](#use-it-in-guided-setup)
+- [Use it from the CLI](#use-it-from-the-cli)
+- [Use it from an agent or integration](#use-it-from-an-agent-or-integration)
+- [How personas work](#how-personas-work)
+- [Stable gaps and grouping](#stable-gaps-and-grouping)
+- [Understanding comparisons](#understanding-comparisons)
+- [Protect engineering performance while reducing tokens](#protect-engineering-performance-while-reducing-tokens)
+- [Failure and recovery](#failure-and-recovery)
+- [Boundaries](#boundaries)
+- [Related guides](#related-guides)
+
+## Decide how far to investigate
+
+Start with the intended change and its consequences. A small interface adjustment and a migration of sensitive data need different investigation. EWAI recommends depth independently for architecture, data, security, product, delivery, governance and operations; you review those choices rather than accepting a single overall score.
+
+Preparation gives you recommendations, supporting evidence, gaps and a review route. Resolve material questions with their owners, or retain them explicitly. A lower depth needs a reason; a deeper recommendation doesn't claim the investigation has already been done.
+
+## What it produces
+
+A prepared workspace contains:
+
+- independent recommendations for architecture, data, security, product, delivery, governance, and operations;
+- the evidence drivers and coverage behind each recommendation;
+- explicit inventory-only, sensitive, oversized, failed, and excluded surfaces;
+- deterministic stable gap identifiers;
+- adaptive questions for missing or contradictory owner evidence;
+- the core, project, personal, and optional installed premium personas active for each concern;
+- a proposed grouping strategy that remains separate from gap identity.
+
+A named review records:
+
+- the selected depth for every dimension;
+- rationale when the owner reduces a recommendation;
+- an explicit group and disposition for every gap;
+- the exact preparation digest, Source Map run, evidence, provider capability, and persona set reviewed;
+- an immutable run ID and content digest under `SPECS/3.Evidence/discovery-depth/runs/`.
+
+A comparison explains changes in causal order: inputs, evidence, personas, selected depth, coverage, stable gaps, and grouping.
+
+## How consistency is achieved
+
+EWAI does not ask a model to reproduce the same narrative. It makes the inputs,
+decisions, and material findings reviewable as structured evidence instead.
+
+```mermaid
+flowchart LR
+    source["Fresh Source Map"] --> ledger["Bounded evidence ledger"]
+    owner["Owner declarations"] --> ledger
+    ledger --> depth["Seven-dimension depth calculation"]
+    depth --> personas["Concern-specific persona ensemble"]
+    personas --> gaps["Stable gap identities"]
+    gaps --> review["Named human review"]
+    review --> run["Immutable reviewed run"]
+    run --> compare["Causal comparison"]
+```
+
+| Control | Contribution to consistency |
+| --- | --- |
+| Fresh Source Map | Binds repository observations to one known analysis run and keeps failed, excluded, sensitive, oversized, and inventory-only surfaces visible. |
+| Bounded owner evidence | Records authority, answer codes, reason codes, and digests without copying free-text source material into the preparation. |
+| Seven independent dimensions | Prevents repository size or backlog length from acting as a crude proxy for depth. |
+| Explicit persona ensemble | Records which core, project, personal, or installed premium perspectives influenced each concern and why. |
+| Stable gap identity | Derives each ID from the dimension, condition, state codes, and evidence references rather than generated wording. |
+| Named review | Requires a human to select depth, justify reductions, and assign every gap without transferring approval authority to a persona or model. |
+| Fingerprinted run | Binds the reviewed result to its inputs, evidence, personas, depth, coverage, gaps, and grouping. |
+| Causal comparison | Separates explained input, evidence, persona, depth, coverage, gap, and grouping changes from unexplained variance. |
+
+Two runs can therefore use different sentences and still be reproducible when
+their material evidence, depth, and stable gaps agree. Conversely, matching prose
+does not make two runs reproducible when one omitted a failed analysis surface or
+used different owner evidence without recording the cause.
+
+See the [worked example](examples/reproducible-archaeology-depth-example.md) for
+an end-to-end illustration and use the
+[operator and Manual QA checklist](quality/reproducible-archaeology-depth-review-checklist.md)
+when assessing a real project.
+
+## The seven dimensions
+
+| Dimension | Typical evidence and questions |
+|---|---|
+| Architecture | Repository topology, component boundaries, dependencies, integrations, and conflicting implementation patterns |
+| Data | Data models, classification, retention, movement, residency, ownership, and sensitive-file exclusions |
+| Security | Trust boundaries, identities, exposure, authorization, threats, and owner-confirmed security constraints |
+| Product | Intended users, outcomes, journeys, exceptions, acceptance, and differences between live behaviour and owner intent |
+| Delivery | Test evidence, release route, standards, quality gates, technical debt, and retained Source Map analysis failures |
+| Governance | Applicable policy, accountable decisions, assurance ownership, exceptions, and review obligations |
+| Operations | Hosting, environments, observability, recovery, continuity, support, and named operational ownership |
+
+Each dimension is selected independently as `bounded`, `standard`, or `deep`. A large repository may need deep architecture analysis but bounded product discovery for a narrowly scoped internal utility. A small service handling sensitive data may need deep data and security analysis even when its architecture is simple.
+
+## Before you begin
+
+1. Initialise EWAI and confirm `.ewai-pipeline/project.json` points to the intended project and SPECS root.
+2. Complete the human project briefing. Repository code can establish observable behaviour, not why the project should exist.
+3. Register and review relevant imported evidence where applicable.
+4. Refresh the Repository Source Map:
+
+```bash
+ewai index refresh --project /path/to/project --json
+```
+
+5. Confirm that failures, inventory-only files, sensitive files, oversized files, and exclusions are visible. Do not silently remove them to improve the coverage status.
+
+## Use it in Guided Setup
+
+Open the local dashboard and choose **Guided Setup**. The **Evidence depth** panel appears inside the existing Discovery workspace; it is not a separate product or primary navigation area.
+
+1. Select **Prepare evidence depth**.
+2. Review the seven-row ledger. Each row shows coverage, recommendation, owner selection, and the personas active for that concern.
+3. Review the stable gaps separately from the adaptive questions.
+4. Enter the named reviewer.
+5. Select a depth for every dimension. Add rationale if reducing a recommendation.
+6. Give every gap a group and disposition.
+7. Select **Record named review**.
+8. When at least two runs exist, select the runs and compare them.
+
+Answered Guided Setup fields are projected as `declared` owner evidence for browser preparation. EWAI hashes their normalized values and records bounded question and revision codes; the answer text itself is not copied into the evidence-depth preparation or reviewed run. Re-prepare after materially changing Discovery answers so the named review binds to the current declarations.
+
+The current UI uses EWAI's default fallback visual system unless the project applies an approved Design System Pack. The panel labels that condition; the fallback is not organisation-approved.
+
+## Use it from the CLI
+
+Inspect the current status:
+
+```bash
+ewai archaeology depth-status --project /path/to/project --json
+```
+
+Prepare from repository evidence only:
+
+```bash
+ewai archaeology depth-prepare \
+  --focus "security recovery and product outcomes" \
+  --project /path/to/project \
+  --json
+```
+
+To add owner evidence, create a project-relative JSON file. The example below is illustrative: `sha256:security-boundary-review` is an accepted symbolic evidence identifier, not a calculated SHA-256 checksum and not proof that a file was verified. Use identifiers tied to the evidence actually reviewed by your owner.
+
+```json
+{
+  "focus": "security recovery and product outcomes",
+  "ownerEvidence": [
+    {
+      "id": "owner:security-boundary",
+      "dimension": "security",
+      "authority": "confirmed",
+      "evidenceDigest": "sha256:security-boundary-review",
+      "answerCode": "internal-users-only",
+      "reasonCode": "named-owner-review",
+      "contradiction": "none"
+    }
+  ]
+}
+```
+
+Then run:
+
+```bash
+ewai archaeology depth-prepare \
+  --input evidence-depth-input.json \
+  --project /path/to/project \
+  --json
+```
+
+Owner evidence uses bounded codes and digests. Do not place free-text answers, source bodies, secrets, absolute paths, or managed persona content in this file.
+
+Create a review JSON from the returned preparation. It must name a reviewer, bind to the exact preparation digest, cover all seven dimensions exactly once, and assign every gap exactly once. Record it with:
+
+```bash
+ewai archaeology depth-record \
+  --input evidence-depth-review.json \
+  --project /path/to/project \
+  --json
+```
+
+Compare two stored runs:
+
+```bash
+ewai archaeology depth-compare LEFT_RUN_ID RIGHT_RUN_ID \
+  --project /path/to/project \
+  --json
+```
+
+Comparison reads the exact stored runs. It does not rescan the repository.
+
+## Use it from an agent or integration
+
+The MCP server exposes:
+
+- `ewai_evidence_depth_status`
+- `ewai_evidence_depth_prepare`
+- `ewai_evidence_depth_record`
+- `ewai_evidence_depth_compare`
+
+`status` and `compare` are read-only. `prepare` writes a disposable runtime preparation, while `record` creates immutable project evidence. All tools use the project root bound when the MCP server starts; caller-supplied project roots are not accepted.
+
+Use `$ewai-evidence-depth` for the complete agent workflow and input contract. `$ewai-archaeology` and `$ewai-project-discovery` route into it when an agreed, repeatable investigation boundary is needed.
+
+## How personas work
+
+EWAI chooses a small ensemble for the concern currently being examined:
+
+- **core personas** provide portable Archaeology, curation, engineering, and operational lenses;
+- **project personas** represent local roles and working conventions;
+- **personal personas** can contribute an explicitly installed individual lens;
+- **premium personas** add specialist challenge when the managed library is already installed and relevant.
+
+The UI shows the persona name, tier, reason for engagement, and dimension. The ensemble changes as the dimension changes. EWAI does not load the whole catalogue merely because it is available.
+
+The standard model and core/project workflow remain complete without premium personas. This feature never downloads or synchronises premium content automatically. Personas cannot confirm owner evidence, select depth, group gaps, or approve delivery.
+
+## Stable gaps and grouping
+
+A gap identity comes from its dimension, condition, current-state code, intended-state code, and evidence references. That identity remains stable when the same structured gap is found again.
+
+Grouping is a later human decision. The same security gap can be grouped under an assurance intent, a product outcome, or a platform boundary without changing the gap itself. This distinction lets teams compare whether evidence changed or only their work-organisation choice changed.
+
+## Understanding comparisons
+
+| Comparison field | A material change usually means |
+|---|---|
+| Inputs | Project, Source Map, contract, pack, provider capability, or exclusions changed |
+| Evidence | The governed repository or owner evidence set changed |
+| Personas | A different identity or tier was actively engaged |
+| Depth | A recommendation or named owner selection changed |
+| Coverage | Required, supported, excluded, or failed coverage changed |
+| Gaps | The deterministic set or reviewed gap state changed |
+| Grouping | The explicit grouping strategy or assignment changed |
+
+Wording or ordering differences do not change run identity when the structured evidence is the same. A grouping-only change is explainable. A coverage or gap change without a material upstream explanation is reported as unexplained variance and the comparison is not reproducible.
+
+## Protect engineering performance while reducing tokens
+
+This capability uses Source Map counts, profiles, bounded evidence identifiers, fingerprints, and immutable reviewed runs. It does not copy repository bodies into the depth ledger or rerun analysis for comparisons.
+
+When optimising context or token demand, compare a known-good reviewed run with the new route. The optimisation is acceptable only if the same material surfaces, standards, constraints, gaps, failure paths, and test obligations remain discoverable. Faster or cheaper output is not an improvement when engineering coverage falls.
+
+Use [Context management and token efficiency](context-management-and-token-efficiency.md) for context-pack design and benchmark guidance, and [Repository Source Map](repository-source-map-guide.md) for coverage mechanics.
+
+## Failure and recovery
+
+| Status or error | What to do |
+|---|---|
+| `source-map-missing` | Refresh the Source Map |
+| `source-map-stale` | Refresh it and prepare again; do not reuse the stale recommendation |
+| `not-prepared` | Prepare after reviewing the available evidence inputs |
+| Newer preparation or stale digest | Reload status and repeat the named review against the current digest |
+| Reduced depth needs rationale | Record substantive accountable rationale or restore the recommendation |
+| Gap is unassigned | Choose an explicit group and disposition |
+| Unexplained comparison variance | Restore the missing evidence context or retain the run as non-reproducible |
+
+Never recover by silently dropping a failed, excluded, contradictory, or unknown surface.
+
+## Boundaries
+
+- This is investigation evidence, not a quality score.
+- It does not guarantee complete Archaeology or Discovery; the selected boundary and coverage ledger remain accountable.
+- It does not make persona output stakeholder research.
+- It does not certify security, compliance, accessibility, or production readiness.
+- It does not replace the canonical Build, standards, test, Manual QA, deployment, or release gates.
+- Feedback remains local. This feature doesn't upload it to a hosted feedback service.
+
+## Related guides
+
+- [Worked example: reproducible Archaeology and Discovery depth](examples/reproducible-archaeology-depth-example.md)
+- [Operator and Manual QA checklist](quality/reproducible-archaeology-depth-review-checklist.md)
+- [Repository Source Map](repository-source-map-guide.md)
+- [Guided Discovery facilitator guide](guided-discovery-facilitator-guide.md)
+- [Context management and token efficiency](context-management-and-token-efficiency.md)
+
+## If preparation reports too many personas
+
+`Evidence depth: personas exceeds 8 entries` means this release assembled more persona identities across the seven dimensions than its input contract accepts. Preparation hasn't succeeded. This can occur with a larger available catalogue; it isn't proof that your source evidence or licence is invalid.
+
+Keep your project and persona files unchanged and report the error with the release version and a safe description of the operation. Don't delete personas, edit the generated preparation or claim the depth review completed. The selection/validation mismatch needs a harness correction; changing your requirements isn't the remedy.