PHAX: A plan's own approval is never ground change

[lbdremy]

PHAX Run Review Handoff

Generated by PHAX.

Run Review Handoff

Run summary

• Short Name: a-plan-s-own-approval-is-never-ground-change
• Run ID: a-plan-s-own-approval-is-never-ground-change-1791288092809
• Base Branch: phax/a-plan-s-own-approval-is-never-ground-change
• Final Phase Branch: phax/a-plan-s-own-approval-is-never-ground-change--phase-02
• Gate Profile: standard
• Phases: 2/2 passed
• See final-report.md for security details and entry/resume instructions.

Global File Reconciliation

Run: phax.a-plan-s-own-approval-is-never-ground-change

File	Planned in	Touched in	Status	Notes
NEXT_STEPS.md	phase-02	phase-02	matched	—
README.md	phase-02	phase-02	matched	—
src/app/planStaleness.ts	phase-01	phase-01	matched	—
src/domain/artifact/lineage.ts	phase-01	phase-01	matched	—
tests/integration/approvalRecordGround.test.ts	phase-01	phase-01	matched	—
tests/unit/artifact/lineage.test.ts	phase-01	phase-01	matched	—

Global unplanned changes

None.

Global missing planned changes

None.

Global review attention points

No attention points.

Deviations not explained in any handoff

None.

Plan compliance review

Plan-compliance review

Verdict

conformant — both phases delivered what the plan specified, with no file deviations.

Per-phase findings

phase-01 — Exclude the plan's own path and record from ground change

• objective: ComputeStalenessInput.planPath (required) exists in src/domain/artifact/lineage.ts. computeStaleness derives the record path via approvalRecordPathFor and excludes the plan's own path plus the record (null-safe for loose plans). src/app/planStaleness.ts passes planPath to computeStaleness.
• excluded-scope: Respected. No edits to the approve transition, the record schema, the CLI files or run.ts.
• files: All four planned files were touched and no others. No deviation.
• tests: The handoff reports unit cases (a)–(g) and two integration tests as planned. Existing tests are unchanged and green. I took this from the handoff and did not re-run the suite.
• boundaries: The producer and consumer contracts hold. The computeStalenessForPlan signature is unchanged.
• commit: Not independently inspected. The recent history shows fix(staleness): a plan's own approval is never ground change, which matches the planned subject.
• handoff: Covers all the required content.

phase-02 — Retire the known issue and the backlog items

• objective: The README bullet is gone. NEXT_STEPS.md has the Small follow-ups item ticked with a "Fixed" note, the Road to 1.0 item ticked and reworded, the intro count updated, and approval-ground removed from the drafts line.
• excluded-scope: Respected. No skill, CLI-doc or archived-artifact edits.
• files: Only README.md and NEXT_STEPS.md were touched. No deviation.
• tests: Docs only, none promised.
• boundaries: Not applicable.
• commit: The recent history shows docs: a plan is no longer stale at its own approval, which matches the plan.
• handoff: Covers the required content, including the skill re-check, which found no advice to remove.

Unplanned-change ledger

None. The reconciliation shows all six files as matched.

Unmet-promise ledger

None found.

Attention points

• NEXT_STEPS.md still mentions approval-ground in historical text (lines ~165–187). This is consistent with "keep the item's history text".
• Line 184 of NEXT_STEPS.md still describes own-approval-ground as "Draft" in the kept history text. The plan is now complete, so this is a minor staleness in prose the plan said to keep.

Phase details

phase-01 — Exclude the plan's own path and record from ground change

File reconciliation

PHAX File Reconciliation

Planned to edit

• src/domain/artifact/lineage.ts
• src/app/planStaleness.ts
• tests/unit/artifact/lineage.test.ts
• tests/integration/approvalRecordGround.test.ts

Summary: No deviations from the planned file lists.

Phase handoff

What was delivered

