Mstar Plan Artifacts

Load order

Before first Read of this skill: Read mstar-harness-core (SKILL.md), and mstar-plan-conventions when path symbols matter. Git branch / worktree / QC checkout → mstar-branch-worktree. On conflict, mstar-harness-core wins.

Scope (plan directory artifacts)

| Topic | See | |-------|-----| | Main plan, review bundle naming, durable summaries, QC waves, residual and plan index order | references/plan-files-and-reports.md | | Plan template (Global Constraints, Interfaces) | templates/plan.main.md | | knowledge / iterations / specs boundaries and indexes | references/knowledge-and-designs.md | | Done row compaction Profile A/B | references/done-compaction.md | | status.json, residual severity, lifecycle, jq | references/status-and-residuals.md | | Empty-repo status.json / notes.json / Profile B plans-done.json templates | templates/status.empty.json, templates/notes.empty.json, templates/plans-done.empty.json (templates/README.md) | | Tech-debt rollup (read-only) | engine techDebtRollup import (no CLI form; see references/status-and-residuals.md) |

Out of scope: branch and QC/QA checkout alignment → mstar-branch-worktree; leaf QC checklist and verdict → mstar-roles/references/qc-specialist/; PM QC orchestration → mstar-review-qc; {HARNESS_DIR} discovery and init → mstar-plan-conventions.

status.json and open residual (summary)

• {HARNESS_DIR}/status.json: plans[] row status + root residual_findings[] (open list SSOT).
• Canonical: register new findings only at root residual_findings; metadata.residual_findings is legacy read-only — do not dual-write.

> Engine check (when available): run mstar status validate (or import { validateStatus } from "@mstar-harness/engine" in a host hook). On fail -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.

• Lifecycle: open → verified close → archived/residuals/.json; machine severity enum in reference.

> Engine check (when available): run mstar status archive-residuals (or import { archiveResiduals } from "@mstar-harness/engine" in a host hook). On fail -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.

• Findings cleanup: Assignment Findings cleanup: zero-residual | allow-residual (+ optional metadata.findings_cleanup); iteration Phase 2 defaults to zero-residual → references/status-and-residuals.md (“Findings cleanup modes”).

> Engine check (when available): import findingsCleanupGate from @mstar-harness/engine in a host hook to enforce the cleanup mode above. On fail -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.

• notes.json, optional tech_debt_summary (rollup view; compute via engine techDebtRollup — references/status-and-residuals.md).
• Iteration Phase 2 leases (metadata.control_worktree_path, plans[].execution_lease, metadata.integration_merge_lease): claim-before-InProgress, resume vs steal, orphan recovery → references/status-and-residuals.md (“Iteration execution leases”).

> Engine check (when available): run mstar lease verify (or import { validateExecutionLease } from "@mstar-harness/engine" in a host hook — validateIntegrationMergeLease is import-only; no CLI form yet). On fail -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.

Field semantics, severity mapping, findings cleanup modes, archive flow, and jq examples → references/status-and-residuals.md.

Templates (this skill): templates/status.empty.json, templates/notes.empty.json — copy into {HARNESS_DIR}/ (templates/README.md).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: btspoony
• Source: btspoony/mstar-harness
• License: MIT

Install and usage instructions live in the source repository linked above.