feat(planctl): v2 task-state commands (next, list, complete, status) #1

Closed

sid wants to merge 0 commits from feature/26174-planctl-task-cmds into main

pull from: feature/26174-planctl-task-cmds

merge into: devtools:main

devtools:main

Conversation 0 Commits - Files changed -

sid commented 2026-04-26 08:54:27 -06:00

Owner

Copy link

Adds four new planctl subcommands: next, list, complete, status. Full golden-file fixture coverage, emit unit tests, and pre-PR codex review (3 rounds, 4 bugs fixed). See dev/plans/26174-planctl-task-cmds/prd.md for full spec.

Adds four new planctl subcommands: next, list, complete, status. Full golden-file fixture coverage, emit unit tests, and pre-PR codex review (3 rounds, 4 bugs fixed). See dev/plans/26174-planctl-task-cmds/prd.md for full spec.

sid added 14 commits 2026-04-26 08:54:28 -06:00

feat(planctl): initialize feature branch + migrate plan dir ... 7467ef65f8

Planner→implementer handoff per dev/README.md: move the 26172-planctl plan dir (prd, design, tasks, codex-sessions, handoff) from the shared plans commit into this feature branch via jj squash, so tasks.md is visible in the branch's history for /process-task-list to consume.

Parent task 0.0 from dev/plans/26172-planctl/tasks.md.

feat(planctl): project skeleton — cmd/planctl, goldmark dep, subcommand dispatch ... a7a79eab65

* cmd/planctl/main.go: run() entry, --help (usage + classification codes),
  --version, lint subcommand stub, R6.1 sentinel for v2-reserved subcommands
  (list/next/complete/new-plan), R5.8 exit-2 for unknown subcommand/flag.
* go.mod: require github.com/yuin/goldmark v1.8.2 (will be promoted from
  indirect to direct once the scanner imports it in parent task 2).
* cmd/planctl/main_test.go: 8 subtests covering help/version/v2-reserved/
  unknown/no-args/lint-stub with // spec:planctl/... tags mirroring production.
* .gitignore: add planctl binary so stray go-build artifacts don't trip jj's
  snapshot size limit.

Parent task 1.0 from dev/plans/26172-planctl/tasks.md.
Codex code-review session 019db22d-7978-7e70-ae87-5242d1eedc25 (3 rounds).

feat(planctl): scanner — goldmark-backed InCode + LineMask classification ... aa73e2f727

* cmd/planctl/scan.go: Scan() / scanBytes() construct a goldmark parser with
  the TaskList extension; AST walk populates InCode[] for CodeBlock /
  FencedCodeBlock / HTMLBlock and LineMask[] for inline CodeSpan nodes with
  +/-1 byte extension to cover the surrounding backticks.
* offsetToLineCol folds '\n' bytes into the preceding line so block segment
  Stop-1 maps correctly — a subtle off-by-one that tripped the closing fence
  and trailing blank-line tests before the fix landed.
* cmd/planctl/scan_test.go: 7 test functions covering fenced / indented /
  HTML blocks, inline code spans (substring + exact-range), nested emphasis
  around code, mixed features in one document, EOF-in-fenced-block, and
  trailing-newline splitLines variations.
* go.mod: goldmark promoted from indirect to direct (scan.go imports it).

Parent task 2.0 from dev/plans/26172-planctl/tasks.md.
Codex code-review session 019db23c-6c44-7d00-b3a4-6653882f0964 (2 rounds).

feat(planctl): indexer — R-id / D§ id / tag / task-line extraction ... 3f63d24c41

* index.go types: Plan, TagRef, Kind (+ KindRequirements/KindDesign),
  TaskLine, Index, Position; Diagnostic / Severity / Code stubs parked
  here until task 4.1 moves them to lint.go.
* Grammar validators: isValidReqID / isValidDesID / isInfraRef backed
  by compile-time regex patterns; infra sentinel handled transparently.
* Tag state machine (extractTagsFromLine) with the design §3.3
  "Tag-unclosed recovery" semantics — forward scan that treats an inner
  `_Requirements:` / `_Design:` opener as a recovery signal, so
  `_Requirements: R3 _Design: D§2_` produces one tag-unclosed + one
  well-formed D§2 extraction. extractTags composes mask → state
  machine → body-parse.
