PHAX: Plan lint by lbdremy · Pull Request #94 · lbdremy/phax

lbdremy · 2026-09-08T09:59:05Z

PHAX Run Review Handoff

Generated by PHAX.

Run Review Handoff

Run summary

Short Name: plan-lint
Run ID: plan-lint-1788858296696
Base Branch: phax/plan-lint
Final Phase Branch: phax/plan-lint--phase-06
Gate Profile: standard
Phases: 6/6 passed
See final-report.md for security details and entry/resume instructions.

Global File Reconciliation

Run: phax.plan-lint

File	Planned in	Touched in	Status	Notes
.claude/skills/phax-cli/SKILL.md	phase-06	—	missing	not touched in: phase-06
.claude/skills/phax-planning/SKILL.md	phase-06	—	missing	not touched in: phase-06
.claude/skills/phax-spec/SKILL.md	phase-06	—	missing	not touched in: phase-06
docs/cli/inventory.md	phase-04, phase-05	phase-04, phase-05	matched	—
docs/cli/reference.md	phase-04, phase-05	phase-04, phase-05	matched	—
docs/plan-extraction-model.md	phase-06	phase-06	renamed	renamed in: phase-06
examples/hello-world/plan.md	phase-06	phase-06	matched	—
phax.usage.kdl	phase-04, phase-05	phase-04, phase-05	matched	—
README.md	phase-04, phase-05, phase-06	phase-04, phase-05, phase-06	matched	—
src/app/extractPlan.ts	phase-05	phase-05	matched	—
src/app/lintPlan.ts	phase-03	phase-03	matched	—
src/app/loadOrExtractPlan.ts	phase-05	phase-05	matched	—
src/cli/cliDocs.ts	phase-04	phase-04	matched	—
src/cli/commands/extractPlan.ts	—	phase-05	deleted	deleted in: phase-05
src/cli/commands/orient.ts	phase-05	phase-05	matched	—
src/cli/commands/plans.ts	phase-04	phase-04	matched	—
src/cli/program.ts	phase-05	phase-05	matched	—
src/domain/plan/lint.ts	phase-01, phase-02, phase-03	phase-01, phase-02, phase-03	matched	—
src/domain/plan/lintRender.ts	phase-04	phase-04	matched	—
src/domain/plan/parsePlanMarkdown.ts	phase-01	phase-01	matched	—
tests/e2e/realFlow.test.ts	phase-05	phase-05	matched	—
tests/integration/cliProgram.test.ts	phase-05, phase-04 (optional)	phase-04, phase-05	matched	—
tests/integration/lintPlan.test.ts	phase-03	phase-03	matched	—
tests/integration/loadOrExtractPlan.test.ts	phase-05	phase-05	matched	—
tests/integration/run.test.ts	phase-05	phase-05	matched	—
tests/unit/cli/plans.test.ts	phase-04	phase-04	matched	—
tests/unit/parsePlanMarkdown.test.ts	phase-01	phase-01	matched	—
tests/unit/planLint.test.ts	phase-01, phase-02, phase-03	phase-01, phase-02, phase-03	matched	—
tests/unit/planLintRender.test.ts	phase-04	phase-04	matched	—

Global unplanned changes

src/cli/commands/extractPlan.ts (touched in: phase-05)

Global missing planned changes

.claude/skills/phax-cli/SKILL.md (planned in: phase-06)
.claude/skills/phax-planning/SKILL.md (planned in: phase-06)
.claude/skills/phax-spec/SKILL.md (planned in: phase-06)

Global review attention points

.claude/skills/phax-cli/SKILL.md (missing) — see phase-06/phase-handoff.md for details
.claude/skills/phax-planning/SKILL.md (missing) — see phase-06/phase-handoff.md for details
.claude/skills/phax-spec/SKILL.md (missing) — see phase-06/phase-handoff.md for details
docs/plan-extraction-model.md (renamed) — see phase-06/phase-handoff.md for details
src/cli/commands/extractPlan.ts (deleted) — see phase-05/phase-handoff.md for details

Deviations not explained in any handoff

None.

Plan compliance review

Plan-compliance review — phax.plan-lint

Verdict: conformant-with-deviations

Five of six phases (phase-01 through phase-05) match their plan sections closely: exported
names, message formats, boundary contracts, test coverage, and file lists all line up with
what was planned and with the global file reconciliation. Phase-06 delivered its README,
extraction-model doc rename, and hello-world example edits as planned, but its most
consequential deliverable — rewriting phax extract-plan references out of the three
shipped skills (phax-planning, phax-cli, phax-spec) — was not completed. The gap is
disclosed candidly in the phase's own handoff (blocked by write-permission denials under
.claude/skills/ for the entire session) and is corroborated by the global reconciliation,
which marks all three skill files "missing" for phase-06. This is a genuine, well-documented,
externally-caused shortfall rather than silent scope creep or a fabricated claim, which is why
the run rolls up to "conformant-with-deviations" rather than "divergent" — but the shortfall
is large enough (3 of 5 planned edits, the ones carrying the most detailed line-level
instructions) that phase-06 itself is scored "divergent" against its own plan section.

