@yemi33/minions 0.1.2423 → 0.1.2425

package/docs/team-memory.md

@@ -58,7 +58,7 @@ Authority is divided by responsibility:
 
 | Store | Authoritative for | Notes |
 |-------|-------------------|-------|
-| `engine/state.db` tables `memory_records` and `memory_retrieval_runs` | Structured record bodies and metadata used by active retrieval; record lifecycle (`active`, `superseded`, `retracted`, `expired`); retrieval telemetry | `memory_records_fts` is a derived external-content FTS5 index maintained by SQLite triggers. |
+| `engine/state.db` tables `memory_records`, `memory_retrieval_runs`, and `memory_lifecycle_events` | Structured record bodies and metadata used by active retrieval; record lifecycle (`active`, `candidate`, `superseded`, `retracted`, `expired`); bounded retrieval and review-learning lifecycle telemetry | `memory_records_fts` is a derived external-content FTS5 index maintained by SQLite triggers. |
 | `pinned.md` | Operator-authored pinned context | Read directly for every rendered agent prompt. It is not a structured-memory pin. |
 | `notes/inbox/*.md` | Pending human, agent, and engine-authored findings awaiting consolidation | Successful agent tasks write one note to the assigned path; failures do not. |
 | `notes.md` | Operator-readable team digest and legacy team-notes prompt input | Consolidation appends here under a file lock. |
@@ -71,6 +71,23 @@ SQLite is the sole authority for runtime state generally; see
 [design-state-storage.md](design-state-storage.md). The Markdown paths above
 remain intentionally file-backed documents and coordination artifacts.
 
+### Offline review-learning backfill
+
+`minions memory backfill-review-learnings [--dry-run] [--limit <N>] [--project <p>]`
+(module `engine/review-learning-backfill.js`) is a strict, offline recovery
+command that reconstructs durable review-learning lessons from legacy artifacts
+(trusted completion artifacts + their dispatch context, tracked PR records,
+legacy feedback inbox/archive files, and migration-027 quarantined candidates).
+It imports through the exact live stable-key + upsert path
+(`reviewLearning.buildFindingKey` → `memoryStore.upsertReviewLearningLesson`), so
+a `--dry-run` classifies identically to a real run and a second real run imports
+zero duplicates. A record is imported only when project, canonical PR, author, a
+discrete generalized rule, exact current-head resolution evidence, source
+consistency, and clean security provenance already exist — it never asks an LLM
+to infer historical rules. Everything else stays non-recallable with an explicit
+skip reason (see `REASON_BUCKETS`). A real run refuses to run while the engine is
+live (memory-record race); `--dry-run` is read-only and always allowed.
+
 ### Synchronization is directional, not a two-way mirror
 
 The normal ingestion paths often write both layers, but they are not one
@@ -78,6 +95,9 @@ cross-store transaction:
 
 - Migration 017 performed a one-time backfill from existing knowledge files,
   team-note sections, and per-agent sections into SQL.
+- Migration 027 extended those tables in place. It did not rebuild migration 017
+  records; exact engine-generated legacy review-feedback records were retained
+  with `status: candidate` and `metadata.legacyUnverified: true`.
 - Inbox consolidation writes knowledge and per-agent files and then upserts
   corresponding semantic records.
 - `POST /api/knowledge` writes both the knowledge file and a human-trusted SQL
@@ -187,7 +207,7 @@ separate default-off summary pass can fold older sections into a fenced
 concurrent append cannot be overwritten.
 
 The heavier KB sweep is a separate process. `engine.autoConsolidateMemory`
-controls its four-hour automatic cadence; it does not control inbox-to-notes
+defaults on and controls its four-hour automatic cadence; it does not control inbox-to-notes
 consolidation. See [kb-sweep.md](kb-sweep.md) for deduplication, TTL, rewrite,
 and archive behavior.
 
@@ -208,7 +228,7 @@ Supported record values are:
 | Type | `semantic`, `episodic`, `procedural` |
 | Scope | `global`, `project:<key>`, `agent:<key>` |
 | Trust | `human`, `system`, `agent`, `external` |
-| Status | `active`, `superseded`, `retracted`, `expired` |
+| Status | `active`, `candidate`, `superseded`, `retracted`, `expired` |
 
 Built-in file ingestion creates semantic records. Completion capture creates
 episodic records. The schema supports procedural records, but recall excludes
@@ -219,6 +239,110 @@ hash. Re-upserting identical content is idempotent. New content for the same
 source type/reference automatically supersedes the previous active row unless
 the caller supplies an explicit supersession.
 
