PR #426 follow-ups: design-doc status lifecycle, blocking alignment step, NNN races nf-9tap ← Beads

open priority 2 task unassigned

Twinned from https://github.com/cfsh/ninefold/issues/427 by tools/beads/import_github.py's reconcile pass.

Suggestions from ninefold-reviewer's review of #426. Advisory residuals only — #426 is CONVERGED and nothing here blocks it. Unclaimed and unlabelled; activate at the next /triage round if worth it.

1. Nobody flips a design doc's status, so the index rots

.claude/commands/design.md:133 gives every doc Status: proposed | accepted | implemented | superseded by NNN and design_docs/README.md:12-14 documents all four, but no step in any command transitions one. /design writes proposed and exits; the Implement design_docs/NNN-<slug>.md issue it files (design.md:174) is the natural owner of acceptedimplemented and is never told to touch the doc; and the supersede rule (design.md:167-170) edits the superseded doc's header while leaving its README index line still reading proposed.

End state: every doc reads proposed forever and the index disagrees with the docs it indexes — a believed-stale status, which is worse than the missing line the README warns about in its own last sentence.

Fix is two clauses: one in the Step-6 issue template ("when this lands, set the doc's Status and its README line to implemented"), one at design.md:169 for the README half of a supersede.

2. AskUserQuestion blocks, in the step that promises not to

design.md:96 prescribes AskUserQuestion for the crisp forks; design.md:110 promises never to block, with the doc as the fallback for when "he drifts off, defers, or says 'your call'". AskUserQuestion has no timeout. Step 4 runs before Step 5, so the drift-off case stalls the round *before the doc is written* — the fallback meant to catch that case never runs, and the deliverable is what's lost.

One sentence closes it: ask once; if no answer arrives, proceed to Step 5 with the defaults marked and say so in the report.

3. NNN allocation races silently across concurrent sessions

design.md:124 says "the next free number", computed against main. Dev sessions a/b/c run concurrently by design; two rounds in flight both read main and both pick 001. design_docs/001-foo.md and design_docs/001-bar.md are different paths, so git merges both cleanly — the collision is silent. Same shape as #408 (needing pr<N>/ before N exists).

Related: design.md:19 tells the round to read the README for prior work while :124 derives the number from the folder — a doc absent from the index would hand out a number twice.

4. First argument-taking command, no $ARGUMENTS and no argument-hint

/design <question> is the repo's first command that takes an argument, and the file never interpolates it. triage.md and playtest.md are both zero-arg, so there's no local precedent. Worth verifying what the harness does with arguments when no placeholder is present, and adding argument-hint: to the frontmatter either way for discoverability.

5. Two stale artifacts on #426 itself (fix on the PR, not here, if it's still open)

Dependencies

None.

Comments

No comments.

Add a comment