feat(batch-bug-shepherd): operator visibility + fold-in invariant

PRINCIPLES.md

@@ -0,0 +1,105 @@
+# APM Principles
+
+The hard contract APM is held to. Every PR, every release, every
+roadmap call cites these principles. The triage panel, the review
+panel, and the batch-bug-shepherd Phase 1.5 strategic-alignment
+gate cite them by number when accepting or rejecting work.
+
+MANIFESTO = values. PRD = product pitch (currently framed at native
+platform owners). **This file = the rejection contract.** When a
+principle here conflicts with a feature request, the principle wins
+by default and shifts only via an explicit, written trade-off in
+the same PR.
+
+## P1 -- No invented primitive frontmatter
+
+APM emits to canonical schemas defined by upstream ecosystems:
+agentskills.io / Anthropic Claude Skills, GitHub Copilot, Cursor,
+Windsurf, Codex, Gemini, OpenCode. We do not invent `apm-*`
+frontmatter keys, top-level fields, or hidden attributes that
+downstream consumers must learn to honor APM-ness.
+
+The primitive on disk must be readable, valid, and useful in the
+consuming harness with zero APM-specific tooling.
+
+Rejection example: "Add an `apm-priority` frontmatter key so
+skills can self-rank in dispatch." NO. Dispatch ranking is the
+harness's problem, not a schema mutation.
+
+## P2 -- Multi-harness with traction gating
+
+APM ships to every harness with demonstrable user traction. Today:
+Copilot, Claude Code, Cursor, Windsurf, Codex, Gemini, OpenCode.
+Adding a new harness requires evidence: published download / install
+counts, named enterprise users, or a public ranking that places it
+in the top tier of agent runtimes.
+
+We do not chase the long tail. A harness with zero documented users
+does not get a target adapter, period.
+
+Rejection example: "Add a target for <obscure-harness>." NO unless
+there is a citable traction number.
+
+## P3 -- Vendor neutral by construction
+
+No primitive APM produces or installs may bake in a preferred LLM
+vendor, a preferred runtime, or a "works best with X" recommendation
+in shipped output. README, docs, and CLI output must remain
+runtime-agnostic where the surface is general.
+
+Per-target adapters are allowed (they ARE the multi-harness promise);
+preferential framing inside neutral surfaces is not.
+
+Rejection example: "Default `apm run` to invoke Claude when no
+runtime is configured." NO. Surface the missing config and require
+an explicit choice.
+
+## P4 -- UX is the floor, not a trade
+
+APM's adoption funnel runs through `apm init`, `apm install`, and
+`apm run`. No bug fix, hardening, security patch, or refactor lands
+if it makes those commands harder, slower, more verbose, or more
+confusing for a new user. The bug stays open until a UX-preserving
+fix exists.
+
+This is asymmetric on purpose: a bug bites the affected user once;
+a bad install experience loses every future user silently.
+
+Rejection example: "Fix #X by adding a required `--target` flag on
+`apm install`." NO. Find a fix that preserves target inference, or
+leave the issue open.
+
+## P5 -- Portability over vendor lock-in
+
+A primitive authored once must execute across every supported
+harness without modification. Lock-in of any flavor -- vendor,
+runtime, host -- is a regression.
+
+## P6 -- Reliability over magic
+
+Behavior must be predictable, auditable, and explainable in plain
+English. No silent normalization, no opaque heuristics, no "the
+agent decided." Every transformation has a name and a line in the
+changelog.
+
+## P7 -- Community over feature count
+
+External-contributor PRs and issues triage before internal
+nice-to-haves. A contributor lost is worse than a feature delayed.
+Surface every external interaction at the top of the queue.
+
+## How this file is used
+
+- `apm-ceo` cites by number in arbitration prose.
+- `batch-bug-shepherd` Phase 1.5 spawns one ceo subagent per
+  triaged-LEGIT row, which returns a verdict + cited principle.
+- `apm-triage-panel` CEO arbiter cites a principle on every
+  `decline-with-reason` rubric outcome.
+- `apm-review-panel` CEO synthesizer cites a principle when
+  surfacing strategic implications in arbitration.
+
+Any addition to this file requires the apm-ceo persona to ratify
+and ships in a PR that updates MANIFESTO.md cross-refs in the same
+commit. Removal of a principle is a breaking strategic change --
+requires CHANGELOG entry, migration line, and explicit `BREAKING:`
+prefix.

packages/batch-bug-shepherd/.apm/prompts/batch-bug-shepherd.prompt.md

@@ -43,15 +43,36 @@ Targets for this run: **${input:targets}**
    plan.md). If `sweep-all` produced more than 20 candidates, ASK for
    confirmation; otherwise proceed.
 
+   Then RENDER the progress mermaid diagram per the skill's
+   `assets/progress-diagram.md` -- every phase styled `pending`,
+   with the candidate count `N` substituted into the P0/P1 labels.
+   Print the live (empty) ground-truth table directly below it.
+   This anchors the operator's view for the rest of the run.
+
 4. INITIALIZE the ground-truth table in plan.md using the
    ground-truth-table asset shipped with the skill. One row per
    candidate. Status `pending-triage`.
 
-5. EXECUTE the skill phases in order. For each phase boundary,
-   reload the ground-truth table before spawning the next wave.
+5. EXECUTE the skill phases in order. For each phase boundary:
+   - reload the ground-truth table from plan.md (B4 PLAN MEMENTO),
+   - re-render the progress mermaid with the just-entered phase
+     styled `active` and earlier phases `done` / `blocked` /
+     `skipped` per the color contract,
+   - print the live ground-truth table beneath the diagram,
+   - and (for every fan-out wave: Phase 1, 3a, 3b, 4) print the
+     dispatch table mapping each subagent_id to its target BEFORE
+     spawning.
+
+   These renders are mandatory, not cosmetic -- they are the
+   operator's only real-time signal that the saga is alive and
+   what it's working on.
 
 6. RENDER the final report from the final-report-template asset
-   shipped with the skill at session end.
+   shipped with the skill at session end. Use clickable GitHub
+   issue / PR / author links so the operator can navigate without
+   copy-paste. Re-render the progress mermaid one last time with
+   every phase `done` (or `blocked` where the human-escalation
+   queue is non-empty).
 
 ## Delegation