* PRD R-id extraction via ast.ListItem walk (AST-primary) with regex
  fallback for malformed lists.
* Design D§ extraction via ast.Heading level 2-4 walk. Pattern widened
  to tolerate the `## 0. Scope` period-space convention used by
  level-2 headings in the in-repo design.md.
* Task-line extraction via east.TaskCheckBox walk; Indent from raw
  line leading spaces; InCode[] exclusion per R3.3.
* BuildIndex orchestrator + extractTaskTags helper.
* Table-driven index_test.go covering all 10 cases from sub-task 3.9;
  assertDiagsExact fails on extras so in-fence / inline-code-span
  exclusion and recovery fixtures are tight.
* 39 `// spec:planctl/*` traceability anchors across index.go.

Parent task 3.0 from dev/plans/26172-planctl/tasks.md.
Codex code-review session: 019db26e-629f-7f51-afe2-28dbb1d14ba6 (3 rounds).

feat(planctl): lint rules — tag-syntax, cross-reference, file-presence, EARS ... 77e1ff19b6

* lint.go: Severity / Code (full set) / Diagnostic types migrated
  here from their temporary home in index.go. Code constants form the
  grep-stable public contract per design §4.
* checkTagSyntax (passthrough over idx.MalformedTags).
* checkCrossRef with four diagnostic classes (orphan-requirement,
  orphan-design, uncovered-requirement, uncovered-design), R2.8
  hasDesign gate, R2.9 infra-sentinel exemption, and sorted-id emission
  for stable uncovered-* order.
* checkCloseoutFiles gated on R3.4 fully-closed-out definition
  (at-least-one + all-checked); emits Line=0 diagnostics with empty
  Path for the emitter to substitute plan-dir.
* newMissingPRDResult: R3.1/R3.2 fatal short-circuit.
* checkEars with the five design §3.4 regex patterns, narrow
  `^\*\*[^*]+\*\*` bold-prefix exemption, and --no-ears R4.4 skip.
* sortDiagnostics uses sort.SliceStable with (Path, Line, Code,
  Message) tie-breakers so output is deterministic run-to-run per
  PRD §6 even when two diagnostics share the first three keys
  (missing-closeout-file Line=0 pair).
* Position extended with a Text field populated at extraction time
  so checkEars keeps its literal `(idx, skip)` signature without
  passing a second *ScanResult.
* lint_test.go: one subtest per checker plus sort stability
  regression.

Parent task 4.0 from dev/plans/26172-planctl/tasks.md.
Codex code-review session: 019db2b8-21c8-7d61-85d6-1da5c18d8033 (2 rounds).

feat(planctl): plan-dir discovery + CLI dispatch wiring ... 4d865dfd82

* main.go: resolvePlans implementing the R5.1 / design §3.5 decision
  tree — Case A (explicit path stat) and a unified upward walk for
  Cases B (cwd inside plan dir) and C (cwd ancestor has dev/plans/)
  with archive/ filter and lex sort; Case D returns the 3-option
  error. No downward WalkDir.
* Hand-rolled parseLintFlags accepting --format={text,json},
  --strict, --no-ears, --color={auto,always,never} (no-op per D-1),
  both --flag=value and --flag value forms. Unknown flag → error.
* runLint orchestrator: resolvePlans → loadPlan (reads prd/design/
  tasks via Scan + os.Stat for close-out markers) → lintPlan
  (BuildIndex + 4 rule checkers, missing-PRD short-circuit per R3.2,
  PlanDir backfill, sortDiagnostics). Placeholder text emitter —
  task 6 replaces with the full emitText/emitJSON from design §3.7.
* computeExit returns 0/1 per R5.4/R5.5; 2 is reserved for outer
  discovery/I-O failures (runLint returns 2 directly on those paths).
