plan-stage: add /pharn-plan product command and Approved-input gate

[PrzemekGalarowicz]

Summary

• Adds the approved build-loop plan for plan-stage — the increment that introduces the product command /pharn-plan (second stage of the product spine after /pharn-spec).
• Scopes a new floor checker .dev/floor/check-spec-approved.mjs that shells to check-spec.mjs and asserts state === "Approved", so planning only proceeds from approved, un-drifted intent.
• /pharn-plan will emit features/<name>/PLAN.md carrying spec_id + spec_content_hash forward; plan content remains advisory.

Test plan

• Human review of .dev/features/plan-stage/PLAN.md (GATE 1 already approved 2026-06-30)
• /pharn-dev-build on this plan (follow-up increment) — implement pharn-plan.md, check-spec-approved.mjs, and tests
• npm test green after build
• node .dev/floor/validate.mjs . still reports floor capability count unchanged (1)

Made with Cursor

Summary by CodeRabbit

• New Features

  • Added a new planning stage with clearer end-to-end flow for approved specifications through planning, review, verification, regression, and shipping.
  • Introduced a stricter approval check before planning can proceed, helping prevent work from starting on incomplete or changed specs.

• Bug Fixes

  • Improved reporting so planning and verification results are more consistent and easier to interpret.
  • Added regression tracking to confirm no new breakage was introduced during the plan-stage run.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds the /pharn-plan command as the plan stage of the product pipeline. A new floor gate script check-spec-approved.mjs delegates to check-spec.mjs and then asserts the SPEC's state == "Approved" before allowing plan generation. The command writes features/<name>/PLAN.md carrying spec_id and spec_content_hash forward. Accompanying plan-stage process artifacts (PLAN, GRILL, REVIEW, REGRESSION, VERIFY, SHIP) are also added.

Changes

plan-stage: Approved-input gate, command spec, and process artifacts

Layer / File(s)	Summary
check-spec-approved.mjs gate and tests .dev/floor/check-spec-approved.mjs, .dev/floor/check-spec-approved.test.mjs	New Node.js CLI that shells to check-spec.mjs, extracts frontmatter state, and fails closed on non-Approved or drifted specs. Black-box test suite covers Draft refusal, correct/wrong pin, malformed input, missing sections, injection-resistance, and no-args usage.
/pharn-plan command definition .claude/commands/pharn-plan.md	Defines the four-step command: resolve feature name and set writes scope, read live SPEC.md, run the Approved-input gate (halt on failure), generate advisory plan body, and write PLAN.md with spec_id and spec_content_hash carried forward. Includes guarantee/trust/determinism audit sections.
Plan-stage process artifacts .dev/features/plan-stage/PLAN.md, .dev/features/plan-stage/GRILL.md, .dev/features/plan-stage/REVIEW.md, .dev/features/plan-stage/REGRESSION.md, .dev/features/plan-stage/VERIFY.md, .dev/features/plan-stage/SHIP.md, .dev/features/plan-stage/regression-report.json, .dev/features/plan-stage/verify-report.json	PLAN.md records the stage contracts and eval cases; GRILL.md records 5 advisory findings (0 blocking); REVIEW.md records GREEN floor-gate verdict; REGRESSION.md and regression-report.json record no-regressions; VERIFY.md and verify-report.json record PASS; SHIP.md records the roll-up chain and what landed at GATE 2.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• pharn-dev/pharn-oss#8: Introduces /pharn-spec, which produces the features/<name>/SPEC.md and spec_content_hash that /pharn-plan's Approved-input gate directly reads and validates.
• pharn-dev/pharn-oss#9: Adds the /grill command stage, which produces the same GRILL.md advisory-findings format used in this PR's plan-stage/GRILL.md.

Poem

🐇 A spec must be Approved, the hash must align,
Only then does the plan get to shine.
The gate checks the state, the floor holds it true,
Advisory prose follows after — that's new!
No drifting allowed in this pipeline of mine. ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: adding /pharn-plan and the Approved-input gate.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch plan-stage

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.claude/commands/pharn-plan.md:
- Around line 84-120: The plan flow currently rereads SPEC.md after the approval
gate, which can let Step 4 copy spec_id and spec_content_hash from a different
SPEC state than the one that passed Step 2. Update pharn-plan so it freezes the
SPEC bytes once before gating, runs check-spec-approved.mjs against that frozen
snapshot, and then carries spec_id and spec_content_hash forward from the same
snapshot when writing PLAN.md. Use the Step 2 gate and Step 4 frontmatter copy
logic in pharn-plan as the place to fix this.

In @.dev/features/plan-stage/SHIP.md:
- Around line 30-38: Keep SHIP.md as a pointer-only document and remove the
restated advisory details currently embedded in the advisory pointers section.
Update the SHIP.md content around the REVIEW.md and GRILL.md references so it
simply directs readers to those source docs, preserving the unique identifiers
like REVIEW.md, GRILL.md, and the “Advisory pointers” section without
duplicating their findings.

In @.dev/floor/check-spec-approved.mjs:
- Around line 81-105: The validation flow in check-spec-approved.mjs re-reads
specPath after check-spec.mjs has already validated it, so a concurrent edit can
change the file between checks and make readState pass on different bytes than
the ones that were verified. Fix this by freezing the SPEC contents once in the
main flow and using that same snapshot for both the check-spec.mjs invocation
and the later state validation, updating the logic around spawnSync,
readFileSync, and readState so they all operate on the same in-memory text
rather than reopening specPath.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 1ef0469c-4ff5-489b-a3eb-ebd72f002285

📥 Commits

Reviewing files that changed from the base of the PR and between 2e773b9 and 1e69e5f.

📒 Files selected for processing (11)

• .claude/commands/pharn-plan.md
• .dev/features/plan-stage/GRILL.md
• .dev/features/plan-stage/PLAN.md
• .dev/features/plan-stage/REGRESSION.md
• .dev/features/plan-stage/REVIEW.md
• .dev/features/plan-stage/SHIP.md
• .dev/features/plan-stage/VERIFY.md
• .dev/features/plan-stage/regression-report.json
• .dev/features/plan-stage/verify-report.json
• .dev/floor/check-spec-approved.mjs
• .dev/floor/check-spec-approved.test.mjs