master-plan-patching

name	master-plan-patching
description	Protocol for the `master-plan-patcher` and `run-finalizer` agents. The per-project `<project>/PROJECT_MASTER.md` follows the Section 9 20-section template. Every successful run patches the relevant sections with cross-references to the run's artifacts.

Master plan patching

<project>/PROJECT_MASTER.md is the durable cross-run memory of the project. It follows the Section 9 20-section template (Executive summary → Deprecation & retirement plan + Appendices). Every successful run contributes to it; surfaced runs do not.

When to patch

Patching happens at run finalize, not earlier. The run-finalizer agent invokes the master-plan-patcher agent immediately before mcp__pp_harness__finalize_run(status="complete").

The daemon also calls applyMasterPlanPatch from inside finalize_run itself as a safety net so that if the agent path is skipped (e.g. an early aborted finalize that the user later flips to complete via direct DB edit), the master-plan still reflects the run.

Section mapping

Every artifact has a taxonomy_section (4.x). Each 4.x section maps to exactly one master-plan section. The canonical mapping lives in daemon/src/orchestrator/taxonomy.ts as the master_plan_section field on each TaxonomySection row — read it directly via mcp__pp_harness__list_taxonomy_sections. Do not maintain a parallel mapping in the plugin or anywhere else; the daemon validates every entry against MASTER_PLAN_SECTIONS so a typo would surface as a "not in MASTER_PLAN_SECTIONS — skipping" warning at finalize time.

Quick reference (current values; check the tool output for ground truth):

4.x	Master-plan section
4.1	2. Business and portfolio context
4.2	3. Stakeholders and users
4.3	6. Functional requirements
4.4	9. UX/UI/content design
4.5	10. Domain and data model
4.6	11. Architecture and technical strategy
4.7	12. Interfaces and contracts
4.8	13. Engineering standards and delivery model
4.9	14. Security, privacy, and compliance
4.10	15. Test and verification strategy
4.11	19. Launch, migration, and rollback plan
4.12	16. Operations and support model
4.13	Appendices
4.14	17. Team operating model and governance
4.15	Appendices
4.16	20. Deprecation and retirement plan

What the patcher writes

For each touched master-plan section, the patcher writes a small block:

### Run `<run_id>` — <one-line summary>

- Date: 2026-05-04
- Scope: <triage class>
- Artifacts:
  - `.harness/<run_id>/spec/attempt-1.md` (PRD)
  - `.harness/<run_id>/security/threat-model.md`
- Verdict: pass (cross-vendor)
- Decisions:
  - <ADR title or short bullet, if any>

The block is appended (kind: append) when the section has prior content; written to a placeholder section (kind: update) on first run.

How to call apply_master_plan_patch

{
  "run_id":       "run_xxx",
  "project_path": "/abs/path/to/project",
  "section":      "11. Architecture and technical strategy",
  "kind":         "append",
  "content_md":   "### Run run_xxx — added OAuth middleware\n\n- ..."
}

The daemon computes prev/new sha and writes a master_plan_patches row. Multiple patches per run are normal — one per touched section.

Surfaced runs

Surfaced runs (validator failed, missability failed, loop ceiling reached) do NOT patch the master plan. The daemon writes a surfaced_skip row to master_plan_patches for audit; the next run picks up where this one left off.

Best-of-N

Best-of-N runs only patch from the winner candidate's artifacts. Losers are archived under <run_id>/<stage>/losers/ but do not contribute to the master plan.

Idempotency

The daemon's update-master-plan PostToolUse hook fires after every finalize_run. It calls apply_master_plan_patch again with the same content. The patcher is idempotent: if the prior section content already includes the run-id block, no change is made.

Reading the current state of the master plan

mcp__pp_harness__master_plan_status(project_path) returns:

• which of the 20 sections are populated
• total bytes
• the Section 10 15-item completion checklist (each item pass/fail based on its mapped section's populated flag)

/pp:checklist and /pp:master invoke this and render the result.

Scaffolding on first run

If PROJECT_MASTER.md does not exist, the patcher calls mcp__pp_harness__ensure_master_plan(project_path) first. The daemon writes the 20-section template using the project basename as the title. Subsequent runs patch into the template.