* main_test.go: TestResolvePlans covers Cases A (valid + invalid), B
  (deeply-nested cwd), C (3 plans + archive filter + lex sort), D
  (no ancestor); TestParseLintFlags covers every documented flag
  plus unknown-flag rejection and last-value-wins. The prior stub
  test TestRun_LintStub was replaced with TestRun_LintMissingPRD —
  the stub assertion no longer holds now that runLint actually runs
  the pipeline. Output-format assertions may need revision when
  task 6.6 lands per tasks.md 5.6 note.

Parent task 5.0 from dev/plans/26172-planctl/tasks.md.
Codex code-review session: 019db2ca-721d-7b11-8760-639b2588b114 (1 round, approved on R1).

feat(planctl): emit — text and JSON formatters ... 5a14a1b413

* emit.go (new): PlanResult (moved from main.go), emitText,
  emitJSON, shared severityLabel / countSeverities helpers.
* emitText: R5.10 single-plan branch (diagnostics or R5.3 clean-
  summary, no headers / aggregate) + R5.9 multi-plan branch
  (`=== <basename> ===` per-plan header, blank-line separator,
  aggregate "N plans linted, E errors, W warnings" with always-
  plural labels).
* emitJSON: jsonl format per R5.11 with struct-tag-pinned field
  order (plan_dir, path, line, severity, code, message), terminal
  {"summary":{"plans":N,"errors":E,"warnings":W}} object,
  SetEscapeHTML(false) so ampersands / `<` stay raw.
* Empty Path (directory-level diagnostics: missing-prd,
  missing-closeout-file) renders with the plan-dir basename in
  text mode; in JSON the shape is uniform with `path=""` and
  plan_dir carrying the basename.
* main.go: runLint selects emitText or emitJSON based on
  flags.format; placeholder emitter removed.
* emit_test.go: single-plan clean, single-plan dirty, multi-plan
  text, multi-plan JSONL validity, clean-plan JSON (summary-only),
  --strict promoting warnings → exit 1, clean → 0, errors → 1.

Parent task 6.0 from dev/plans/26172-planctl/tasks.md.
Codex code-review session: 019db2d1-e9ae-7fc0-9b8b-270db5f0b2a3 (1 round, approved on R1).

feat(planctl): end-to-end fixtures + golden-file test harness ... 3bc838f86e