+### Review-learning lifecycle storage
+
+Migration 027 adds the storage foundation for review-derived procedural memory:
+
+- A stable finding key has the form
+  `<project>|<canonical-pr-id>|<host-namespaced-source-key>`, for example
+  `minions-opg|github:opg-microsoft/minions#42|github:review-comment:991`.
+  Project, PR, and source host must agree; case and area facets are normalized
+  before persistence.
+- An unresolved finding is a project-scoped procedural `memory_records` row with
+  `source_type: review-learning`, system trust, and `status: candidate`.
+  Its body is generated by the engine and contains no reviewer body. Candidates
+  remain queryable for diagnostics via `listReviewLearningCandidates` or the
+  explicit `includeReviewLearning` opt-in, but review-learning records are
+  globally excluded from the generic FTS pack, so they are never recallable
+  through the standard `Relevant Memory` path.
+- A verified `accepted-fixed` or `satisfied-elsewhere` disposition may create an
+  active procedural lesson. Replaying unchanged content returns the same record;
+  changed rule content supersedes every older active row for the stable finding
+  key, leaving at most one active version.
+- `invalid` closes a candidate as `retracted`, `stale` closes it as `expired`,
+  and `deferred` or `out-of-scope-follow-up` keeps it in `candidate` with a
+  bounded state marker. Positive transitions preserve the candidate and point
+  `superseded_by` at the active lesson.
+- Both PR comment pollers retain at most 64 prompt-source records under
+  `humanFeedback.commentSources`. GitHub keys are
+  `github:<issue|review>-comment:<id>`; ADO keys are
+  `ado:thread:<thread-id>:comment:<comment-id>`. Each record stores bounded
+  author/timestamps and a SHA-256 content hash, while the same exact key is
+  included in that comment's untrusted-input fence. Edits preserve the key and
+  replace the hash.
+- Human-feedback fix dispatches snapshot that bounded source list in
+  `meta.commentSources`, including contexts coalesced during cooldown.
+- When `review-learning-capture` is enabled, only a completed Minions
+  `changes-requested` verdict creates an unresolved candidate. Review identity,
+  project, canonical PR, configured author, reviewer, dispatch, source item,
+  and a source hash are persisted; the raw review note remains only in its
+  existing fenced prompt context. Approval and non-blocking completions create
+  no candidate.
+- New review completions no longer create `feedback-<author>-from-...` inbox
+  notes. Residual generated files are backfilled to non-recallable legacy
+  candidates when provenance is sufficient, then archived before LLM, team
+  note, knowledge-base, or personal-memory consolidation.
+
+`memory_retrieval_runs` now also stores `dispatch_id`, `retrieval_kind`,
+`selected_ids`, and a structured `decision_trace`. `memory_lifecycle_events`
+stores a unique deterministic `event_key`, event/memory/finding identity,
+project, agent, normalized area, disposition, work-item/dispatch references,
+compact metadata, and timestamp. Event replay is idempotent. Event pruning
+removes only old event rows and never deletes a memory record.
+
+The boundary in `engine/review-learning.js` redacts secret-shaped values and
+enforces these UTF-8/count limits:
+
+| Value | Limit |
+|-------|-------|
+| Candidate or lesson body | 4,096 bytes |
+| Generalized rules | 8 entries, 1,024 bytes each |
+| Metadata | 4,096 bytes, 32 keys/items per container, depth 3 |
+| Retrieval query | 2,048 bytes |
+| Selected IDs | 32 entries / 4,096 bytes |
+| Decision trace | 64 structured entries / 8,192 bytes |
+| Applicable review-lesson recall | 4 records / 4,096 bytes per dispatch |
+| Lifecycle event key | 64 bytes |
+| PR comment source list / author | 64 entries / 160 bytes |
+| Retained retrieval runs / lifecycle events | 5,000 / 50,000 rows |
+| Candidate expiry / lifecycle-event max age | 180 days / 1 year |
+
+Raw prompt, comment/reviewer-body, transcript, message, stdout/stderr, reasoning,
+and chain-of-thought fields are rejected. Telemetry accepts IDs, hashes, bounded
+evidence references, scores, dispositions, and reason codes instead of narrative
+execution traces.
+
+Rollout counters group by project and normalized area. The denominator is the
+distinct finding keys with a `created` event and a positive disposition; the
+numerator is distinct keys with `repeated-finding`. Aggregates also report the
+distinct `retrieved`, `applied`, and `retracted` finding-key counts. Aggregates
+return `insufficient-sample` below the default minimum of 20 created findings
+rather than claiming a rate improvement.
+
+### Diagnostics and retention (P-1ed2fb5f)
+
+Operator diagnostics endpoints layer on top of the same SQL store, exposing only
+IDs, hashes, reason codes, and bounded traces (never raw prompt/reviewer bodies):
+
+- `GET /api/memory-records/search` accepts optional validated `project`,
+  `author`, `audience`, `sourceType`, and `findingKey` filters. Malformed values
+  return an actionable `400`; a `project` filter narrows scope to that project
+  plus global so results never cross into another project.
+- `GET /api/memory-records/retrieval-decision?dispatchId=…|workItemId=…` returns
+  the latest bounded retrieval decision (why each lesson was selected/excluded)
+  by stable id and reason code. One of the two anchor ids is required.
+- `GET /api/memory-records/lifecycle` returns a bounded (≤200) lifecycle timeline
+  plus per-event-type counters for a finding/memory/project.
+- `GET /api/memory-records/rollout` returns the bounded rollout aggregates above.
+
+Retention is folded into the periodic `engine/cleanup.js` cadence and is
+deliberately decoupled from KB file TTL: unresolved review-learning candidates
+expire (`status: expired`) after 180 days; compact lifecycle events are pruned
+past one year and above the 50,000-row cap; active procedural lessons persist
+until superseded or retracted. Reversible `retract`/`restore` of a review-learning
+record emits a `retracted`/`restored` lifecycle event for the operator timeline.
+
+
 ### Query construction and selection
 
 `engine/memory-retrieval.js` builds a task query from the work-item title,
