@yemi33/minions 0.1.2370 → 0.1.2371

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2370",
+  "version": "0.1.2371",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"
@@ -29,7 +29,7 @@
     "test:e2e:accept": "node test/playwright/accept-baseline.js",
     "test:e2e:accept-force": "node test/playwright/accept-baseline.js --force",
     "test:setup": "npx playwright install chromium",
-    "lint": "eslint dashboard/ engine/ado.js engine/github.js engine/lifecycle.js engine/queries.js engine/watches.js engine/cli.js"
+    "lint": "eslint dashboard/ engine.js engine/ dashboard.js dashboard-build.js bin/"
   },
   "keywords": [
     "ai",

package/playbooks/build-fix-complex.md

@@ -76,10 +76,6 @@ Use subagents only for genuinely parallel, independent tasks (e.g., editing file
 
 ## Health Check
 
-{{#project_skills_block}}
-{{project_skills_block}}
-
-{{/project_skills_block}}
 Before starting work, run `git status` and verify the worktree is clean and on the expected branch (`{{pr_branch}}`). If the worktree is dirty or on the wrong branch, report the issue and stop.
 
 ## Validation

package/playbooks/fix.md

@@ -53,10 +53,6 @@ Before editing, split the feedback into:
 
 ## Health Check
 
-{{#project_skills_block}}
-{{project_skills_block}}
-
-{{/project_skills_block}}
 Before starting work, run `git status` and verify the worktree is clean and on the expected branch (`{{pr_branch}}`). If the worktree is dirty or on the wrong branch, report the issue and stop.
 
 ### Branch-mismatch guard (issue #2999)

package/playbooks/implement-shared.md

@@ -45,10 +45,6 @@ Do ALL work in the worktree.
 
 ## Health Check
 
-{{#project_skills_block}}
-{{project_skills_block}}
-
-{{/project_skills_block}}
 Before starting work, run `git status` and verify the worktree is clean and on the expected branch (`{{branch_name}}`). If the worktree is dirty or on the wrong branch, report the issue and stop.
 
 ## Working Style

package/playbooks/implement.md

@@ -38,10 +38,6 @@ If this feature spans multiple projects, inspect the relevant repos, make change
 
 ## Health Check
 
-{{#project_skills_block}}
-{{project_skills_block}}
-
-{{/project_skills_block}}
 Before starting work, run `git status` and verify the worktree is clean and on the expected branch. If the worktree is dirty or on the wrong branch, report the issue and stop.
 
 ## Working Style

package/playbooks/plan-to-prd.md

@@ -19,10 +19,6 @@ A user has provided a plan. Analyze it against the codebase and produce a struct
 
 ## Instructions
 
-{{#project_skills_block}}
-{{project_skills_block}}
-
-{{/project_skills_block}}
 1. **Read the plan carefully** — understand the goals, scope, and requirements
    - If the plan declares `Project: <name>` (including `**Project:** <name>`), the engine has resolved `{{project_name}}` from that declaration. Preserve `{{project_name}}` for the top-level `project`, default item `project`, filename, and implementation framing; do not let contextual mentions of another product or repository override it.
 2. **Check for an existing PRD** — if the engine provides `existing_prd_json` below, a PRD already exists for this plan. See "Reusing an Existing PRD" section for how to preserve item IDs and done statuses. If no existing PRD is provided, this is a fresh run — all items start as `"missing"`.
@@ -35,11 +31,20 @@ A user has provided a plan. Analyze it against the codebase and produce a struct
 
 ## Output
 
-Write the PRD to: `{{team_root}}/prd/{{prd_filename}}`
+Write the PRD result sidecar to: `{{team_root}}/agents/{{agent_id}}/prd-result.json`
+
+The sidecar must be an envelope with the exact pre-generated filename:
 
-**Use the exact filename above.** The engine pre-generates a unique filename to avoid collisions with existing or archived PRDs; renaming it will detach the PRD from the plan.
+```json
+{
+  "filename": "{{prd_filename}}",
+  "prd": {
+    "...": "the PRD object described below"
+  }
+}
+```
 
-This file is NOT checked into the repo. The engine reads it on every tick and dispatches implementation work automatically.
+The engine validates and imports this one-shot sidecar into SQLite when the dispatch completes, then deletes it. Do not write runtime state under `prd/`.
 
 ```json
 {
@@ -190,14 +195,14 @@ If the task description contains `mode: diff-aware-update`, you are updating an
 
 ## Important
 
-- Write ONLY the single `.json` PRD file to `{{team_root}}/prd/` — do NOT write any `.md` files there
+- Write ONLY the single result sidecar at `{{team_root}}/agents/{{agent_id}}/prd-result.json`
+- Wrap the PRD object in `{ "filename": "{{prd_filename}}", "prd": { ... } }`
 - Do NOT create a git branch, worktree, or PR — this playbook writes minions-internal state only
 - Do NOT modify any files in the project repo
-- **NEVER run `git add prd/` or `git add -f prd/` — PRD files are gitignored runtime artifacts (`prd/*.json` is in `.gitignore`). Force-adding them exposes internal work plans in the public repo diff. A CI guard (`test/unit/prd-not-git-tracked.test.js`) will fail the PR if you do this, and you will be required to run `git rm --cached prd/<file>.json` to undo it.**
-- The engine will dispatch implementation agents automatically once the JSON file exists
+- The engine will dispatch implementation agents automatically once the sidecar is imported
 - For `shared-branch`: agents commit to a single branch — one PR is created automatically when all items are done
 - For `parallel`: each agent creates its own branch and PR
 
 ## When to Stop
 
-Your task is complete once you have written the PRD JSON file to `{{team_root}}/prd/{{prd_filename}}`. The engine will detect the file and begin dispatching work. Do NOT run any git commands. Do NOT create branches, PRs, or modify project code. Stop after writing the JSON file.
+Your task is complete once you have written `{{team_root}}/agents/{{agent_id}}/prd-result.json`. The engine imports it into SQLite after you exit. Do NOT run any git commands. Do NOT create branches, PRs, or modify project code. Stop after writing the sidecar.

package/playbooks/plan.md

@@ -27,10 +27,6 @@ A user has described a feature they want built. Your job is to create a detailed
 - Identify the core goal, constraints, and success criteria
 - Note any ambiguities that need to be called out
 
-{{#project_skills_block}}
-{{project_skills_block}}
-
-{{/project_skills_block}}
 ### 2. Explore the Codebase
 - Read `CLAUDE.md` at repo root and relevant directories
 - Map the areas of code that this feature will touch

package/playbooks/review.md

@@ -27,12 +27,6 @@ Use subagents only for genuinely parallel, independent tasks (e.g., reviewing un
    git diff {{main_branch}}...origin/{{pr_branch}}
    ```
 
-{{#project_skills_block}}
-{{project_skills_block}}
-
-> **Skipping an in-scope review skill is gated.** Before you record a `meta.review.skillSkipped` (or `meta.skill.skipped`) outcome for any skill listed above, re-read that skill's own SKILL.md checklist and confirm your skip reason does not contradict any explicit "Flag if…" / "Verify that…" / "Requirements" item it documents. If the diff trips ANY such item, do NOT skip — apply the skill (or at least that item). When you do skip, surface the exact same `{name, reason}` in your PR review comment via `minions pr comment … --skill-skipped-json '{"name":"…","reason":"…"}'` so a human sees it alongside your verdict before merge (no drift between the report and the comment). See `playbooks/shared-rules.md` → "Skipped an in-scope project skill?".
-
-{{/project_skills_block}}
 2. Think about deploy risk before commenting:
    - What user-visible behavior changed?
    - What dependencies, callers, or tests could be affected?

package/playbooks/shared-rules.md

@@ -120,71 +120,6 @@ The engine provides a completion report path in the prompt and in `MINIONS_COMPL
 
 For the canonical schema — every field, the `failure_class` enum, `noop:true` semantics, `retryable` / `needs_rerun` shape, and the artifacts array — see `docs/completion-reports.md`. The JSON report is the primary signal; fenced `completion` blocks in stdout are accepted only as a fallback.
 
-## Harness transparency / self-report
-
-Populate the **optional** `harnessUsed` field on your completion report with the harness affordances you actually consulted to do the work — the skills you ran, the MCP servers you called, the slash-commands you invoked, and the reference docs you read. This is observability, not a gate: it lets the team see which tooling drove a dispatch and lets the engine cross-check your claims against what it actually exposed. Omit the field entirely when you used none; do not pad it with affordances you didn't touch.
-
-Use this canonical `{ skills, mcpServers, commands, docs }` shape. Each kind keeps only the listed fields; the **required** field must be present or the entry is dropped:
-
-- `skills` — `{ name, source, path }` (required: `name`; `source` is `user` / `project`)
-- `mcpServers` — `{ name, scope }` (required: `name`; `scope` is `user` / `project`)
-- `commands` — `{ name, scope }` (required: `name`)
-- `docs` — `{ path, why }` (required: `path`; `why` is a short reason you read it)
-
-Copyable worked example:
-
-```json
-{
-  "status": "success",
-  "summary": "Added the harnessUsed self-report contract to shared-rules + docs.",
-  "harnessUsed": {
-    "skills": [
-      {"name": "run-tests", "source": "project", "path": ".claude/skills/run-tests/SKILL.md"}
-    ],
-    "mcpServers": [
-      {"name": "azure-ado", "scope": "user"}
-    ],
-    "commands": [
-      {"name": "simplify", "scope": "user"}
-    ],
-    "docs": [
-      {"path": "docs/completion-reports.md", "why": "confirmed the harnessUsed field shape"}
-    ]
-  }
-}
-```
-
-Entries you report are **cross-checked** against what the engine propagated into your worktree and annotated `grounded: true | false` — never dropped — so a `grounded: false` entry surfaces a discrepancy for a human rather than being hidden. Full contract: `docs/harness-transparency.md`.
-
-When you author a **PR review / fix summary comment**, the same harness footprint belongs in the comment body as a collapsible "Harnesses used" section so reviewers see which skills / MCPs / docs informed the change.
-
-**Preferred — `minions pr comment` (GitHub and Azure DevOps `--host ado`): do NOT hand-render the section.** Write your `harnessUsed` record — the same `{ skills, mcpServers, commands, docs }` shape as the completion field above — to a JSON file and pass `--harness-file <path>` (or inline via `--harness-json <json>`). The shared builder (`engine/comment-format.js#buildHarnessUsedSection`, consumed by both `engine/gh-comment.js` and `engine/ado-comment.js`) folds the byte-identical `<details>` section into the body for you, so agent-authored and engine-authored comments match. Each entry is cross-checked against the harness manifest the engine propagated into your worktree and annotated `grounded: true | false` (never dropped); a `grounded: false`, ⚠️-marked bullet means **the engine couldn't confirm that affordance against the propagated manifest — not that you did anything wrong**.
-
-**Raw fallbacks only — `gh pr comment` / `az repos pr comment` / ADO REST:** these bypass the CLI chokepoint, so you MUST hand-render the section yourself. Render it **identically on both hosts** — append this exact `<details>` block at the end of your comment body (omit it entirely when you used no affordances):
-
-```markdown
-<details>
-<summary>🧰 Harnesses used (N)</summary>
-
-- 🧩 `skill-name` — source
-- 🔌 `mcp-name` — scope
-- ⌘ `command-name` — scope
-- 📄 `docs/some-doc.md` — why you read it
-
-</details>
-```
-
-One bullet per affordance, in the order skills → MCP servers → commands → docs; `N` is the bullet count. Whether the CLI folds it in or you hand-render it on a raw fallback, the section is the human-readable mirror of your `harnessUsed` completion field — keep the two consistent.
-
-### Skipped an in-scope project skill? Validate the skip, then surface it in the PR comment
-
-`meta.review.skillSkipped` / `meta.skill.skipped` (shape `{name, reason}`, see `docs/completion-reports.md`) lets you self-report that you intentionally skipped an available, **in-scope** project (review) skill. Two hard rules apply — this is not aspirational:
-
-1. **Validate the skip against the skill's own scope before recording it.** Re-read the skipped skill's SKILL.md review criteria / checklist (the content already injected via the `## Project skills` / `## Project review skills` block). Confirm your skip reason does **not** contradict any explicit "Flag if…" / "Verify that…" / "Requirements" item the skill documents. If the diff trips ANY explicit checklist item the skill covers, skipping is **not** permitted — apply the skill (or at minimum that specific checklist item). A skip reason that waves away a gate the skill explicitly documents (e.g. "no CHANGELOG needed for this diff" when the skill's CHANGELOG Requirements section says otherwise) is invalid.
-2. **Surface the skip in the PR comment, not just the JSON.** When you post a review/fix summary comment, the skip must be visible in the same comment as the verdict so a human sees it **before** merge. Via `minions pr comment` (GitHub and ADO `--host ado`), pass `--skill-skipped-file <path>` (JSON `{name, reason}`) or inline `--skill-skipped-json <json>`; the shared builder (`engine/comment-format.js#buildSkippedSkillSection`, consumed by both `engine/gh-comment.js` and `engine/ado-comment.js`) folds a byte-identical `> ⚠️ Skipped project skill: <name> — <reason>` callout in for you. On raw fallbacks (`gh pr comment` / `az repos pr comment` / ADO REST) render that exact one-line blockquote callout yourself.
-
-The **same** `{name, reason}` you record in `meta.review.skillSkipped` / `meta.skill.skipped` must be the one rendered in the PR comment — no drift between the two.
-
 ## Minions API access
 
 The Minions dashboard runs at `http://localhost:7331` whenever the engine is up. Agents may call its HTTP endpoints when (and only when) the playbook explicitly authorizes it for a particular task — most dispatches do not need any API access, and uninvited writes to engine-managed state are still prohibited (see "Do NOT write to `agents/*/status.json`" above).

package/docs/harness-transparency.md

@@ -1,199 +0,0 @@
-# Harness Transparency
-
-Plan P-a8f3c2d1. Minions gives dispatched agents a *harness* — the skills, MCP
-servers, slash-commands, and reference docs the engine makes reachable inside a
-worktree (user-scope `~/.claude` / `~/.copilot` / `~/.agents`, project-local
-`.claude/skills`, `.mcp.json`, propagated `--add-dir` roots, …). Harness
-transparency makes that surface **observable after the fact**: which of those
-affordances did the agent actually consult to do the work?
-
-The contract has three stages — **capture → ground → surface** — and a single
-canonical vocabulary that every stage speaks.
-
-## Canonical vocabulary
-
-Defined in `engine/shared.js` as `HARNESS_USED_KINDS`. Four kinds; each declares
-the only fields that survive normalization plus the one field that MUST be
-present for an entry to be kept:
-
-| Kind | Fields | Required |
-|---|---|---|
-| `skills` | `name`, `source`, `path` | `name` |
-| `mcpServers` | `name`, `scope` | `name` |
-| `commands` | `name`, `scope` | `name` |
-| `docs` | `path`, `why` | `path` |
-
-`shared.normalizeHarnessUsed(raw)` validates and clamps any untrusted
-`harnessUsed`-shaped object into this canonical `{ skills, mcpServers, commands,
-docs }` form: it drops malformed entries (non-objects, or entries missing the
-kind's required field), keeps only whitelisted string fields (trimmed and
-clamped to `HARNESS_USED_MAX_FIELD_LEN` = 512 chars), caps each array at
-`HARNESS_USED_MAX_ENTRIES` = 50, and returns `null` when nothing survives so
-callers can treat "no harness data" as one falsy case. When non-null, all four
-kind keys are always present (empty arrays for kinds with no entries) for a
-stable downstream shape.
-
-## Stage 1 — Capture (agent self-report)
-
-Every agent populates `completionReport.harnessUsed` with the affordances it
-actually used. This is a self-report: the agent is the only party that knows
-*which* skill it ran or *which* doc it read. The field is optional and
-backward-compatible — agents that omit it stay valid. See
-[completion-reports.md → harnessUsed](completion-reports.md#harness-usage-harnessused)
-for the field schema and a copyable example, and `playbooks/shared-rules.md`
-→ "Harness transparency / self-report" for the per-task instruction every
-playbook inherits.
-
-## Stage 2 — Ground (engine cross-check)
-
-A self-report is a *claim*. Grounding cross-checks it against what the engine
-actually exposed.
-
-At spawn time (`engine.js spawnAgent`, P-a8f3c2d1) the engine folds the
-resolved harness roots — `queries.getUserHarnesses` (user-scope) +
-`queries.getProjectHarnesses` (project-scope) — plus the computed `--add-dir`
-set into a `_harnessPropagated` manifest via
-`queries.buildHarnessPropagatedManifest({ userHarnesses, projectHarnesses,
-addDirs })`. The manifest unions **both** user-scope and project-scope
-contributions and dedups by path, then is persisted onto the dispatch record as
-`_harnessPropagated`. Capturing user-scope harnesses is load-bearing:
-otherwise a legitimate `~/.agents` / `~/.claude` skill usage would be wrongly
-flagged un-grounded downstream. This capture is observability only — it does
-**not** change which dirs are propagated at spawn time, and any failure here is
-non-fatal (the spawn proceeds).
-
-**Monorepo sub-project contributes `--add-dir` roots (P-f52d81ba).** The `addDirs` set
-folded into the manifest includes the project-local harness dirs propagated for
-the dispatch. When the engine auto-derives a dominant sub-project (see
-[project-skills.md → Monorepo sub-project scoping](project-skills.md#monorepo-sub-project-scoping)),
-those sub-project-scoped `--project-harness-dir` roots flow into `propagatedProjectHarnessDirs`
-→ `addDirs` → the `_harnessPropagated` manifest. The clip that selects them is
-the **same** `shared.filterProjectHarnessDirsForWorkdir` used for an explicit
-`meta.workdir` — `spawnAgent` passes `workdir: validatedWorkdir || _effectiveSubproject
-|| null`, so an explicit `meta.workdir` wins, else the auto-derived sub-project's
-first-level segment clips the surface, else no clip (whole-project harness).
-Because the manifest captures the same sub-project-clipped roots the agent was actually
-handed, a self-reported skill usage against a sub-project's skill (e.g.
-`ocm/.claude/skills/…`) still grounds `true` — grounding stays faithful under
-sub-project scoping instead of falsely flagging the sub-project's own skills.
-
-The grounding cross-check (P-c6f5e8b3) runs in `engine/lifecycle.js`
-`runPostCompletionHooks` once the completion report is parsed and nonce-trusted:
-`shared.groundHarnessUsed(completionReport.harnessUsed, _harnessPropagated)`
-normalizes the self-report (same clamp/drop rules as `normalizeHarnessUsed`) and
-annotates each surviving entry `grounded: true | false`. The grounded object
-replaces `structuredCompletion.harnessUsed` in place, so it rides the existing
-completion storage onto the completed dispatch record for the Stage-3 readouts.
-The spawn-time manifest is located via `lifecycle.resolveHarnessPropagated`
-(in-memory dispatch record first, then the persisted dispatch queues for the
-restart/re-attach case). It compares each self-reported entry against the
-`_harnessPropagated` manifest and annotates it `grounded: true | false`:
-
-- `grounded: true` — the engine demonstrably exposed this affordance.
-- `grounded: false` — the entry is **kept, not dropped**, and flagged. A
-  false here means "the agent claims it used something the engine has no record
-  of exposing" — which can be a genuine out-of-band tool, a stale path, or a
-  hallucinated entry. The point is to surface the discrepancy for a human, not
-  to silently discard the claim.
-
-An entry grounds `true` on any of these signals (OR'd):
-
-- **identity** — the entry's `name` matches a propagated entry's name of the
-  same kind, or (skills/docs) its `path` is lexically contained under a
-  propagated skill root or `--add-dir`, or `basename(path)` matches a propagated
-  skill name.
-- **scope** — the entry's scope (skills use `source`) matches a propagated
-  entry's scope of the same kind. The capture manifest records harness *roots*
-  (skill/command dirs, MCP config files), not individual affordances, so a
-  per-affordance self-report frequently can't match by name; scope membership is
-  the coarse-but-honest "the engine exposed this surface" signal the manifest
-  can attest. `docs` carry no scope, so path containment is their only signal —
-  a relative doc path (`docs/foo.md`) can't be tested against absolute add-dirs
-  and grounds `false`.
-
-## Stage 3 — Surface (three readouts)
-
-Grounded harness usage is rendered on three surfaces so a human (or a later
-evaluation pass) can see what tooling drove a dispatch:
-
-1. **PR comment** (P-e4b7a6d5) — the harness digest is folded into the agent's
-   PR comment/summary so reviewers see which skills / MCPs / docs informed the
-   change. `engine/comment-format.js#buildHarnessUsedSection(harnessUsed)` is
-   the single, platform-neutral renderer: it turns the grounded
-   `{ skills, mcpServers, commands, docs }` record into a collapsible Markdown
-   `<details>` block (one bullet per affordance, `grounded: false` entries kept
-   and ⚠️-marked), and returns `''` for an empty/absent record. The GitHub
-   comment path folds it in via `engine/gh-comment.js#buildMinionsCommentBody`
-   (optional `harnessUsed` arg, threaded through `postPrComment` /
-   `postPrReviewComment`); the Azure DevOps path mirrors it via
-   `engine/ado-comment.js#postAdoPrComment` (same builder, same `harnessUsed`
-   arg). Both posters are reached from the `minions pr comment` CLI, which turns
-   `--harness-file` / `--harness-json` into the grounded record and folds the
-   **byte-identical** section in for the agent. Only the raw `gh pr comment` /
-   `az repos pr comment` / REST fallbacks bypass that chokepoint, so on those
-   paths review/fix agents append the section themselves per
-   `playbooks/shared-rules.md` → "Harness transparency / self-report". Every
-   surface consumes the one renderer, so there is no second formatter to drift.
-
-   **Skipped in-scope project skill (W-mr287sc0000uc214).** The same PR-comment
-   surface also folds in a VISIBLE (non-collapsed) `> ⚠️ Skipped project skill:
-   <name> — <reason>` callout when the agent self-reported that it intentionally
-   skipped an available, in-scope project (review) skill
-   (`meta.review.skillSkipped` / `meta.skill.skipped`). This lived only in the
-   completion-report JSON before — invisible to a human reading the PR pre-merge.
-   `engine/comment-format.js#buildSkippedSkillSection(skillSkipped)` is the single
-   neutral renderer (sibling of `buildHarnessUsedSection`); it is threaded through
-   `buildMinionsCommentBody` (optional `skillSkipped` arg) and both posters
-   (`gh-comment.js` / `ado-comment.js`), and the `minions pr comment` CLI turns
-   `--skill-skipped-file` / `--skill-skipped-json` into the record. Two rules
-   attach to the skip (see `docs/completion-reports.md` → Review/Project skill
-   outcomes): the skip reason must be **validated against the skill's own
-   documented checklist** before it is recorded (a skip that contradicts an
-   explicit "Flag if…" / "Requirements" item the skill covers is invalid), and
-   the `{name, reason}` rendered in the comment must match the one recorded in the
-   report (no drift).
-2. **Final agent note** — for a non-clean completion (failure / partial) the
-   single final agent report (`engine/lifecycle.js#writeNonCleanAgentReport`)
-   folds the grounded harness footprint in as the same `buildHarnessUsedSection`
-   block, so the learnings / inbox stream that feeds consolidation still carries
-   it without a separate per-attempt `harness-usage-*` note. Clean completions
-   rely on the work-item modal surface (#3) instead — they write no inbox note
-   at all (#308 removed the standalone harness-usage digest to cut note spam).
-3. **Work-item detail modal** — the dashboard work-item modal shows the
-   harness list alongside the completion artifacts (P-d5a6f7c4). On
-   completion, `engine/lifecycle.js promoteCompletionArtifacts` persists the
-   grounded `structuredCompletion.harnessUsed` onto the work item as
-   `_harnessUsed` (it survives the slim `/api/work-items` list payload and
-   modal hydration). `dashboard/js/render-work-items.js _wiRenderDetail` renders
-   the "Repo harnesses used" section from `item._harnessUsed`: one plain solid
-   pill per skill / MCP / command / doc. The grounding flag is **not** surfaced
-   in this modal — every entry renders identically (the per-pill dashed-border /
-   ⚠ marker distinction was dropped in PR #296). Grounding is surfaced only on
-   the PR-comment surface above.
-
-## Why it matters
-
-- **Tooling ROI.** Knowing which skills/MCPs are actually consulted (vs. shipped
-  and ignored) tells the team where to invest in harness affordances.
-- **Grounding catches drift.** `grounded: false` entries flag stale paths,
-  renamed skills, or agents reaching for tooling the engine didn't actually
-  wire in — without dropping the signal.
-- **Evaluation.** Comparing skill-driven work against first-principles work
-  (cf. `meta.skill` in [completion-reports.md](completion-reports.md#project-skill-outcomes))
-  needs a faithful record of what the agent had and used.
-
-## Related
-
-- `engine/shared.js` — `HARNESS_USED_KINDS`, `HARNESS_USED_MAX_ENTRIES`,
-  `HARNESS_USED_MAX_FIELD_LEN`, `normalizeHarnessUsed()`, `groundHarnessUsed()`,
-  `filterProjectHarnessDirsForWorkdir()` (the sub-project/workdir clip)
-- `engine/queries.js` — `buildHarnessPropagatedManifest()`,
-  `getUserHarnesses()`, `getProjectHarnesses()`
-- `engine/lifecycle.js` — `resolveHarnessPropagated()` + the grounding
-  cross-check wired into `runPostCompletionHooks`
-- `docs/completion-reports.md` — the `harnessUsed` completion-report field
-- `docs/project-skills.md` — project-local skill/command discovery that feeds
-  the project-scope harness
-- `docs/workspace-manifests.md` — per-agent `allowed_tools` / `allowed_repos`
-  scoping that bounds the harness surface
-- `playbooks/shared-rules.md` — the per-task self-report instruction

package/docs/project-skills.md

@@ -1,193 +0,0 @@
-# Project skill discovery & intent vocabulary
-
-W-mq1cczi90006b21f (follow-on to PR #82, W-mq16xtdx001a347e).
-
-Minions' project-local **skill discovery layer** surfaces purpose-built tooling that a project ships (`.claude/skills/`, `.claude/commands/`, slash-command mentions in `CLAUDE.md` / `.github/copilot-instructions.md`) so dispatched agents steer toward the right skill instead of reinventing the flow from first principles.
-
-This document is the contract every playbook author and project teammate needs to know.
-
-## Where the code lives
-
-| File | Role |
-|---|---|
-| `engine/discover-project-skills.js` | Bounded filesystem walk + classification heuristic. The crash-safe primitive. |
-| `engine/playbook-intents.js` | Single source of truth for the playbook → intent set mapping. |
-| `engine/playbook.js` | Calls discovery + filter at render time, injects `{{project_skills_block}}` into the rendered prompt. |
-
-## What gets discovered
-
-Per project worktree, the discovery walk visits:
-
-- `<projectRoot>/.claude/skills/*/SKILL.md` — top-level skill packs.
-- `<projectRoot>/.claude/commands/*.md` — top-level slash-commands.
-- `<projectRoot>/<area>/.claude/skills/*/SKILL.md` — **nested per-area skills** (one level deep). This is how OCM / loop / officemobile organize their skills in a monorepo.
-- `<projectRoot>/<area>/.claude/commands/*.md` — same, for nested commands.
-- `<projectRoot>/.github/copilot-instructions.md` — slash-command mentions (top 32 KB).
-- `<projectRoot>/CLAUDE.md` — slash-command mentions (top 32 KB).
-
-Each discovery entry has shape:
-
-```js
-{
-  kind: 'skill' | 'command' | 'slash-command',
-  name: string,                   // e.g. "code-reviewer" or "/review-swarm"
-  path: string,                   // relative to projectRoot
-  oneLineDescription: string,     // ≤200 chars
-  intents: string[]               // closed enum, see below
-}
-```
-
-The walk is **cheap and bounded** — preserve every guardrail in
-`engine/discover-project-skills.js`:
-
-- ≤ 50 files per surface
-- 8 KB per skill / 32 KB per docs file
-- 250 ms walltime budget — bails rather than blocks dispatch
-- ≤ 50 nested areas probed
-- Missing worktree / unreadable → `[]` (never throws)
-
-## Monorepo sub-project scoping
-
-P-f52d81ba. In a monorepo, a dispatch usually touches one sub-project (`ocm/`,
-`loop/`, `officemobile/`, …) even though discovery walks every sub-project's
-`.claude/skills`. Scoping surfaces that sub-project's skills **first** without hiding
-the rest, so an `ocm/`-focused agent isn't forced to scroll past `loop/` tooling
-to find the relevant pack.
-
-**Changed-path → sub-project detection.** `detectDominantSubproject({ projectPath,
-changedPaths })` (engine/discover-project-skills.js) counts the changed paths
-per first-level directory, keyed on the POSIX first segment. It reuses
-`_listAreas` for the authoritative set of valid sub-projects, so a stray first segment
-that isn't a real top-level dir never counts. It returns `{ subproject, matched,
-total, confident }`. The engine feeds it changed paths from:
-
-- **spawnAgent** (async, authoritative): `git diff --name-only <mainBranch>...HEAD`
-  in the current dispatch's worktree — never a parent/follow-up's stale diff.
-- **renderProjectWorkItemPromptForAgent** (`_deriveDominantSubprojectSync`, build-time
-  fallback with no git access): the work item's `references[*].path`.
-
-**Dominant-sub-project plurality threshold.** `detectDominantSubproject` only reports a sub-project
-as `confident` when the top sub-project holds **≥ 60%** of the sub-project-matched files **and**
-**≥ 2** files (`dominantSubprojectMinRatio` / `dominantSubprojectMinFiles` in `DEFAULTS`,
-overridable via `opts`). Ties break alphabetically for determinism. An empty,
-mixed, or no-known-sub-project diff returns `{ subproject: null, confident: false }` →
-flat discovery (today's global name-sort). This is deliberately conservative:
-a weakly-dominant or split diff falls back to flat surfacing rather than
-mis-scoping to the wrong sub-project.
-
-**Explicit `meta.workdir` wins over auto-detection.** When the operator declares
-`meta.workdir` on the work item, the effective sub-project is its first path segment —
-no diff work is done. Auto-detection only runs when `meta.workdir` is absent.
-The async git-diff-derived sub-project (threaded into the shared-branch re-render via
-`options.dominantSubproject`) overrides the sync `references`-derived guess.
-
-**Prioritized, not exclusive, surfacing.** The effective sub-project is threaded through
-`playbook.js` as `scopeSubproject` into `discoverProjectSkillsWithDiagnostics`. When
-set, entries under `<scopeSubproject>/` lead the list (name-sorted within the group),
-then root-level entries, then other-sub-project entries. **Discovery still walks
-everything — no skills are dropped; only ordering changes.** An empty/unset
-`scopeSubproject` reduces byte-for-byte to the historical global name-then-path sort.
-
-**Configurable per-surface cap.** `ENGINE_DEFAULTS.projectSkillMaxFilesPerSurface`
-(default **200**) caps how many skill packs / command files are read per surface
-(root `.claude/skills`, each `<area>/.claude/skills`, …). `playbook.js` threads
-it into the discovery `opts`; when no override is supplied the module falls back
-to its own `DEFAULTS.maxFilesPerSurface` (50). It's raised well above the
-fallback so large monorepo sub-projects (e.g. an `ocm/.claude/skills` with ~80 packs)
-don't silently drop the most-relevant skills. Entries are alphabetically sorted
-**before** the cap is applied, so the surviving subset is deterministic across
-runs and OSes rather than FS-readdir-order-dependent.
-
-**Truncation diagnostics.** `discoverProjectSkillsWithDiagnostics` returns
-`{ entries, truncations }` where each truncation is `{ surface, dir, scanned,
-total }` — recorded when a surface's `total` file count exceeds `scanned`
-(i.e. the cap dropped entries). `playbook.js` logs a `warn` when any surface
-truncates and stashes the diagnostics so `spawnAgent` can persist the detected
-sub-project (`_dominantSubproject`) and truncations (`_skillDiscoveryTruncations`) onto the
-dispatch record for later grounding/observability. Overflow is thus **observable**
-instead of silent.
-
-## The intent vocabulary (CLOSED)
-
-| Intent | What belongs here |
-|---|---|
-| `review` | code review, PR review, swarm review (`code-reviewer`, `/review-swarm`, `/code-review`, etc.) |
-| `build` | scaffold, generate, bump, migrate, codemod, refactor (`bump-fmf-android`, `workspace`, `vhd`, etc.) |
-| `fix` | debug, triage, repro, regression, flake-killing (`triage-flake`, `cover-pr` for missing tests on PR…) |
-| `test` | author tests, increase coverage, validate (`integration-tests`, `run-tests`, `qa-validate`) |
-| `plan` | PRD authoring, ADR, design-doc, decompose (`substitute-scheduler-template-vars`, `decompose`) |
-| `research` | investigate, gather-impact, telemetry-query, audit (`gather-impact`, `audit-deprecated`) |
-| `deploy` | release, publish, buddy-build, rollout, ship (`buddy-build`, `track-pr`) |
-| `observability` | telemetry, logs, kusto, monitoring, metrics dashboards (`kusto-telemetry-lmf-quality-report`, `weekly-repo-summary`) |
-| `meta` | meta-tooling about the skill system itself. **Do NOT use as a catch-all** — empty `intents: []` is the honest signal when the heuristic doesn't fire. |
-
-### How intents are assigned
-
-For each discovered entry, `classifyIntents(...)` does:
-
-1. **Honor explicit author intent first.** A skill's `SKILL.md` frontmatter may declare `intents:` (or `tags:` / `intent:`) — only values that match the closed vocabulary above are accepted. Example:
-   ```yaml
-   ---
-   name: bump-fmf-android
-   description: Bump the FMF SDK version pin in OCM Android
-   intents: [build, deploy]
-   ---
-   ```
-2. **Fall back to keyword heuristics.** The skill's `name`, frontmatter `description`, first heading, and filename are matched against the per-intent keyword regexes in `INTENT_KEYWORDS` (engine/discover-project-skills.js). A skill matching multiple regexes carries multiple intents.
-3. **Empty intents are honest.** Zero matches → `intents: []`. The entry is still discovered and returned, but no intent-filtered playbook will surface it. NEVER default to `meta` just to satisfy the field.
-
-### Slash-commands scraped from docs
-
-For `/foo` mentions in `CLAUDE.md` / `.github/copilot-instructions.md`, the discovery layer is more conservative: it only surfaces slash-commands whose **name itself** matches at least one intent keyword. This keeps doc-scrape noise out of every prompt (a doc may name 50 `/foo` commands; we don't want to dump them all into an `implement` prompt).
-
-## The playbook → intent map
-
-Defined in `engine/playbook-intents.js`. The default mapping at time of writing:
-
-| Playbook | Intents surfaced |
-|---|---|
-| `review` | `['review']` |
-| `fix` | `['fix', 'test', 'review']` |
-| `implement` / `implement-shared` | `['build', 'test', 'research']` |
-| `plan` / `plan-to-prd` / `decompose` | `['plan', 'research']` |
-| `docs` | `['research']` |
-| `verify` | `['test', 'review']` |
-| `build-and-test` | `['build', 'test']` |
-| `test` / `qa-validate` | `['test']` |
-| `explore` | `['research']` |
-| (all others) | `[]` — no block rendered |
-
-When a playbook's intent set is empty (or maps to none), the `{{project_skills_block}}` template variable resolves to the empty string and the splice fence collapses cleanly (no stray header, no padding).
-
-The `followup-dispatch` template **inherits** its parent dispatch's intent set via `vars.parent_dispatch_type` — there's no row in the map for it.
-
-## Adding a new playbook
-
-1. Add a row to `PLAYBOOK_INTENTS` in `engine/playbook-intents.js` mapping your playbook name to the intent set it should surface.
-2. Splice the conditional template fence into your playbook markdown at the position where the agent should see purpose-built tooling — typically between the task-intake step and the first "actually do the work" step:
-   ```md
-   {{#project_skills_block}}
-   {{project_skills_block}}
-
-   {{/project_skills_block}}
-   ```
-3. If the playbook should opt out for some dispatches, the dispatcher can set `meta.skipProjectSkills: true` (or the PR-82 alias `meta.skipProjectReviewSkills: true`) on the work item.
-
-## Adding a new intent
-
-1. Add a regex to `INTENT_KEYWORDS` in `engine/discover-project-skills.js`. Use `\b` word boundaries.
-2. Add the value to `INTENT_VOCABULARY` so explicit frontmatter `intents:` entries with the new name are accepted.
-3. Add a row to the table above, with a one-line description of what belongs.
-4. Update one or more playbook entries in `engine/playbook-intents.js` to include the new intent.
-
-Keep the vocabulary tight — every additional intent is noise risk in every prompt that surfaces it.
-
-## Completion-report contract
-
-When an agent acts on a discovered skill, record the outcome in the completion report's `meta.skill` block. See [docs/completion-reports.md](completion-reports.md#project-skill-outcomes) for the full schema. The legacy `meta.review.skill*` fields (PR #82) remain accepted as aliases — new code should prefer `meta.skill.*`.
-
-## Tests
-
-- `test/unit/discover-project-skills.test.js` — discovery + classification + intent filtering + render + per-playbook splice coverage.
-
-When you change discovery, classification, or the playbook→intent map, extend or update this test file.