* main_test.go: TestGoldenFixtures sweeps
  testdata/{clean,dirty,inline-code-exclusion,multi}/**; compares
  stdout against expected.golden and exit against expected.exit.
  --update flag regenerates sidecars. Per-fixture invocation
  overrides via optional args.txt (with FIXTURE substitution) and
  cwd-rel.txt. Handles flat-layout fixtures (prd.md at class root)
  and multi-plan layouts (dev/plans/ subtree).
* CRLF normalisation on both sides of the golden compare per
  design §7.4's Windows-CI contract.
* Clean fixtures: simple-plan (prd+tasks), with-design-plan
  (prd+design+tasks, full coverage).
* Dirty single-class fixtures: orphan-requirement, orphan-design,
  uncovered-requirement, uncovered-design, tag-syntax, tag-unclosed,
  ears-violation, missing-closeout-file. Each isolates one
  diagnostic class; ears-violation-strict and ears-violation-no-ears
  share the plan via args.txt overrides.
* tag-unclosed-with-recovery fixture: codex R1 regression guard for
  design §3.3 recovery — the recovery line uniquely cites D§2.2 so
  broken recovery would surface as uncovered-design.
* inline-code-exclusion fixture: decoys cite an undeclared R9.9 so
  any masking leak would trip orphan-requirement.
* Multi-plan fixtures: case-c (repo root with dev/plans/{alpha,beta,
  archive/retired}/, Case C upward walk + archive skip); case-b
  (deeply-nested cwd inside a plan dir, Case B resolution).
* Perf fixture testdata/perf/big-plan/ — synthetic 5-file plan
  (~90 KB) with 36 R-ids, 18 D§ sections, 72 tasks (all covered).
  Parent 8 wires Benchmark_Lint_BigPlan.

Parent task 7.0 from dev/plans/26172-planctl/tasks.md.
Codex code-review session: 019db2ed-d621-7bc0-90f2-05feb5e2fe50 (2 rounds).

feat(planctl): CI workflow + perf benchmark ... 3dc1273a7a

* .forgejo/workflows/planctl.yml: build/test matrix across
  {ubuntu-latest, macos-latest, windows-latest} × {1.22, stable}
  per D-3 / PRD R7.4. Dedicated bench job on ubuntu+stable so
  ns/op numbers stay comparable across runs. Path filters scope
  CI to planctl-adjacent changes only.
* cmd/planctl/bench_test.go: Benchmark_Lint_BigPlan times the full
  lint pipeline on testdata/perf/big-plan/. Local M4 Pro: ~720µs,
  two orders of magnitude under M3's 100ms target.
* TestLint_BigPlan_SoftCeiling logs (via direct os.Stderr write —
  not t.Logf, which is suppressed without -v) when wall time
  exceeds 100ms. Soft check per task 8.3 — CI runner variance
  means a hard assert would be flaky; the visible stderr line is
  the regression signal.
* Windows line-ending handling already landed in parent-7's
  harness (CRLF → LF normalisation on both sides of golden
  compare), so 8.4 is satisfied by construction.

Parent task 8.0 from dev/plans/26172-planctl/tasks.md.
Codex code-review session: 019db2f3-2f80-7fc0-b7bb-9e1f677f978e (2 rounds).

feat(planctl): docs + close-out ... c32ae6c99e

* README.md: new `## planctl` section after the jj-commitd section —
  description, `go install` command, classification-code list,
  pointer to the plan dir.
* AGENTS.md: bullet under `dev/ workflow` pointing agents at
  `planctl lint` as a pre-codex sanity gate.
* dev/README.md: "Pre-codex planctl lint gate" paragraph in the
  Skill workflow section.
* tasks.md: appended full traceability matrix — one row per PRD
  R-id and one per design D§ id, with the tasks and tests covering
  each. Grep-verifiable against the `// spec:planctl/*` anchors.
* Dogfood pass (task 9.5) against dev/plans/26172-planctl/ flushed
  out real self-violations in the plan docs:
    - Expanded en-dash range tags (`R1.1–R1.7`) to explicit
      comma-separated lists.
    - Dropped comma-containing annotations (`D§0 (D-2, D-5)` →
      `D§0`).
    - Added D§2 / D§3 / D§7 umbrella citations to tasks 5.3 /
      3.1 / 7.7.
    - Applied the design §3.4 bold-prefix EARS exemption to R5.3
      / R5.4 / R5.5 / R5.11 (grammatically valid but non-strict
      EARS) by prepending short bold labels.
    - Updated PRD R5.11 to say `plan-directory basename` instead
      of `relative path from CWD` — resolving a long-standing
      divergence with task 6.4 + design §3.7 + the implementation.
* Final dogfood: `26172-planctl: clean (79 tasks, 45 requirements,
  21 design sections)`.

Parent task 9.0 from dev/plans/26172-planctl/tasks.md.
Codex code-review session: 019db302-b8a9-7e53-b1e3-feab4ed7081f (2 rounds).

fix(planctl): paren-aware tag extraction and splitting ... 1a29ff50b2

Pre-PR codex review found a gap in the R1.1 annotation grammar handling:

* scanTagAfterOpener treated the first '_' after an opener as the
  closing delimiter regardless of paren nesting, so a legitimate
  tag like `_Requirements: R1.1 (foo_bar)_` would incorrectly
  close at the underscore inside the annotation.
* parseTagBody split on every ', ' regardless of paren context, so
  `_Requirements: R1.1 (note, with comma), R2.1_` split into
  three bogus refs.

Both are per-spec: PRD R1.1 defines annotation body as 'arbitrary
non-) characters', which includes _ and ,. The state machine and
the ref-splitter are now paren-depth-aware; regression tests added
for both cases.

docs: add reference docs for both binaries + consolidated build guide ... 7fa52772b3

* docs/building.md — how to build jj-commitd and planctl from source,
  requirements, `go install` recipes, reproducible-build flags
  (`-trimpath -ldflags="-buildid="` per planctl PRD R7.3), test +
  benchmark commands, cross-compile, CI matrix link.
* docs/planctl.md — full command reference beyond --help: plan-dir
  discovery cases A-D, all 9 classification codes with severity and
  meaning, tag-grammar spec (including paren-aware annotations + the
  tag-unclosed recovery semantics), the five EARS regexes and the
  bold-prefix exemption, JSON schema, worked examples for pre-commit
  / CI / multi-plan / JSON consumers.
* docs/jj-commitd.md — architecture diagram, socket event protocol
  (session-start, post-edit, session-end, shutdown, status) with
  field tables, all env vars (REPO_ROOT, JJ_HOOK_DEBOUNCE_SEC,
  JJ_HOOK_STALE_MIN, JJ_HOOK_AUTO_SQUASH), baked-in timing constants,
  socket / log paths, fallback mode, troubleshooting.
* README.md — expanded the jj-commitd bullets and linked to each
  reference from a new "Documentation" section; kept top-level
  summaries terse.

feat(planctl): TaskRecord type and core helpers for v2 ... 21ccee527c

Add tasks.go: TaskRecord, stripCheckboxPrefix, parseTaskID,
buildTaskRecords, buildTaskRecordsFromScan, findTaskByID,
atomicRewriteTaskLine, evalPlanStatus

Add tasks_test.go: unit tests for all helpers

Task 1.0 from dev/plans/26174-planctl-task-cmds/prd.md

feat(planctl): v2 task-state commands (next, list, complete, status) ... 2f5ad32113

- Add tasks.go: TaskRecord, buildTaskRecords, findTaskByID, atomicRewriteTaskLine, evalPlanStatus
- Add runNext, runList, runComplete, runStatus subcommands in main.go
- Add emitNext, emitList, emitComplete, emitStatus formatters in emit.go
- Rewrite CLI dispatch; update printUsage to list all five subcommands
- Add 28 golden-file fixture dirs under testdata/v2/
- Add mutation tests for complete (success, already-done, triggers-lint, dry-run)
- Add per-subcommand --help tests and unit tests for all emit functions
- Fix: warnings-only status shows PASS not FAIL per R4.2
- Fix: case-insensitive T prefix for complete <task-ref> per R3.1
- Fix: dry-run JSON computes hypothetical lint diagnostics per R3.8
- Fix: dry-run JSON always exits 0 per R3.8
- Add multi-plan status aggregate: Summary line (text) + summary object (JSON) per R4.6

Tasks 2.0-6.0 from dev/plans/26174-planctl-task-cmds/prd.md

sid force-pushed feature/26174-planctl-task-cmds from 2f5ad32113 to b8ae95373c 2026-04-26 09:12:24 -06:00 Compare

sid force-pushed feature/26174-planctl-task-cmds from b8ae95373c to aff5a30b27 2026-04-26 09:12:38 -06:00 Compare

sid closed this pull request 2026-04-26 09:49:24 -06:00

Some checks failed

Hide all checks

planctl / build-test (1.22, macos-latest) (push) Has been cancelled

Details

planctl / build-test (1.22, ubuntu-latest) (push) Has been cancelled

Details

planctl / build-test (1.22, windows-latest) (push) Has been cancelled

Details

planctl / build-test (stable, macos-latest) (push) Has been cancelled

Details

planctl / build-test (stable, ubuntu-latest) (push) Has been cancelled

Details

planctl / build-test (stable, windows-latest) (push) Has been cancelled

Details

planctl / build-test (1.22, macos-latest) (pull_request) Has been cancelled

Details

planctl / build-test (1.22, ubuntu-latest) (pull_request) Has been cancelled

Details

planctl / build-test (1.22, windows-latest) (pull_request) Has been cancelled

Details

planctl / build-test (stable, macos-latest) (pull_request) Has been cancelled

Details

planctl / build-test (stable, ubuntu-latest) (pull_request) Has been cancelled

Details

planctl / build-test (stable, windows-latest) (pull_request) Has been cancelled

Details

planctl / bench (push) Has been cancelled

Details

planctl / bench (pull_request) Has been cancelled

Details

Pull request closed

This pull request cannot be reopened because the branch was deleted.

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels

No items

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference: devtools/template-jj#1

No description provided.