@@ -246,6 +370,39 @@ Every packed record includes:
 That provenance is visible both in the `Relevant Memory` appendix and the
 dashboard's structured-memory search.
 
+### Reserved deterministic review-lesson recall
+
+Review-learning records are recalled through a dedicated path that never depends
+on an FTS hit (`engine/memory-retrieval.js#retrieveApplicableReviewLearnings`),
+and they are **globally excluded** from the generic FTS pack
+(`searchMemoryRecords` drops `source_type='review-learning'` unless a caller
+passes `includeReviewLearning`, which only the operator dashboard search does).
+
+When `features.review-learning-recall` is on and a dispatch has a resolved
+project context, the path:
+
+1. lists active project-scoped lessons straight from the review-learning index
+   (`listActiveReviewLearnings`), so a lexically unrelated later task still
+   recalls a lesson touching the same file or symbol;
+2. applies the audience gate — `project-team` lessons reach any agent in the
+   project; `author` lessons require the matching author agent — with project
+   scoping preventing any cross-project leak;
+3. derives normalized affected-file, symbol, and tag hints from the same task
+   context (`deriveReviewFacetHints`, mirroring the capture-side normalization);
+4. ranks exact **symbol → file → tag** overlap first, then lexical relevance,
+   confidence, and recency, keeping only applicable lessons; and
+5. injects at most **4 records or 4 KiB** (independent of the generic memory
+   budget) as a separately fenced `## Applicable Prior Review Lessons` section,
+   wrapped with `engine/untrusted-fence.js`.
+
+Each run records bounded telemetry through `recordRetrievalRun` with
+`retrieval_kind='review-learning'`, the dispatch and work-item ids, selected
+record ids, per-record scores, and reason codes (`exact-symbol`, `exact-file`,
+`exact-tag`, `lexical`, `not-applicable`, `record-cap`, `byte-cap`) — never any
+prompt or comment body. With recall off (capture-only), the rendered prompt is
+unchanged with respect to review-learning records, and projectless Command
+Center / unrelated central work receive no section.
+
 ## Prompt assembly and fallback
 
 `engine/playbook.js` renders the requested playbook, adds shared rules, then
@@ -255,7 +412,10 @@ appends memory context in this order:
 2. Either **Relevant Memory** or the legacy pair:
    - **Team Notes** from `notes.md`;
    - **Personal Memory** from `knowledge/agents/<agentId>.md`.
-3. Later non-memory appendices such as propagated project instructions.
+3. **Applicable Prior Review Lessons**, when `review-learning-recall` is on, the
+   dispatch has a project, and at least one applicable lesson exists (bounded and
+   fenced independently of the generic memory budget).
+4. Later non-memory appendices such as propagated project instructions.
 
 Pinned context is independent of retrieval and remains present in every mode.
 
@@ -338,25 +498,123 @@ completion result.
 | Key | Default | Purpose |
 |-----|---------|---------|
 | `features.memoryRetrieval` | `true` | Enables structured retrieval. Feature resolution is environment override, then `config.features`, then registry default. |
+| `features.review-learning-capture` | `false` | Temporary gate for capturing verified review-learning candidates and lessons. |
+| `features.review-learning-recall` | `false` | Temporary independent gate for the dedicated review-learning recall path. |
 | `engine.memoryRetrievalShadowMode` | `false` | Measure retrieval without replacing legacy prompt memory. |
 | `engine.memoryRetrievalTopK` | `8` | Maximum selected records. |
 | `engine.memoryRetrievalMaxBytes` | `8192` | UTF-8 byte budget for selected record blocks. |
 | `engine.memoryRetrievalCandidateLimit` | `50` | FTS5 candidates before reranking. |
 | `engine.memoryEpisodicCapture` | `false` | Store compact completion episodes. |
 | `engine.inboxConsolidateThreshold` | `5` | Eligible inbox files required before consolidation starts. |
-| `engine.autoConsolidateMemory` | `false` | Automatically run the separate KB sweep every four hours. |
+| `engine.autoConsolidateMemory` | `true` | Automatically run the separate KB sweep every four hours. |
 | `engine.agentMemoryMaxEntries` | `300` | Non-summary section window in a personal file. |
 | `engine.agentMemorySummaryEnabled` | `false` | Enable LLM compression of older personal sections. |
 | `engine.agentMemorySummaryThreshold` | `30` | Oldest-section batch size for a summary. |
 | `engine.agentMemorySummaryDays` | `30` | Age trigger for summary eligibility. |
 