Note: this session's tooling had no shell/git access, so exact commit subject/body text for
each phase could not be independently diffed against git log. The findings below on the
commit dimension rely on the phase handoffs' self-reported commit content and the plan text;
nothing observed contradicts the planned commit messages except the phase-06 body's claim
(inherited from the plan's own commit-body template) that the three skills were "updated,"
which the files' unedited content and the reconciliation both refute.

Per-phase findings

phase-01 — Parser reports every structural error

objective: Delivered as specified. collectPlanStructureErrors, StructureError,
LintFinding, LintSeverity, LintCheck, and structureFindings all exist in
src/domain/plan/lint.ts and src/domain/plan/parsePlanMarkdown.ts with the signatures
the plan specified.
excluded-scope: Respected — no file-plan, commands, or models logic appears in this
phase's diff scope; finalizeExtractedPlan untouched.
files: Matched exactly (reconciliation: matched). Optional file
tests/unit/examplePlanDeterministic.test.ts correctly left untouched per the handoff.
tests: tests/unit/parsePlanMarkdown.test.ts has describe("collectPlanStructureErrors", ...)
and tests/unit/planLint.test.ts has describe("structureFindings", ...) with the
conforming-plan and closed-vocabulary cases the plan asked for.
boundaries: Respected — no consumer of extractPlanDeterministic needed changes.
commit: Handoff and plan text align on scope/wording; no independent git diff available
this session (see note above).
handoff: Covers exported names/signatures, the first-error byte-identity confirmation,
and states no file-list deviations. Meets the "Expected handoff content" bar.

phase-02 — File-plan rule over the known-existing set

objective: Delivered — plannedPaths and filePlanFindings exist in lint.ts with the
exact message formats specified (verified by reading tests/unit/planLint.test.ts, which
has one test per spec acceptance criterion: missing-edit-target, create-exists,
create-already-created, create+edit-same-phase, optional-files-never-checked, and the
create ∩ optional warning).
excluded-scope: Respected — no filesystem probing logic added.
files: Matched exactly (reconciliation: matched); no optional files needed.
tests: Present at the domain-unit-test layer as planned.
boundaries: Respected — pure domain code, no port dependency introduced.
commit: Aligns with plan text; not independently git-diffed this session.
handoff: Documents the known-map origin semantics and the reused message strings
verbatim, which is exactly what phase-03/04 needed.

phase-03 — Run-readiness rules and the lint use case

objective: Delivered — commandFindings, modelFindings, hasLintErrors in
lint.ts; lintPlan in src/app/lintPlan.ts returning LintReport. Spot-checked
tests/integration/lintPlan.test.ts, which uses makeFakeFileSystem and asserts the
FileSystem-only requirement pattern the plan called for.
excluded-scope: Respected — no CLI or rendering code introduced here.
files: Matched (reconciliation: matched); optional src/app/loadRouting.ts correctly
left untouched (handoff explains the built-in-defaults fallback makes it unnecessary).
tests: Both the domain-wrapper unit tests and the app integration tests are present,
matching "Test strategy."
boundaries: The critical constraint — lintPlan requires FileSystem only, no
Backend/Shell/Lock/Git — is asserted by name in the handoff and is structurally the
point of the integration test's fake-fs-only layer.
commit: Aligns with plan text; not independently git-diffed this session.
handoff: Covers the signature, requirement set, message formats, and the
structure/files/commands/models ordering explicitly.

phase-04 — `phax plans lint` command, rendering and JSON

objective: Delivered — renderLintReport in src/domain/plan/lintRender.ts,
runPlansLint registered on the plans parent in src/cli/commands/plans.ts, --json
and exit-code behavior as specified. Verified docs/cli/inventory.md gained the ### plans
section with the lint row, and tests/integration/cliProgram.test.ts asserts the
<plan> argument and --json option.
excluded-scope: Respected — no extract-plan removal or README prose changes bled into
this phase.
files: Matched (reconciliation: matched); the optional tests/integration/cliProgram.test.ts
touch is explicitly justified in the handoff ("that suite already inspects subcommand
trees").
tests: tests/unit/planLintRender.test.ts verified directly — covers the header count
variants (plural/singular), per-finding line format, and the plan-level dash-phase case,
matching the plan's acceptance list precisely.
boundaries: CLI → app boundary respected (runPlansLint calls only lintPlan); render
and exit-code derivation are domain functions, not inline CLI logic.
commit: Aligns with plan text; not independently git-diffed this session.
handoff: Documents the exact rendered format, JSON shape, and confirms the README
changed only within its generated markers, and flags that docs/cli/inventory.md still had
the stale extract-plan row for phase-05 to remove — a useful, accurate carry-forward note.

phase-05 — Remove extract-plan from code and generated docs

objective: Delivered — src/cli/commands/extractPlan.ts deleted, extractPlan/
ExtractPlanOptions/ExtractPlanResult/ExtractPlanError/buildExtractReport removed from
src/app/extractPlan.ts (verified the file now opens directly on extractPlanLlm's
supporting imports, no leftover wrapper). tests/integration/cliProgram.test.ts's
TOP_LEVEL_COMMANDS list has no extract-plan entry.
excluded-scope: Respected — no prose/skill edits landed in this phase (correctly
deferred to phase-06).
files: Matched (reconciliation: matched) across all listed create/edit/delete targets.
tests: The regression-guard suites named in "Test strategy"
(cliProgram.test.ts, loadOrExtractPlan.test.ts, the sealed/titles suites) are all
present and were the ones edited, per handoff.
boundaries: None crossed, as planned (a CLI→app edge removed, not modified).
commit: Plan calls for a feat(cli)!: breaking-change commit with a BREAKING CHANGE:
footer; handoff content is consistent with that framing. Not independently git-diffed this
session.
handoff: Confirms phax --usage no longer lists extract-plan, gives the final export
list, notes the pre-existing flaky test is unrelated, and confirms knip is clean.

phase-06 — Docs, skills and example follow the lint

objective: Partially delivered — divergent. README ("Write a plan" / new "Lint the
plan" section), the docs/extract-plan-model.md → docs/plan-extraction-model.md rename
with retitled content, and the examples/hello-world/plan.md note were all completed and
verified by direct read; they match the plan's described content closely (two-level
precedence chain, no CLI flag, phax plans lint pointer). However, the plan's core mandate
for the three shipped skills — precise line-level rewrites in
.claude/skills/phax-planning/SKILL.md (frontmatter description + lines 9, 13, 40, 85, 114,
188, 447), .claude/skills/phax-cli/SKILL.md:66, and .claude/skills/phax-spec/SKILL.md:19
— was not delivered at all. Direct reads of all three files this session confirm they
still say phax extract-plan verbatim in the exact locations the plan named (e.g.
phax-cli/SKILL.md:66 still reads "phax run extracts the plan inline; phax extract-plan
is the standalone step..."; phax-spec/SKILL.md:19's pipeline diagram still shows
phax-plan.json (extract-plan)). This is the majority of the phase's detailed-instructions
scope by line count and the two files (phax-cli, phax-spec) most likely to actively
steer an agent toward a command that phase-05 deleted.
excluded-scope: Respected for what was touched — no blog/vocabulary-review/archive
edits, matching the plan's exclusions.
files: The three skill files are a deviation from "Planned files to edit," and it is
justified in the handoff (permission denials under .claude/skills/ for the whole session,
both Edit and Bash-write attempts). The justification is credible and specific, but it does
not resolve the underlying gap — the plan's objective remains unmet, not merely delayed.
tests: No automated tests were planned for this phase (docs-only); none needed.
boundaries: N/A — documentation only, as planned.
commit: The plan's commit-body template states the commit updated "the phax-planning,
phax-cli and phax-spec skills" — per the reconciliation and this session's direct file
reads, that claim does not hold for the actual committed state. If the phase's commit body
was generated verbatim from the plan template (as is typical), it overstates what shipped;
this session had no git access to confirm the literal commit text (see the top-level note).
handoff: Explicit and honest about the deviation — the "What the next phase needs to
know" section names the exact three files, the exact edits still needed, and states plainly
this is "the actual open work of spec 33." It does not include the "Expected handoff
content" item the plan asked for (a grep proof that extract-plan no longer appears outside
the named exempt paths) — it cannot, since that grep would currently fail. This omission is
itself accurate reporting rather than a fabricated pass.

Unplanned-change ledger

None found. Every file touched across phase-01 through phase-06, per the global
reconciliation and this session's direct inspection, is either an exact match to a planned
file or an explicitly justified optional-file touch (phase-03's untouched loadRouting.ts,
phase-04's cliProgram.test.ts). No extra-touched or unplanned files are recorded in the
reconciliation table.

Unmet-promise ledger

phase-06: the three planned skill-file edits (.claude/skills/phax-planning/SKILL.md,
.claude/skills/phax-cli/SKILL.md, .claude/skills/phax-spec/SKILL.md) were never applied.
Confirmed directly: all three files still contain the exact pre-phase-06 extract-plan
wording at the plan-cited locations.
phase-06: the "Expected handoff content" grep proof (that extract-plan no longer
appears outside the named exempt paths) is missing from the handoff — correctly, since it
would fail today. A grep this session additionally turned up two more live (non-exempt,
non-archived) mentions the plan's exemption list doesn't cover: NEXT_STEPS.md:112 (a
retrospective description of this very run's plan, not an instruction — low risk) and
docs/plans/41-claude-protected-path-approval-hook-plan.md:13 (status: Stale, a
not-yet-run plan for a different, unrelated feature that instructs an agent to "Feed this
file to phax extract-plan" — stale advice that would fail if ever executed, but not part
of spec 33's declared scope).

Attention points

The open work is precisely scoped: apply phase-06's already-fully-specified skill edits
once a session with write access to .claude/skills/ is available. The plan text itself
(phase-06 "Detailed instructions") is a ready-made punch list.
Notably, docs/plans/41-claude-protected-path-approval-hook-plan.md (status Stale, not
part of this run) is a plan for exactly the capability that would have unblocked phase-06:
a scoped approval hook letting a phax agent edit declared Claude-Code protected paths like
.claude/skills/**. Worth surfacing to the operator as a candidate to revive.
This review could not independently verify exact commit subject/body text against git log
— no shell/git tool was available in this session. If precise commit-message conformance
matters, a follow-up with git access should confirm phase-06's actual commit body against
the plan's template, given the skills-not-updated finding above.

Pointers

(none — no incidental correctness issues were noticed outside plan-conformance scope during
this review)

Phase details

phase-01 — Parser reports every structural error

File reconciliation

PHAX File Reconciliation

Planned to create

src/domain/plan/lint.ts
tests/unit/planLint.test.ts

Planned to edit

src/domain/plan/parsePlanMarkdown.ts
tests/unit/parsePlanMarkdown.test.ts

Summary: No deviations from the planned file lists.

Phase handoff

What was delivered

src/domain/plan/parsePlanMarkdown.ts gained collectPlanStructureErrors(planMd): readonly StructureError[]
and the exported StructureError type ({ phase: string | null; message: string }),
built on a new internal walkPlan helper that accumulates every structural
defect in document order instead of stopping at the first.
extractPlanDeterministic is now a thin wrapper over walkPlan: unchanged
signature, unchanged Right/Left shape, byte-identical first-error
message.
src/domain/plan/lint.ts (new) exports the finding vocabulary:
LintSeverity = "error" | "warning", LintCheck = "structure" | "files" | "commands" | "models", LintFinding { severity; check; phase; message },
and structureFindings(planMd): readonly LintFinding[].

Key decisions and why

Per-phase checks still build their message as "<phase-id>: <text>" (as
before); collectPlanStructureErrors strips that literal prefix when
populating StructureError.phase so the renderer (phase-04) never sees a
doubled phase id. extractPlanDeterministic uses the raw (prefixed)
message unchanged, so no test asserting the old message text needed to
change.
The one message that never had a "<id>: " prefix — the missing-{#anchor}
heading error — still gets phase: "<id>" populated (the id is always
derivable via PHASE_HEADING_RE, since collectPhaseBlocks already
filtered blocks on that same regex), but its message text is left
exactly as before; there's nothing to strip.
LintSeverity/LintCheck are exported per spec even though nothing
outside lint.ts consumes them yet this phase; a type-only import was
added to tests/unit/planLint.test.ts to keep knip green until phase-04's
renderer and later checks reference them for real. Later phases should
feel free to drop that explicit type import once real consumers exist, as
long as knip stays green.

Exact locations (file paths and exported names)

src/domain/plan/parsePlanMarkdown.ts — collectPlanStructureErrors, StructureError, extractPlanDeterministic (unchanged signature)
src/domain/plan/lint.ts — LintSeverity, LintCheck, LintFinding, structureFindings

What the next phase needs to know

No file-plan deviations: only the four planned files
(src/domain/plan/parsePlanMarkdown.ts, src/domain/plan/lint.ts,
tests/unit/parsePlanMarkdown.test.ts, tests/unit/planLint.test.ts)
were touched. tests/unit/examplePlanDeterministic.test.ts (optional) was
left alone — extractPlanDeterministic's output is unchanged for that
fixture.
LintFinding.phase is null for plan-level errors (missing/empty title,
missing "## Required commands", no phase headings found) and a
phase-NN string for every phase-scoped error, including the
missing-{#anchor} case.
Findings are always in document order: plan-level checks first, then each
phase's checks in heading order; within a phase, a phase whose heading
can't be parsed (missing {#anchor}) is skipped after its own heading
error — no further checks run for that phase.
plannedPaths/filePlanFindings (phase-02) and commandFindings/
modelFindings/hasLintErrors (phase-03) all belong in the same
src/domain/plan/lint.ts file, alongside structureFindings.
All gate commands (format, typecheck, test:type, lint,
format:check, test, knip, audit:architecture,
gen:model-catalog --check, build, deno:smoke, deno:smoke-binary)
ran clean.

phase-02 — File-plan rule over the known-existing set

File reconciliation

PHAX File Reconciliation

Planned to edit

src/domain/plan/lint.ts
tests/unit/planLint.test.ts

Summary: No deviations from the planned file lists.

Phase handoff

What was delivered

src/domain/plan/lint.ts gained FilePlanPhase ({ id; plannedFilesToCreate; plannedFilesToEdit; optionalFilesToEdit }),
plannedPaths(phases): readonly string[], and
filePlanFindings(phases, existing: ReadonlySet<string>): readonly LintFinding[],
alongside the existing LintSeverity, LintCheck, LintFinding,
structureFindings from phase-01.
tests/unit/planLint.test.ts gained one test per spec 33 acceptance
criterion for the file-plan rule (9 new tests, 12 total in the file).

Key decisions and why

A phase that lists the same path in both plannedFilesToCreate and
plannedFilesToEdit gets exactly one finding
(create and edit both list <path>, error) and no further per-path
checks that phase — the plan's instruction was to "report once, then treat
the path as created for later phases," so the exists/already-created
checks are skipped for that path in that phase, but it still joins known
under the current phase id.
known origin values are the literal string "ground" for paths seeded
from the working-tree existence set, or a phase-NN id for paths created
by an earlier phase — the message text branches on which ("exists in the working tree" vs "already created by phase-NN").
FilePlanPhase is a standalone interface, not Pick<PhaxPlanPhase, ...> —
lint.ts has no dependency on schemas/phaxPlan.js yet. Its shape is
identical to the relevant PhaxPlanPhase fields, so phase-03 can pass real
plan phases directly with no adapter.

Exact locations (file paths and exported names)

src/domain/plan/lint.ts — FilePlanPhase, plannedPaths, filePlanFindings
(new); LintSeverity, LintCheck, LintFinding, structureFindings
(from phase-01, unchanged)

What the next phase needs to know

No deviations: only the two planned files
(src/domain/plan/lint.ts, tests/unit/planLint.test.ts) were touched.
Message formats to reuse verbatim (the CLI renders them as-is in
phase-04): create and edit both list <path>,
create <path>: exists in the working tree,
create <path>: already created by <phase-id>,
edit <path>: does not exist and no earlier phase creates it,
create <path>: also listed under optional files.
plannedPaths returns paths in plan order (first-seen), deduplicated,
excluding every optionalFilesToEdit entry — this is exactly the probe
list phase-03's app layer should check against the filesystem to build the
existing set for filePlanFindings.
commandFindings, modelFindings, hasLintErrors, and the lintPlan use
case (phase-03) belong alongside these exports in the same
src/domain/plan/lint.ts file, per the plan.
All gate commands ran clean: format, typecheck, test:type, lint,
format:check, test (2871 tests), knip (only pre-existing config hints, no
errors), audit:architecture, gen:model-catalog --check, build,
deno:smoke, deno:smoke-binary.

phase-03 — Run-readiness rules and the lint use case

File reconciliation

PHAX File Reconciliation

Planned to create

src/app/lintPlan.ts
tests/integration/lintPlan.test.ts

Planned to edit

src/domain/plan/lint.ts
tests/unit/planLint.test.ts

Summary: No deviations from the planned file lists.

Phase handoff

What was delivered

src/domain/plan/lint.ts gained commandFindings, modelFindings and
hasLintErrors beside the phase-01/02 exports.
src/app/lintPlan.ts holds lintPlan(opts) and the LintReport /
LintPlanOptions types.
tests/unit/planLint.test.ts covers the two wrappers and hasLintErrors;
tests/integration/lintPlan.test.ts covers the use case (6 cases).

Key decisions and why

commandFindings(requiredCommands, configCommands, gateCommands) is
positional, matching the plan text rather than the object form of
checkRequiredCommands.
lintPlan returns after the structure findings whenever
extractPlanDeterministic is Left — the later checks need a parsed plan,
and no cache or model path exists.
finalizeExtractedPlan warnings (anchor mismatches) surface as structure
findings of severity warning, its Left as one structure error with
phase: null.
Gate commands come from Object.keys(config.raw.gateProfiles)[0]; when the
map is empty the list is [], not an error.
loadRouting.ts was not touched: absent ~/.phax/model-routing.json /
providers.json already fall back to the built-in defaults.

Exact locations (file paths and exported names)

src/app/lintPlan.ts — lintPlan, LintReport, LintPlanOptions
src/domain/plan/lint.ts — commandFindings, modelFindings,
hasLintErrors, structureFindings, plannedPaths, filePlanFindings,
LintFinding, LintSeverity, LintCheck, FilePlanPhase

What the next phase needs to know

lintPlan's type is
Effect<LintReport, FsError | ConfigValidationError, FileSystem> — provide
makeRepoRootedFileSystemLayer(config) and nothing else. Adding any other
port requirement would break the structural guarantee of spec 33 §5.1.
LintReport.plan echoes planMdPath verbatim; the CLI resolves the path
before calling.
Findings arrive in check order: structure, files, commands, models. Messages
are final text — render them verbatim.
commands message:
required command "<cmd>" is not covered by security.agentCommands or the gate profile.
models message: <model> / <effort>: <reasons; joined> plus
(alternatives: id1, id2) when the failure lists any. phase is null for
plan-level findings, the phase-NN id otherwise.
An unreadable plan or an invalid global routing/provider file fails the
effect (FsError / ConfigValidationError); it never becomes a finding, so
phase-04 routes those through exitCodeForError, not hasLintErrors.
No deviations from the planned file lists; the optional
src/app/loadRouting.ts was left untouched.

phase-04 — `phax plans lint` command, rendering and JSON

File reconciliation

PHAX File Reconciliation

Planned to create

src/domain/plan/lintRender.ts
tests/unit/planLintRender.test.ts

Planned to edit

Optional files touched

tests/integration/cliProgram.test.ts

Summary: No deviations from the planned file lists.

Phase handoff

What was delivered

src/domain/plan/lintRender.ts holds renderLintReport and the RenderableLintReport
input type.
src/cli/commands/plans.ts gained runPlansLint and PlansLintCommandOptions, and
registers plans lint <plan> [--json] on the existing plans parent.
src/cli/cliDocs.ts gained the "plans lint" entry; the plans parent help and
examples now name lint.
phax.usage.kdl, docs/cli/reference.md and the README generated block regenerated;
docs/cli/inventory.md gained a ### plans section carrying the lint row.

Key decisions and why

--json emits the LintReport verbatim ({ plan, findings }), not wrapped in a
{ report } key as plans status does — spec 33 §5.11 describes the report itself.
The plan argument is resolve(process.cwd(), plan) before it crosses the port: the
FileSystem layer is repo-rooted, so a bare relative arg would otherwise be reinterpreted
as repo-relative. LintReport.plan therefore echoes an absolute path.
docs/cli/inventory.md had no plans family at all. The new section carries only the
lint row; backfilling status and overlap would be unrelated scope.
tests/integration/cliProgram.test.ts (optional file) was touched: that suite already
inspects subcommand trees, so the lint shape assertion belongs there now, not in phase-05.

Exact locations (file paths and exported names)

src/domain/plan/lintRender.ts — renderLintReport, RenderableLintReport
src/cli/commands/plans.ts — runPlansLint, PlansLintCommandOptions,
runPlansStatus, registerPlansCommand
src/domain/plan/lint.ts — hasLintErrors (the exit-code predicate)
src/app/lintPlan.ts — lintPlan, LintReport
src/cli/cliDocs.ts — "plans lint" key
docs/cli/inventory.md — ### plans section

What the next phase needs to know

Rendered output: <plan>: N errors, M warnings (singular when a count is 1) or
<plan>: no findings; then one line per finding,
<severity padded 7> <check padded 9> <phase|"-" padded 8> <message>.
Exit codes: 1 when any finding is an error; 0 for warnings-only or none; a config error
is 1; a use-case failure goes through exitCodeForError, not hasLintErrors.
Regenerating both pnpm gen:usage-spec and pnpm docs:cli rewrote phax.usage.kdl,
docs/cli/reference.md and the README only between its generated markers. Phase-05
must re-run both after removing extract-plan, and delete the extract-plan row from
the hand-maintained docs/cli/inventory.md — that row is still there.
src/cli/cliCompleters.ts (optional) was left untouched: it carries no plans entries,
so lint needs none.
Test helpers in tests/unit/cli/plans.test.ts live at module scope, not inside their
describe — oxlint's unicorn(consistent-function-scoping) rejects the nested form.
phax plans lint was not run by hand against a real plan; the unit and integration
suites are the only evidence.

phase-05 — Remove extract-plan from code and generated docs

File reconciliation

PHAX File Reconciliation

Planned to edit

Deleted files

src/cli/commands/extractPlan.ts

Summary: Deviations detected — see sections above.

Phase handoff

What was delivered

extract-plan no longer exists as a CLI command: its registration is gone
from src/cli/program.ts and src/cli/commands/extractPlan.ts is deleted.
src/app/extractPlan.ts now exports only extractPlanLlm, extractPlanCore,
ExtractPlanCoreOptions, ExtractPlanCoreResult, ExtractPlanCoreError —
the persistent wrapper (extractPlan, ExtractPlanOptions/Result/Error,
buildExtractReport, parseShortNameFromPlanText) is gone.
loadOrExtractPlan's --no-extract cache-miss message reads:
No cached extraction for "<path>"; drop --no-extract to extract it.
phax.usage.kdl, docs/cli/reference.md, README's generated CLI block, and
docs/cli/inventory.md no longer mention extract-plan.

Key decisions and why

extractPlanCore and extractPlanLlm are untouched in behavior — phax run
(via loadOrExtractPlan) and tests/integration/extractPlanSealed.test.ts /
extractPlanTitles.test.ts still exercise them exactly as before.
src/cli/commands/run.ts's "extract-plan" RunId placeholder string (an
internal telemetry label for "no run context yet", same pattern as
orient.ts's ORIENT_TELEMETRY_RUN_ID) was left as-is: it's not part of the
CLI command surface and the plan does not list run.ts as a file to touch.
No unplanned files were touched; every planned file in this phase's
plannedFilesToEdit was edited, no optional files were needed
(src/cli/cliDocs.ts and src/cli/cliCompleters.ts had no extract-plan
references to begin with).

Exact locations (file paths and exported names)

src/app/extractPlan.ts — extractPlanLlm, extractPlanCore,
ExtractPlanCoreOptions, ExtractPlanCoreResult, ExtractPlanCoreError
src/app/loadOrExtractPlan.ts — loadOrExtractPlan (hint text changed only)
src/cli/program.ts — no more extract-plan command registration
docs/cli/inventory.md — extract-plan row removed (no plans lint row
gap introduced by this phase; that row was added in phase-04)

What the next phase needs to know

Remaining extract-plan prose mentions live only in README.md (~239,
~246, ~414), docs/extract-plan-model.md, .claude/skills/phax-planning/SKILL.md,
.claude/skills/phax-cli/SKILL.md, .claude/skills/phax-spec/SKILL.md, and
examples/hello-world/plan.md — exactly phase-06's scope, untouched here.
pnpm test has one pre-existing flaky test unrelated to this phase:
tests/integration/providerDispatcher.test.ts > "codex-cli routes to the
Codex adapter…" times out under full-suite load but passes in isolation
(verified). Not a regression from this phase's changes.
phax --usage and phax.usage.kdl/docs/cli/reference.md confirmed to no
longer list extract-plan; phax extract-plan now fails with
error: unknown command 'extract-plan' (exit 1), confirmed by hand.
pnpm knip is clean after the deletion — no unused export or dependency was
left behind by removing the wrapper.

phase-06 — Docs, skills and example follow the lint

File reconciliation

PHAX File Reconciliation

Planned to create

docs/plan-extraction-model.md

Planned to edit

README.md
.claude/skills/phax-planning/SKILL.md
.claude/skills/phax-cli/SKILL.md
.claude/skills/phax-spec/SKILL.md
examples/hello-world/plan.md

Renamed files

docs/extract-plan-model.md → docs/plan-extraction-model.md

Summary: Deviations detected — see sections above.

Phase handoff

What was delivered

README.md now documents write → lint → run: the "Write a plan" section
points at phax plans lint instead of phax extract-plan, and the old
"Extract the plan" section is replaced by "Lint the plan" with a
phax plans lint docs/plans/NN-<slug>-plan.md example and a summary of the
four checks and the exit code.
docs/extract-plan-model.md is renamed to docs/plan-extraction-model.md
and retitled "Plan extraction model configuration": the precedence chain is
now two levels (agent.extractPlan.* in phax.json, then the built-in
default — no CLI flag), and the text says extraction runs inside phax run
(and plans status / plans overlap) as the deterministic-parse fallback.
examples/hello-world/plan.md's note now says to run phax plans lint plan.md then phax run --plan plan.md.

Key decisions and why

The three shipped skills (.claude/skills/phax-planning/SKILL.md,
.claude/skills/phax-cli/SKILL.md, .claude/skills/phax-spec/SKILL.md)
were not edited: every Edit and Bash write attempt against paths under
.claude/skills/ was denied by the harness's permission system in this
session (read access to the same files worked fine). The commit was created
by phax with only the files that were actually writable staged in it.

Exact locations (file paths and exported names)

README.md — "Write a plan" / "Lint the plan" sections, and the
docs/plan-extraction-model.md link near the --trace docs.
docs/plan-extraction-model.md — renamed from docs/extract-plan-model.md.
examples/hello-world/plan.md — top note.
Untouched, still referencing extract-plan and needing the phase-06 edits:
.claude/skills/phax-planning/SKILL.md (frontmatter description + lines
9, 13, 40, 85, 114, 188, 447), .claude/skills/phax-cli/SKILL.md:66,
.claude/skills/phax-spec/SKILL.md:19.

What the next phase needs to know

Deviation: docs/plan-extraction-model.md shows as "not created" in
the reconciliation report because it was produced via git mv +
content rewrite (a rename), not a fresh file — the old path
docs/extract-plan-model.md is deleted and the new path is a distinct diff
entry from a pure create. The content changes described above are real and
committed.
Deviation (unresolved): the three skill files remain unedited because
writes under .claude/skills/ were denied for the entire session. This is
the actual open work of spec 33 — a future session (with write access to
.claude/skills/) must apply the phase-06 edits verbatim: swap every
phax extract-plan mention for phax run (inline extraction) /
phax plans lint <plan> (checking) per the plan's phase-06 detailed
instructions, and add the "Lint before you run" paragraph to
phax-planning/SKILL.md right after "What phax expects".
A grep for extract-plan outside docs/blog/, docs/vocabulary-review.md,
docs/plans/archive/, docs/specs/archive/, and this feature's own
spec/plan files will only be clean once that follow-up lands.

Refactor the deterministic plan parser to collect every structural error in document order and expose them through collectPlanStructureErrors, keeping extractPlanDeterministic's first-error contract intact for the run's fast path. Introduce the lint finding vocabulary (severity, check, phase, message) and the structure check that maps parser errors to findings. Groundwork for spec 33's plan lint. --- Run-Id: plan-lint-1788858296696 Short-Name: plan-lint Phase-Id: phase-01 Phase-Title: Parser reports every structural error Model: claude-sonnet-5 Effort: medium Worktree: /Users/remyloubradou/.phax/worktrees/phax.plan-lint/phase-01 Session-Id: b52cfb42-ff8c-420e-ac56-75e2dd408c26 Gate-Log: /Users/remyloubradou/.phax/runs/phax.plan-lint/phase-01/checks-attempt-01.log

Add filePlanFindings: walk the phases in order over a known-existing set seeded from the working tree, flagging edits of unreachable files, creates of existing or already-created files, and a phase that both creates and edits a path; warn on a path listed both to create and as optional. Optional files are never checked. Pure domain code with one unit test per spec 33 acceptance criterion. --- Run-Id: plan-lint-1788858296696 Short-Name: plan-lint Phase-Id: phase-02 Phase-Title: File-plan rule over the known-existing set Model: claude-sonnet-5 Effort: medium Worktree: /Users/remyloubradou/.phax/worktrees/phax.plan-lint/phase-02 Session-Id: 59fde2d4-70ef-410c-9cb8-b1c5d805a50c Gate-Log: /Users/remyloubradou/.phax/runs/phax.plan-lint/phase-02/checks-attempt-01.log

Add commandFindings and modelFindings as thin domain wrappers over the run-start preflight functions, and lintPlan, the read-only app use case that reads a plan, reports structural errors without ever falling back to the model, probes the planned paths through the FileSystem port for the file-plan rule, and runs the required-commands and model-catalog checks with the same inputs executePlan uses. Requires FileSystem only, which is what keeps it side-effect free by construction. --- Run-Id: plan-lint-1788858296696 Short-Name: plan-lint Phase-Id: phase-03 Phase-Title: Run-readiness rules and the lint use case Model: claude-opus-5 Effort: medium Worktree: /Users/remyloubradou/.phax/worktrees/phax.plan-lint/phase-03 Session-Id: 5cd8698c-91fe-43c0-9923-1ee70d2538e4 Gate-Log: /Users/remyloubradou/.phax/runs/phax.plan-lint/phase-03/checks-attempt-01.log

Add `phax plans lint <plan> [--json]`: renders the lint report or emits it as JSON and exits 1 when any finding is an error. Read-only, model-free: the command provides the filesystem layer only. Long help in cliDocs; usage spec, CLI reference, README generated block and the hand-maintained inventory updated. Implements spec 33 §5.10, §5.11 and §6. --- Run-Id: plan-lint-1788858296696 Short-Name: plan-lint Phase-Id: phase-04 Phase-Title: `phax plans lint` command, rendering and JSON Model: claude-opus-5 Effort: medium Worktree: /Users/remyloubradou/.phax/worktrees/phax.plan-lint/phase-04 Session-Id: 9f83e1c7-b90a-4179-bf45-3b9cdef69979 Gate-Log: /Users/remyloubradou/.phax/runs/phax.plan-lint/phase-04/checks-attempt-01.log

Remove the standalone extract-plan command and the app wrapper that wrote phax-plan.json and extract-report.md; phax run keeps extracting inline with the cache and the model fallback, and phax plans lint is the way to check a plan. Update the cache-miss hint, the command-list and e2e tests, and regenerate the usage spec and CLI reference. Implements spec 33 §5.12. BREAKING CHANGE: `phax extract-plan` no longer exists; use `phax plans lint` to check a plan, and read a run's phax-plan.json from its run folder. --- Run-Id: plan-lint-1788858296696 Short-Name: plan-lint Phase-Id: phase-05 Phase-Title: Remove extract-plan from code and generated docs Model: claude-sonnet-5 Effort: medium Worktree: /Users/remyloubradou/.phax/worktrees/phax.plan-lint/phase-05 Session-Id: 3ca69b49-0c88-426c-a3c2-c604b06d2a1f Gate-Log: /Users/remyloubradou/.phax/runs/phax.plan-lint/phase-05/checks-attempt-01.log

Rewrite the README flow around phax plans lint, rename the extraction-model doc to describe the extraction phax run performs, and update the phax-planning, phax-cli and phax-spec skills and the hello-world example so no shipped document tells an agent to run extract-plan. Completes spec 33. --- Run-Id: plan-lint-1788858296696 Short-Name: plan-lint Phase-Id: phase-06 Phase-Title: Docs, skills and example follow the lint Model: claude-sonnet-5 Effort: low Worktree: /Users/remyloubradou/.phax/worktrees/phax.plan-lint/phase-06 Session-Id: 42d6c5ce-d385-4518-9a4d-d7cdbd0fe6a8 Gate-Log: /Users/remyloubradou/.phax/runs/phax.plan-lint/phase-06/checks-attempt-01.log

Transitions docs/plans/33-plan-lint-plan.md to Completed (complete).

Transitions docs/specs/33-plan-lint.md to Completed (complete).

Completes the phase-06 edits the run could not apply: writes under .claude/skills/ were denied for the whole session, so the phase committed its README, extraction-model and example changes with a commit body that claimed the skills had been updated too. phax-planning attributes the two-stage extraction to phax run and gains a "Lint before you run" section; phax-cli's line 66 and canonical flow name phax plans lint; phax-spec's pipeline diagram becomes spec -> plan.md -> phax plans lint -> phax run. A grep for extract-plan is now clean outside docs/blog/, docs/vocabulary-review.md, the archives and this feature's own artifacts. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0164hoKCjqGFeFQcPB66ThLn

filePlanFindings short-circuited with `continue` after reporting that a phase lists the same path both to create and to edit, which skipped the spec 33 §5.5 check (create of a path that exists in the working tree or was already created by an earlier phase) and the create-and-optional warning for that path. §5.5 is unconditional, and the lint's premise is one pass reporting every defect. Drop the short-circuit so all three checks run on the path; the edit loop still skips it via createdHere, so no duplicate "does not exist" finding. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0164hoKCjqGFeFQcPB66ThLn

Removing the extract-plan command left extractPlanCore with no production caller — only two integration test files, which is why knip could not see it. The live fallback path is loadOrExtractPlan -> extractPlanLlm. Delete the wrapper and its options/result types, and re-point its tests at the functions that actually ship: the sealed-completion tests exercise extractPlanLlm directly (temp dir, complete-not-runAgent, provider), and the title-derivation tests go through loadOrExtractPlan, so they now cover the real LLM-fallback seam rather than a dead one. ExtractPlanCoreError loses its referent and becomes ExtractPlanError. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0164hoKCjqGFeFQcPB66ThLn

The CLI absolutizes the plan argument against the invocation directory so the repo-rooted FileSystem layer does not reinterpret a bare relative path as repo-relative — but it then handed that resolved path to the report, so `phax plans lint docs/plans/60-foo-plan.md` printed an absolute path in both the header and the JSON `plan` field. Spec 33 §6 shows the argument. Split the two roles: `planMdPath` is what the plan is read from, `reportPath` is what the report names. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0164hoKCjqGFeFQcPB66ThLn

Plan 41's preamble still told a reader to feed the file to `phax extract-plan`; it now names `phax plans lint` and `phax run`. The README's "Write a plan" section pointed at `examples/plan.md`, which has never existed — the worked example is `examples/hello-world/plan.md`. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0164hoKCjqGFeFQcPB66ThLn

The dispatcher test called the real adapters, so every run spawned `claude`, `vibe` and `codex` with a live prompt. That is why the codex case intermittently blew its 30s budget: on a machine where the binary is installed and authenticated it performs an actual agent turn. It also cost the integration tier ~30s of its ~43s wall clock. Worse, it asserted almost nothing. Each case only checked that the error message — if there was an error at all — did not say "not yet wired", then finished with `expect(true).toBe(true)`. Routing claude-code to the Codex adapter would have passed. Stub the three adapter modules and assert the dispatch positively: each provider reaches its own adapter and no other, with the provider-config entry the adapter needs. Adds the guard case the old test could only infer, for a provider the union does not name. Verified by mutation — pointing codex-cli at the Claude adapter now fails the suite, where before it passed. No I/O left, so it moves to the unit tier: 45s and flaky -> 0.3s and deterministic. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0164hoKCjqGFeFQcPB66ThLn

CI hit ENOTEMPTY removing the fixture repo in afterEach. The assertions had already passed — only the cleanup failed. `git commit` spawns a detached `git maintenance run --auto --quiet` (confirmed under GIT_TRACE on git 2.41), which can still be writing into .git when afterEach walks the tree. Node's recursive rmSync does not retry by default, so one entry appearing mid-removal fails the whole call. Disable auto maintenance and gc in the fixture repo so nothing is left running, and give the removal a few retries to cover any other late writer. The same pattern — mkdtemp, git init, commit, recursive rm — appears in 16 other test files and carries the same latent race; this commit only fixes the one that failed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0164hoKCjqGFeFQcPB66ThLn

…eeping Prune the queue after the two September plans landed: spec 33 through plan 33 (PR #94, plans lint replacing extract-plan) and spec 19 through plan 60 (PR #96, the advisory plan auditor), both completed and archived, with v0.13.0 released and on npm. The approved-specs section shrinks to the two parked specs (23, 24); the spec 33 and spec 19 subsections go, as do the ticked run-lookup, run-archive and plan 39 entries already in the history. The preflight-ordering follow-up stays open with a note that plan 33 catches the commands and models causes earlier but the run command still allocates the run folder before executePlan. Housekeeping records today's archive of the two review_open runs and the global install bumped to 0.13.0. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DhEPaMfTNpVzL4aRwuZiWG

lbdremy and others added 15 commits September 8, 2026 11:11

chore(plans): complete 33-plan-lint-plan

14d7b5f

Transitions docs/plans/33-plan-lint-plan.md to Completed (complete).

chore(specs): complete 33-plan-lint

3f295f7

Transitions docs/specs/33-plan-lint.md to Completed (complete).

lbdremy merged commit e6c65c0 into main Sep 9, 2026
2 checks passed

Navigation Menu

PHAX: Plan lint - #94

PHAX: Plan lint#94
lbdremy merged 15 commits into
mainfrom
phax/plan-lint--phase-06

lbdremy commented Sep 8, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

lbdremy commented Sep 8, 2026

PHAX Run Review Handoff

Run Review Handoff

Run summary

Global File Reconciliation

Global unplanned changes

Global missing planned changes

Global review attention points

Deviations not explained in any handoff

Plan compliance review

Plan-compliance review — phax.plan-lint

Verdict: conformant-with-deviations

Per-phase findings

phase-01 — Parser reports every structural error

phase-02 — File-plan rule over the known-existing set

phase-03 — Run-readiness rules and the lint use case

phase-04 — phax plans lint command, rendering and JSON

phase-05 — Remove extract-plan from code and generated docs

phase-06 — Docs, skills and example follow the lint

Unplanned-change ledger

Unmet-promise ledger

Attention points

Pointers

Phase details

phase-01 — Parser reports every structural error

File reconciliation

PHAX File Reconciliation

Planned to create

Planned to edit

Phase handoff

What was delivered

Key decisions and why

Exact locations (file paths and exported names)

What the next phase needs to know

phase-02 — File-plan rule over the known-existing set

File reconciliation

PHAX File Reconciliation

Planned to edit

Phase handoff

What was delivered

Key decisions and why

Exact locations (file paths and exported names)

What the next phase needs to know

phase-03 — Run-readiness rules and the lint use case

File reconciliation

PHAX File Reconciliation

Planned to create

Planned to edit

Phase handoff

What was delivered

Key decisions and why

Exact locations (file paths and exported names)

What the next phase needs to know

phase-04 — phax plans lint command, rendering and JSON

File reconciliation

PHAX File Reconciliation

Planned to create

Planned to edit

Optional files touched

Phase handoff

What was delivered

Key decisions and why

Exact locations (file paths and exported names)

What the next phase needs to know

phase-05 — Remove extract-plan from code and generated docs

File reconciliation

PHAX File Reconciliation

Planned to edit

Deleted files

Phase handoff

What was delivered

Key decisions and why

Exact locations (file paths and exported names)

What the next phase needs to know

phase-06 — Docs, skills and example follow the lint

File reconciliation

PHAX File Reconciliation

Planned to create

Planned to edit

phase-04 — `phax plans lint` command, rendering and JSON

phase-04 — `phax plans lint` command, rendering and JSON