• ComputeStalenessInput in src/domain/artifact/lineage.ts has a new required planPath: string (repo-relative path of the plan being judged).
• computeStaleness removes the plan's own path and approvalRecordPathFor("plan", planPath) (when not null) from changedFilesSinceBaseline before the footprint intersection. ground-changed evidence lists only the remaining files.
• computeStalenessForPlan in src/app/planStaleness.ts passes planPath in all three computeStaleness calls. Its signature and error channel are unchanged.
• Unit table in tests/unit/artifact/lineage.test.ts (describe "computeStaleness: a plan's own approval is never ground change"), cases (a)–(g) as planned. Every existing computeStaleness call now passes planPath: JUDGED_PLAN.
• Integration describe "A plan's own approval is never ground change" in tests/integration/approvalRecordGround.test.ts, with two tests: fresh right after approve; stale with ground-changed [src/feature/pi.ts] after a later commit.

Key decisions and why

• The exclusion rule lives in the domain and derives the record path itself, so a caller cannot pass the wrong pair of paths.
• self-changed and spec-changed logic and evidence order are unchanged.
• The plan's own JSON sidecar and other artifacts' record files still count as ground evidence (cases c and d).
• A loose plan (approvalRecordPathFor returns null) excludes only its own path.

Exact locations (file paths and exported names)

• src/domain/artifact/lineage.ts: ComputeStalenessInput.planPath, computeStaleness
• src/domain/artifact/approvalRecordFile.ts: approvalRecordPathFor (imported, unchanged)
• src/app/planStaleness.ts: computeStalenessForPlan (signature unchanged)

What the next phase needs to know

• No deviation from the planned file lists. src/cli/commands/run.ts, computePlanStaleness, the CLI docs, the record schema and STALENESS_REASONS were not touched.
• The three existing approvalRecordGround tests stay green unchanged.
• Integration test 1 does not capture a baseline, because its expected verdict (fresh) carries none.
• Unit case (f) and integration test 2 also failed before the fix: the own path used to appear in ground-changed.
• The full gate list passed: format, typecheck, test:type, lint, format:check, test (5154), knip, audit:architecture, gen:model-catalog --check, build, site:build, deno:smoke, deno:smoke-binary.
• Phase-02 is docs only: the README known-issue bullet and the NEXT_STEPS.md items can now be retired.

---

phase-02 — Retire the known issue and the backlog items

File reconciliation

PHAX File Reconciliation

Planned to edit

• README.md
• NEXT_STEPS.md

Summary: No deviations from the planned file lists.

Phase handoff

What was delivered

• README.md: the known-issue bullet "A plan is stale right after its approval" no longer exists.
• NEXT_STEPS.md, Small follow-ups: the approval-staleness item is ticked and carries a "Fixed:" note (approval-record-files, own-approval-ground; approval-ground abandoned).
• NEXT_STEPS.md, Road to 1.0.0: the happy-path item is ticked and reworded to "Both known happy-path defects are fixed" (slug burn PR PHAX: Preflight before naming #112, approval-commit staleness).
• NEXT_STEPS.md, status line: approval-ground removed from the drafts waiting on the author.

Key decisions and why

• The Road to 1.0.0 intro count now reads "two remain once the happy-path defect is closed". The happy-path item was one of the three remaining blockers.
• New prose refers to plans and specs by slug, never by stamp.

Exact locations (file paths and exported names)

• README.md — troubleshooting / known-issues list
• NEXT_STEPS.md — status line near the top, Road to 1.0.0 section, Small follow-ups section

What the next phase needs to know

• This is the last phase of the plan.
• The skill re-check found no advice to leave approvals.json or a record file out of a plan's lists. phax-cli only describes record files. No skill file was edited.
• No deviation from the planned file lists (README.md and NEXT_STEPS.md only).
• Code, CLI docs (phax.usage.kdl, docs/cli/reference.md, src/cli/cliDocs.ts) and archived artifacts were not touched.