-The feature flag is exposed by the generic Dashboard **Settings > Features**
-surface. Settings also exposes shadow mode, episodic capture, retrieval bounds,
-the inbox threshold, and automatic KB sweep. The personal-file window and
-summary keys are configuration-only today.
-
-The environment override for the feature is
-`MINIONS_FEATURE_MEMORYRETRIEVAL=1|0`.
+Feature flags are exposed by the generic Dashboard **Settings > Features**
+surface. The two review-learning flags expire on 2027-01-31 and default off, so
+the migration alone changes no prompt. Settings also exposes shadow mode,
+episodic capture, retrieval bounds, the inbox threshold, and automatic KB sweep.
+The personal-file window and summary keys are configuration-only today.
+
+Environment overrides are `MINIONS_FEATURE_MEMORYRETRIEVAL=1|0`,
+`MINIONS_FEATURE_REVIEW_LEARNING_CAPTURE=1|0`, and
+`MINIONS_FEATURE_REVIEW_LEARNING_RECALL=1|0`.
+
+## Staged rollout and acceptance
+
+Review-learning ships behind two independent, default-off flags so the schema,
+capture, recall, promotion, contradiction, and diagnostics code can all land on
+`main` without changing a single rendered prompt. The rollout is deliberately
+staged and measured; do not skip stages.
+
+### Stage 0 — flags off (baseline behaviour)
+
+With both `review-learning-capture` and `review-learning-recall` off:
+
+- No candidate or lesson is captured; a `changes-requested` review completion is
+  handled exactly as before.
+- No `## Applicable Prior Review Lessons` section is ever rendered, so the review,
+  fix, re-review, memory, comment-poller, and dashboard flows are byte-for-byte
+  identical to the pre-feature engine.
+- `processReviewLearningApplications` short-circuits (recall gate), so an agent's
+  `reviewLearningApplications` payload is ignored and no lesson is mutated.
+- Any records that already exist in SQL (e.g. from a prior enabled window or the
+  offline backfill) stay fully auditable through the diagnostics endpoints; only
+  prompt injection is gated, never storage or inspection.
+
+### Stage 1 — capture-only for 30 days
+
+Enable `review-learning-capture` only (recall stays off). This is the measurement
+baseline: verified findings become candidates and lessons and accrue `created`,
+`retrieved`-less, and `repeated-finding` lifecycle events, but **no lesson is ever
+injected into a prompt**. Capture-only changes no rendered prompt. Run this for at
+least 30 days to collect a per-project, per-normalized-area baseline recurrence
+rate (the share of resolved valid findings that recurred).
+
+### Stage 2 — one-project recall canary
+
+Enable `review-learning-recall` for a **single project** (per-project
+`config.features` override or the `MINIONS_FEATURE_REVIEW_LEARNING_RECALL` env
+override on that project's engine). Recall now injects at most 4 records / 4 KiB of
+bounded, fenced lessons on dispatches in that project. Watch the canary for:
+
+- contradiction alerts (`review-learning-contradiction` inbox notes) — an
+  evidence-backed contradiction quarantines the offending lesson automatically;
+- the retrieval decision traces (`/api/memory-records/retrieval-decision`) to
+  confirm lessons are selected for the right file/symbol reasons; and
+- the recurrence rate for the canary project's first 30 active days.
+
+### Expansion criteria (the success gate)
+
+`GET /api/memory-records/rollout-comparison`
+(`memoryStore.getReviewLearningRolloutComparison`) compares the **30-day
+capture-only baseline window** against the **first 30 days of active recall**,
+grouped by project and normalized area. It only reports `status: "success"` for a
+(project, area) when **both** windows clear the resolved-valid-finding floor
+(`minimumSample`, default 20 — otherwise `status: "insufficient-sample"`) **and**
+the repeated valid-finding rate fell by at least `minReduction` (default `0.25` =
+25%). A zero baseline rate is reported as `no-improvement`, never a divide-by-zero
+success. Do not broaden the recall canary to another project until its comparison
+row reports `success`.
+
+### Immediate prompt rollback
+
+Recall is a pure prompt-injection layer, so rolling it back is instant and total:
+
+1. Set `config.features["review-learning-recall"] = false` (or
+   `MINIONS_FEATURE_REVIEW_LEARNING_RECALL=0`). The very next dispatch renders no
+   `## Applicable Prior Review Lessons` section — disabling recall is a complete
+   prompt rollback.
+2. Optionally set `config.features["review-learning-capture"] = false` to stop
+   accruing new candidates/lessons. Existing records remain in SQL and stay
+   auditable through the diagnostics endpoints; nothing is deleted.
+
+No migration, restart-ordering, or data cleanup is required to roll back — the flags
+gate prompt behaviour, not storage.
+
+### Promotion into repository guidance
+
+A verified, **repeatedly observed** lesson can be promoted (human-approved) into
+guidance that vanilla runtimes discover natively (`engine/promotion.js`,
+`POST /api/memory-records/<id>/promote`). Promotion is eligible only at confidence
+≥ `0.8` and ≥ 2 distinct valid findings (the rule recurred at least once). It never
+edits an operator checkout: every promotion queues a normal project-bound work item
+that follows the standard branch → PR → review → merge lifecycle, landing the rule
+in an allowlisted instruction file (`CLAUDE.md` / `AGENTS.md` at any depth, or the
+GitHub Copilot instruction file) or a project skill. The guidance is only seen by
+vanilla Copilot/Claude once that PR merges.
+
+### Contradiction quarantine
+
+When a recall-enabled dispatch reports a lesson `outcome: "contradicted"` with
+exact current-code evidence — and only for a lesson its own trusted retrieval trace
+actually showed it, in its own project — the engine quarantines that lesson through
+the reversible `retracted` lifecycle (provenance retained) and raises a
+`review-learning-contradiction` operator inbox alert. `applied` and
+`considered-not-applicable` are task-local and never mutate the lesson. A
+quarantined lesson stops being recalled but can be `restore`d by an operator.
 
 ## Dashboard and API surfaces
 
@@ -376,8 +634,12 @@ inspect each lifecycle status.
 | `GET` | `/api/knowledge/<category>/<file>` | Read one KB file. |
 | `POST` | `/api/knowledge/sweep` | Start the asynchronous KB sweep. |
 | `GET` | `/api/knowledge/sweep/status` | Poll sweep status. |
-| `GET` | `/api/memory-records/search?q=...&status=active&limit=20` | Search structured records with provenance. |
+| `GET` | `/api/memory-records/search?q=...&status=active&limit=20` | Search structured records with provenance; optional `project`/`author`/`audience`/`sourceType`/`findingKey` filters. |
 | `POST` | `/api/memory-records/<id>/action` | Apply `pin`, `retract`, or `restore`. |
+| `GET` | `/api/memory-records/retrieval-decision?dispatchId=...` | Latest bounded retrieval decision (selection/exclusion reasons) for a dispatch or work item. |
+| `GET` | `/api/memory-records/lifecycle?findingKey=...` | Bounded lifecycle timeline + event-type counters. |
+| `GET` | `/api/memory-records/rollout?project=...` | Bounded rollout aggregates (created/retrieved/applied/retracted/repeated + recurrence rate). |
+| `GET` | `/api/memory-records/rollout-comparison?baselineFrom=...&baselineTo=...&activeFrom=...&activeTo=...` | Staged-rollout success gate: capture-only baseline window vs active-recall window per project/area (see **Staged rollout and acceptance**). |
 | `POST` | `/api/inbox/persist` | Copy an inbox excerpt into `notes.md`, then archive the source. |
 | `POST` | `/api/inbox/promote-kb` | Move an inbox item into a selected KB category. |
 
@@ -460,8 +722,15 @@ Markdown tiers are automatically copied into the prompt.
   classification, personal routing, pruning, reconciliation, and summary.
 - [`engine/db/migrations/017-agent-memory.js`](../engine/db/migrations/017-agent-memory.js)
   - schema and one-time Markdown backfill.
+- [`engine/db/migrations/027-review-learning-lifecycle.js`](../engine/db/migrations/027-review-learning-lifecycle.js)
+  - in-place retrieval/lifecycle schema extension and exact legacy-feedback
+    quarantine.
+- [`engine/review-learning.js`](../engine/review-learning.js) - dispositions,
+  stable finding/area identities, redaction, bounds, record validation, event
+  keys, and candidate transitions.
 - [`engine/memory-store.js`](../engine/memory-store.js) - record validation,
-  lifecycle, FTS5 query, and telemetry persistence.
+  lifecycle, FTS5 query, candidate/lesson helpers, bounded telemetry, and
+  rollout aggregates.
 - [`engine/memory-retrieval.js`](../engine/memory-retrieval.js) - task query,
   reranking, deduplication, provenance formatting, and byte packing.
 - [`engine/playbook.js`](../engine/playbook.js) - pinned/retrieved/legacy prompt

package/docs/tutorials/03-plan-driven-feature.md

@@ -14,9 +14,9 @@ tests. Keep implementation, tests, and documentation as separate items with
 explicit dependencies.
 ```
 
-The plan agent writes Markdown under `plans/`. The plan-to-PRD step then creates
-structured items under `prd/` with acceptance criteria and `depends_on`
-relationships.
+The plan agent writes Markdown under `plans/`. The plan-to-PRD agent writes a
+one-shot result sidecar; the engine validates it and imports structured items
+with acceptance criteria and `depends_on` relationships into SQLite.
 
 You can also provide plan text from the CLI:
 

package/docs/tutorials/04-runtimes-and-harness.md

@@ -1,8 +1,8 @@
-# Tutorial 4: Choose Runtimes and Propagate Project Tools
+# Tutorial 4: Choose Runtimes and Use Native Project Tools
 
 Minions can dispatch with Copilot CLI, Claude Code, or Codex. This tutorial
 switches the fleet runtime, separates Command Center from agent settings, and
-checks which skills, commands, and MCP configurations reach a worktree.
+checks the selected runtime's native skill, command, and MCP discovery surface.
 
 ## 1. Inspect the current fleet
 
@@ -40,38 +40,35 @@ Changing CC does not silently switch dispatched agents.
 
 ## 3. Add a project-local skill
 
-In the linked repository's main checkout, create a committed skill under:
+Use the selected runtime's native project skill root:
 
 ```text
-.claude/skills/<skill-name>/SKILL.md
+Claude:  .claude/skills/<skill-name>/SKILL.md
+Copilot: .github/skills/<skill-name>/SKILL.md
+Codex:   .agents/skills/<skill-name>/SKILL.md
 ```
 
 Describe when the skill applies and provide the exact existing project command
-to run. Commit the skill if every worktree should receive it. Uncommitted
-project-local assets can be propagated from the live checkout when
-`engine.harnessPropagateProjectLocal` is enabled, but committed assets are more
-reproducible.
+to run. Commit the skill so worktree-mode dispatches receive it. Copilot also
+reads `.claude/skills` and `.agents/skills`, but Claude does not natively discover
+`.agents/skills`. Uncommitted assets are visible only when the dispatch actually
+runs in that checkout, such as live checkout mode.
 
-## 4. Verify propagation
+## 4. Verify native discovery
 
 ```bash
 minions doctor --harness
 ```
 
-Dispatch a small task that clearly matches the skill. The completion report's
-`harnessUsed` section distinguishes assets that were available from those the
-agent reports actually using.
-
-For a known-empty execution environment, enable `hermeticHarness` for an agent
-or the fleet. This removes user asset directories and project harness
-propagation; use it for reproducibility tests, not as an MCP process-launch
-control.
+The report inventories adapter-declared roots and whether they exist. It does
+not inject assets or attest that the runtime loaded or used them. Dispatch a
+small task that clearly matches the skill and inspect the runtime output for
+the observable behavior you requested.
 
 ## Checkpoint
 
-The selected runtime passes doctor, your project asset appears in the harness
-survey, and a matching dispatch reports whether it used that asset.
+The selected runtime passes doctor, the committed skill is present in the
+dispatch checkout, and a matching task exhibits the skill's requested behavior.
 
 Reference: [Runtime Adapters](../runtime-adapters.md),
-[Harness Propagation](../harness-propagation.md), and
-[Harness Transparency](../harness-transparency.md).
+[Native Repository Harness](../harness-propagation.md).

package/docs/tutorials/08-operations-and-recovery.md

@@ -12,8 +12,9 @@ minions sources
 ```
 
 Use the dashboard **Engine** page for dispatch logs, metrics, managed processes,
-and worktree state. Read JSON sidecars only as diagnostics; migrated runtime
-state is canonical in `engine/state.db`.
+and worktree state. Runtime state is canonical in `engine/state.db`; remaining
+JSON files have explicit configuration, definition, cache, artifact, or
+coordination contracts and are not state mirrors.
 
 ## 2. Classify before acting
 

package/docs/tutorials/README.md

@@ -9,7 +9,7 @@ only describing configuration.
 | [1. Install and connect a project](01-install-and-connect.md) | A healthy engine, dashboard, and linked repository | 15 min |
 | [2. Ship your first task](02-first-task.md) | One scoped work item dispatched and tracked to completion | 15 min |
 | [3. Build a feature from a plan](03-plan-driven-feature.md) | An approved PRD with dependency-aware implementation and verification | 25 min |
-| [4. Choose runtimes and propagate project tools](04-runtimes-and-harness.md) | A configured fleet with verified skills, commands, and MCP visibility | 20 min |
+| [4. Choose runtimes and use native project tools](04-runtimes-and-harness.md) | A configured fleet with verified native skill, command, and MCP discovery | 20 min |
 | [5. Automate recurring work and follow-ups](05-schedules-and-watches.md) | A schedule and a condition-based watch | 25 min |
 | [6. Keep a development service running](06-managed-services.md) | An engine-owned, health-checked development service | 25 min |
 | [7. Coordinate a cross-repository change](07-cross-repo-plan.md) | One plan fanned out safely across multiple projects | 30 min |
@@ -21,8 +21,9 @@ only describing configuration.
   open a real pull request.
 - Keep the dashboard open while following CLI steps. It is the easiest place to
   see routing, pending reasons, live output, and artifacts together.
-- Treat JSON files under `engine/` and `projects/` as diagnostic mirrors.
-  `engine/state.db` is the primary store for migrated runtime state.
+- Treat `engine/state.db` as the sole runtime-state store. Remaining JSON files
+  are explicit configuration, definitions, caches, artifacts, or coordination
+  sidecars — not runtime mirrors.
 - Use the linked reference docs when you need the full schema or lifecycle.
   Tutorials intentionally focus on a successful path.
 

package/docs/visual-evidence-ci.md

@@ -0,0 +1,103 @@
+# PR visual evidence CI
+
+The OPG GitHub workflow captures matched dashboard screenshots for pull requests that change visual dashboard inputs. It compares live base and head checkouts; it never compares a committed demo image with a live PR.
+
+## Triggering
+
+`Visual evidence capture` runs automatically when a PR changes:
+
+- `dashboard/**`
+- `dashboard-build.js`
+- `docs/capture-demos.js`
+- `test/seed-demo-data.js`
+
+Add the `visual-evidence` label to opt in a visual change outside that list. Removing the label removes the opt-in. Backend, test-only, prose-only, and documentation-only PRs do not start browsers unless explicitly labeled.
+
+## Capture contract
+
+The capture workflow:
+
+1. Resolves the exact PR, repository, base, and head tuple from the trusted `pull_request_target` event and records it with the workflow run ID and attempt. The request builder comes from the exact `github.workflow_sha` revision, so an older PR base that predates the controller records a `controller-not-on-base` opt-out instead of failing the plan.
+2. Captures and uploads BEFORE in a base-only job.
+3. Starts the separate head job only after BEFORE has been uploaded, then runs the untrusted dashboard in a capability-dropped container with a read-only root/source/controller and one writable marker-owned state mount. The trusted host owns the browser and AFTER output.
+4. Seeds marker-owned state directories with the same deterministic demo fixture.
+5. Starts each checkout on the same port and captures it with the base branch's canonical [`capture-demos.js`](capture-demos.js).
+6. Uses Chromium at 1400x900, dark theme, `en-US`, UTC, reduced motion, and a fixed browser time.
+7. Requires the same ten non-empty PNG names on both sides.
+
+Startup, fixture, and capture logs are retained with the images. Partial output is never presented as a successful comparison: a failed AFTER side fails the run, and a failed BEFORE side degrades the run to an explicitly-labelled AFTER-only publication (see [Degraded AFTER-only runs](#degraded-after-only-runs)).
+
+## Artifacts and PR summary
+
+GitHub Actions stores five artifacts keyed by PR number and full head SHA:
+
+- capture-request metadata
+- BEFORE PNG set
+- AFTER PNG set
+- BEFORE logs and `result.json`
+- AFTER logs and `result.json`
+
+Artifacts expire after **14 days**. Each upload replaces its same-run name on a rerun, so a later attempt refreshes all five artifacts instead of colliding with the prior attempt. The trusted publisher creates or updates one `github-actions[bot]` comment with BEFORE/AFTER artifact links. All publisher jobs serialize globally through GitHub Actions' multi-entry concurrency queue before mutating PR comments, so a newly queued publisher does not replace an already-pending publication. Each publisher also checks the authoritative workflow-run order before changing comments. Older runs and attempts are suppressed even when a newer opt-out run left no summary. Results for an obsolete head are suppressed when a current result exists; an already-posted result is marked stale when its head no longer matches. If the current PR diff no longer requests visual evidence, the old bot summary is removed.
+
+## Degraded AFTER-only runs
+
+`capture-before` checks out `github.event.pull_request.base.sha` and runs the **base branch's** seed and capture code, not the pull request's. A defect already merged to `main` therefore breaks the BEFORE side of every PR opened against that base — including the PR that repairs the base, which could otherwise never show a green check.
+
+The BEFORE side is consequently non-blocking:
+
+- `capture-before` carries `continue-on-error: true` and is named `Capture BEFORE (base, non-blocking)`, the same convention `pr-tests.yml` uses for its non-blocking `perf-tests` job. The failure surfaces as a warning annotation plus a job summary that names the base SHA and states the run is AFTER-only; it does not present a blocking red check on the PR.
+- `Upload BEFORE screenshots` uses `if-no-files-found: warn`, so a crashed capture that wrote zero PNGs is reported once by the capture step instead of raising a second hard error. `Upload BEFORE capture logs` deliberately stays `if-no-files-found: error` — the logs directory is always written and is what makes the failure diagnosable.
+- `capture-after` is gated on `!cancelled() && needs.plan.outputs.capture == 'true'` instead of a successful `capture-before`, so the head-side capture still runs and uploads. The plan gate is re-asserted directly because it is no longer inherited through a green BEFORE job, and `!cancelled()` keeps a run superseded by `cancel-in-progress` from spending a full Docker and Playwright capture.
+
+The publisher degrades in step. When the run concludes successfully and the BEFORE PNG set is the *only* missing artifact, `assessArtifacts` returns `status: 'after-only'` and the bot comment is titled **"Visual evidence: AFTER only (BEFORE capture failed)"**. It states that this is not a BEFORE/AFTER comparison, renders the BEFORE cell as `capture failed - no screenshots`, and links the BEFORE logs for diagnosis. Any other gap — a missing AFTER set, missing BEFORE logs, duplicate artifacts, or a genuinely failed run — still reports the full failure summary. A reviewer is never handed a half-capture presented as a matched pair.
+
+Nothing about the security posture changes: the controller and base checkout still run from the trusted base ref with `persist-credentials: false`, `Verify exact base checkout` is unchanged, and untrusted head code gains no execution privileges.
+
+## Security boundary
+
+The workflow definition and capture-request builder run from the exact trusted `github.workflow_sha` revision through `pull_request_target`; detection and capture execution remain pinned to the PR's trusted base SHA. If that historical base does not contain the controller, detection suppresses both browser jobs while the trusted workflow revision still records the opt-out request artifact. Neither planning path loads controller code from the untrusted head. The workflow has only `contents: read` and `pull-requests: read`, checkout credentials are not persisted, and no write-capable token is available. BEFORE and AFTER use separate runners, and AFTER cannot start until the immutable BEFORE artifact has uploaded. The head dashboard runs without the Actions process environment, host process namespace, controller checkout, screenshot output, or Docker socket; its source/controller mounts and container root are read-only. The sole writable bind mount is marker-owned `/state`, and the container runs as the host UID:GID that owns it. Secret-shaped variables and GitHub Actions control-file variables are removed from host capture child processes.
+
+Comment publication happens later in `visual-evidence-publish.yml`, triggered by `workflow_run`. That job checks out only the repository default branch and requires a `pull_request_target` run from the trusted base repository. It downloads and parses only the trusted plan job's capture-request JSON, then binds its repository, workflow, stable run ID, PR, base, head repository, base branch, and full head SHA to the live run before writing. A request retained from an earlier attempt is valid for a selective rerun of that same run ID, while metadata claiming a future attempt is rejected. The run's `head_sha` is the captured PR head; publication does not depend on the optional `workflow_run.pull_requests` association. Screenshot and log artifacts remain link-only and are never downloaded or executed by the publisher.
+
+## Base-controller failure mode
+
+Because the seeder (`test/seed-demo-data.js`) and Playwright controller (`docs/capture-demos.js`) always execute from the base checkout, a break in either one is only observable once it is on `main`: every subsequent BEFORE capture fails, for every PR, and no change on a PR branch can repair it — the PR's own copy is never executed. Both files are also visual paths, so even a PR that fixes them triggers the broken capture. Since `capture-before` is non-blocking, the visible symptom is that every PR degrades to an AFTER-only publication (see [Degraded AFTER-only runs](#degraded-after-only-runs)) until the fix lands. Recovery is to land the fix on `main` (admin bypass) and then push to the affected PRs so a fresh `pull_request_target` event picks up a base SHA that contains it. `test/unit/visual-evidence-ci.test.js` runs the seeder's full seeding body so this class of break fails PR Tests before it can reach `main`.
+
+## Local reproduction
+
+Start from a trusted checkout of the base branch, never the pull request/head checkout. Resolve the exact full base and head SHAs independently, then use two disposable worktrees and keep output outside both:
+
+```bash
+BASE_WORKTREE=../visual-base
+HEAD_WORKTREE=../visual-head
+OUTPUT_ROOT=../visual-output
+git worktree add --detach "$BASE_WORKTREE" <full-base-sha>
+git worktree add --detach "$HEAD_WORKTREE" <full-head-sha>
+test "$(git -C "$BASE_WORKTREE" rev-parse HEAD)" = "<full-base-sha>"
+test "$(git -C "$HEAD_WORKTREE" rev-parse HEAD)" = "<full-head-sha>"
+npm --prefix "$BASE_WORKTREE" ci --ignore-scripts
+npm --prefix "$BASE_WORKTREE" exec -- playwright install chromium
+node "${BASE_WORKTREE}/.github/scripts/run-visual-evidence.js" \
+  --dashboard-runtime docker \
+  --controller-root "$BASE_WORKTREE" \
+  --base-root "$BASE_WORKTREE" \
+  --head-root "$HEAD_WORKTREE" \
+  --base-sha <full-base-sha> \
+  --head-sha <full-head-sha> \
+  --output-root "$OUTPUT_ROOT"
+```
+
+The PNGs land in `../visual-output/{before,after}` and logs in `../visual-output/logs`. Docker is the default dashboard runtime so neither dashboard checkout executes in the host Node process. The host still executes the runner, fixture seeder, and Playwright controller, all from the exact base worktree; the runner verifies that controller checkout against `--base-sha` before mutating output. `--dashboard-runtime process` is an explicit opt-in for code you trust. The output root must be new, empty, or carry the runner's `.minions-visual-evidence-output` ownership marker, and it must not overlap either checkout or the controller in either direction. Reruns clear only the known generated subdirectories beneath a valid marker-owned root. Remove the disposable worktrees with the normal `git worktree remove` command after inspection.
+
+## Complementary in-description embeds (agent-authored)
+
+The CI workflow above is one of **two** complementary visual-evidence surfaces; it is not the only one:
+
+- **`Visual evidence capture` (this workflow)** — an automated, sandboxed BEFORE/AFTER comparison posted by `github-actions[bot]`. It is untouched by the agent flow and remains the trusted comparison of record.
+- **Agent-embedded screenshots (additive, W-mrz1yc79)** — when a Minions dispatch makes a meaningful **visual/UI change** (dashboard pages, slim-ux, Settings, work-item/PR/plan views, badges, layout/CSS), the agent proactively captures screenshots and embeds them directly in the PR **description** (`![view (after)](url)`), rather than relying only on the bot. Backend-only, engine-logic, text/prose-only, analysis, and docs changes get no screenshots.
+
+The agent embed path does **not** replace or modify the CI workflow — the two coexist. Mechanics the agent uses (full recipe in `playbooks/_pr-description-audit.md` → "Screenshot handling"):
+
+- **GitHub:** raw PNGs are saved under `agents/<id>/screenshots/` (never `git add`ed), published as assets on a dedicated per-PR prerelease (`gh release create pr-<num>-visual … --prerelease`, or `gh release upload … --clobber` on re-dispatch), and embedded via each asset's `browser_download_url`. This works on private repos and never commits PNGs to the source branch. The upload uses a per-command `GH_TOKEN` for the repo owner's account (`opg-microsoft` → `yemishin_microsoft`, `yemi33` → `yemi33`) and never runs `gh auth switch`.
+- **Azure DevOps:** `PUT /pullRequests/<id>/attachments/<filename>` with the PNG bytes, then reference the returned URL.
+- **Degrade gracefully:** if the dev server won't start, the route 404s, Playwright is unavailable, or the upload fails, the agent skips without failing the work item and records the reason under `meta.descriptionAudit`.