@yemi33/minions 0.1.2424 → 0.1.2426

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/01-install-and-connect.md

@@ -9,6 +9,8 @@ repository, and start the engine and dashboard.
 - Git
 - GitHub Copilot CLI, Claude Code, or Codex CLI with working authentication
 - A local Git repository with an `origin` remote
+- For the internal (OPG) install: Azure CLI signed in (`az login`) and Azure
+  Artifacts **read** permission on the ISS `ProjectFeed-ISS` feed
 
 Minions defaults to GitHub Copilot CLI. Install it if you have not selected a
 different runtime:
@@ -19,6 +21,27 @@ npm install -g @github/copilot
 
 ## 1. Install and initialize
 
+Install the internal package `@opg-microsoft/minions` from the ISS
+`ProjectFeed-ISS` Azure Artifacts feed using the repository's one-command
+installer:
+
+```powershell
+scripts\install-internal-minions.ps1     # Windows
+```
+
+```bash
+./scripts/install-internal-minions.sh    # Linux / macOS
+```
+
+The installer validates feed access, installs the package, and then runs the
+supported `minions init --force` synchronization — so no separate `minions init`
+is needed. It authenticates with a short-lived token from your existing `az`
+login; no PAT is created, accepted, or stored. See
+[internal-install.md](internal-install.md) for options and troubleshooting.
+
+If you do not have access to the ISS `ProjectFeed-ISS` feed, install the public
+package from npm instead (a separate release channel, not the OPG path):
+
 ```bash
 npm install -g @yemi33/minions
 minions init

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.