Create/Update Request Skill
Trigger
- Keywords: create request, new request, write request, build request, update request, sync progress, scan requests, request status, incomplete requests, request dashboard
Mode Overview
flowchart LR
A[/create-request] --> B{Mode?}
B -->|--status| C[Scan: Discover → Parse → Filter → Report]
B -->|--update-all| F[Batch Update: Scan → Git Verify → Batch Edit → Report]
B -->|--update| D[Update: Load → Analyze → Map → Update → Report]
B -->|default| E[Create: Gather → Explore → Generate → Confirm]
Modes
| Mode | Trigger Condition | Action |
|---|---|---|
create |
No file specified / new request | Gather info -> Fill template -> Create file |
update |
File specified / update request | Read current state -> Check implementation -> Update progress |
update-all |
--update-all flag |
Batch scan → git verify → update all stale docs → report |
scan |
--status flag |
Scan all requests -> Parse metadata -> Filter incomplete -> Report |
Arguments
| Flag | Applies To | Description |
|---|---|---|
--verify-ac |
--update (single) |
Dispatch Explore agent to verify AC completion with evidence (file:line). Supports auto-detected path via feature context 5-level cascade. Not available with --update-all. |
When NOT to Use
- Feature-level requirements analysis (use
/req-analyze— produces1-requirements.md, a Phase 1 lifecycle doc for problem-space analysis; see Relationship section below) - Viewing request structure (use request-tracking)
- Writing tech spec (use /tech-spec)
- Code development (use feature-dev)
Relationship with /req-analyze
Request tickets are work breakdown units derived from /tech-spec, not requirements documents themselves. They live in a different document class per @rules/docs-numbering.md.
| Dimension | /create-request → requests/YYYY-MM-DD-*.md |
/req-analyze → 1-requirements.md |
|---|---|---|
| Doc class | Request ticket (date-prefixed, non-lifecycle — per @rules/docs-numbering.md) |
Lifecycle (Phase 1, numeric prefix) |
| Count per feature | Many (one per task) | One (upsert) |
| Position in workflow | After /tech-spec (execution phase) |
Before /tech-spec (design phase) |
| Content focus | Execution — Status, Progress, AC checklist, Related Files | Problem space — 5-Why, FR/NFR, MoSCoW, stakeholders |
| Granularity | Single task (≤ 8 substantive ACs; gate receipts excluded from the budget, never from the lifecycle count) | Feature-wide |
| Update pattern | Status tracking (scan / update / update-all / --verify-ac) |
Document upsert |
| Audience | Executors, progress trackers | Designers, decision-makers |
Workflow ordering
/req-analyze → /tech-spec → /create-request → /feature-dev
(Phase 1) (Phase 2) (ticket per task) (implement)
A request ticket references its parent /tech-spec for technical detail and may optionally link to 1-requirements.md for problem-space rationale (when /req-analyze was run).
A feature directory may also carry intent-<key>.md (ancillary — Design record, written by
/req-analyze or /tech-spec): constraints only — North star, Non-goals, INV-* invariants,
acceptance sketch — read by both the designer and the implementer. Tickets never restate it; the
implementing skills load it themselves before writing code.
Anti-patterns to avoid
| Anti-pattern | Correct approach |
|---|---|
| Writing 5-Why / stakeholder analysis inside a request ticket | Put it in 1-requirements.md via /req-analyze; ticket just references it |
Adding ## Progress / ## Status tables to 1-requirements.md |
Progress tracking belongs in request tickets, not the lifecycle requirements doc |
| Creating one request ticket per whole feature (AC > 8) | Split by layer or functional area; see Granularity Guide in references/template.md |
Treating 1-requirements.md as a prerequisite for creating requests |
It is advisory-only; requests work standalone when only tech-spec exists |
Create Mode Workflow
Phase 1: Gather -> Collect feature, title, priority, requirements
Phase 1.5a: Quick -> AC count + layer keyword scan (pre-Explore)
Phase 2: Explore -> Search related code + tech specs
Phase 1.5b: Refined -> Layer mixing (Related Files) + scope breadth + WBS (post-Explore)
Phase 3: Generate -> Fill template + create file(s)
Phase 4: Confirm -> Display result + suggest next steps
Phase 1.5: Granularity Check
Assess whether the request should be split into multiple focused tickets. This runs in two passes to balance early detection with accurate analysis.
Signal Detection
| Signal | Detection | Weight |
|---|---|---|
| AC count > 8 | Count per § Pre-Render AC Count below — this whole phase runs in Create Mode, where no ticket is rendered yet — then exclude receipts per § Quality-Gate AC Classifier | Primary |
| Layer mixing | 1.5a: keyword scan for rules/, hooks/, scripts/ in requirements text. 1.5b: classify Related Files into behavior-layer (.md rules/skills) vs code-layer (.sh/.js hooks/scripts) |
Primary |
| Scope breadth | Requirements has 3+ functionally independent areas | Primary |
| WBS groups ≥ 2 | Tech spec has Work Breakdown heading with 2+ independent task groups (secondary, high-confidence only) |
Secondary (×0.5) |
| Effort > 3 days | Tech spec WBS has multiple M/L items | Secondary (×0.5) |
Pre-Render AC Count
Phase 1.5 runs inside the Create Mode workflow, before Phase 3 renders anything, so § Live
Checkbox ACs — which reads a rendered ## Acceptance Criteria section — has no input here and
would count zero, silently suppressing every split suggestion this phase exists to produce.
One rule, governing every count taken before the ticket exists: the overall {N}, and each
{AC_count_A} / {AC_count_B} in the split suggestion after grouping. Count the criteria gathered
at Phase 1 item 6, one per list item, whatever form the user wrote them in — numbered, hyphenated
or plain lines. Then exclude receipts per § Quality-Gate AC Classifier, applied to those same
strings — one of that classifier's two permitted uses. The subgroup counts are the same units as the
total, or a split "into two tickets of ≤ 8" can be proposed out of groups that were never measured
the same way as the number that triggered it.
Live Checkbox ACs
Every path that counts ACs in a ticket that exists — Scan Mode's AC Progress, the § AC-Form Preflight, Phase 2.5's verification input and decision table, Phase 3's Progress mapping, Phase 4 and batch mode — counts the same items, or the same ticket gets two different AC counts depending on who is looking.
The qualifier is load-bearing: this definition reads a rendered section, so the only counts that do not come from here are Create Mode's, defined at § Pre-Render AC Count.
An AC is a top-level hyphen-form task-list item inside ## Acceptance Criteria that is live document text —
^ {0,3}-\s+\[(?: |x|X)\] after live-text masking. The indent bound is load-bearing: a deeper
indent under a paragraph is a continuation of that paragraph, so Example only: followed by an
indented - [x] illustrative checkbox is visible prose, not a task list, and an unbounded ^\s*[-*]
counts it as a checked AC. CommonMark also allows * and + bullets and ordered task items; this
repo's template emits hyphens and the corpus contains no other form, so the extractor accepts the
hyphen form only and anything else reaches the § AC-Form Preflight's Need Human exit rather than
being promoted. A
checkbox inside a fenced block, an HTML comment, or an indented code example is illustration, not an
acceptance criterion, and a section holding nothing else has no ACs at all — which is the
§ AC-Form Preflight's no-mutation exit, not an empty AC set. Some tickets record ACs as an
AC → evidence table instead; that is a valid form which none of these paths can count, and it
takes the same exit.
Quality-Gate AC Classifier
Scope: display and granularity only. This classifier never touches status derivation. Exactly two paths use it — Scan Mode's AC Progress (what the dashboard shows) and Phase 1.5's split signal. Phase 2.5's decision table, Phase 4's lifecycle and batch mode's Status rule count every AC and do not consult it.
That boundary is the point. Classifying free-text ACs with a regex is inherently approximate: six
successive refinements each measured clean against the whole corpus, and each was then shown to
admit a behavioural requirement or drop a real receipt. Where a misread only shifts a displayed count it is visible; where it shifts the split suggestion
it may not be, since an undercount can suppress the suggestion silently. Both are advisory and
reversible, which is the property that matters. Where it fed status derivation, a
false positive removed an AC from the set a ticket had to satisfy — so a ticket could reach
Completed without the work. The fix is not a better regex; it is not letting an approximate signal
decide a durable record.
One consequence, and it is the correct one: an unchecked Pass /precommit keeps a ticket at
In Progress until that gate actually runs. A ticket whose gates have not run is not finished.
An AC is a quality gate only when it is a receipt — its content is that a gate ran, or why it
has not. Neither containing a gate command nor merely opening with one is the test:
`/precommit` — Try script -> fallback + graceful skip opens with a gate command and is an
implementation requirement for /precommit. A receipt is a gate command plus one of:
| Receipt marker | Example |
|---|---|
a receipt word — Pass / Passed / passes / 通過 |
Pass /codex-review-doc |
a round N citation |
`/codex-review-fast` round 1 |
a named verdict sentinel after a dash — exactly these six pairs: ✅ PASS / ✅ Ready / ✅ Mergeable / ⛔ Blocked / ⛔ Needs revision / ❌ FAIL |
`/precommit` — ✅ PASS |
a gate lifecycle tail — superseded or pending followed within a bounded window by a round N or verdict reference, or tracked below |
— pending Codex round 30 verdict |
A bare marker must also end the receipt — the intended semantics, subject to § Known residuals
below, which names the forms the published regex still accepts against this rule. pass, round N and tracked below are ordinary
English too, so each must be followed by end-of-AC, a parenthetical, or a paired verdict sentinel —
otherwise /precommit passes selected flags through to the underlying runner, round 3 results must be persisted and failure details are tracked below the originating step all read as
receipts. A receipt is short; a requirement continues into a sentence.
superseded and pending need that bounded follow-on precisely because they are ordinary English:
`/precommit` — pending jobs must resume after the build finishes is a behavioural requirement,
and dropping it from the displayed count understates what is left. (Under the old design, where
this classifier fed status derivation, the same misread could let a ticket advance without the AC.
That is why it no longer does — the consequence is now a wrong number on a dashboard or a
misfired split suggestion.) Labels are optional and may be bold or plain (AC-8:, **AC-Q1**).
^(?:(?:\*\*[^*]{1,24}\*\*|[A-Za-z][\w.-]{0,12})\s*[::]?\s+)?(?:(?:pass(?:ed|es)?|通過)\s+`?/(?:codex-review-fast|codex-review-doc|codex-review|precommit-fast|precommit|pr-review)\b|`?/(?:codex-review-fast|codex-review-doc|codex-review|precommit-fast|precommit|pr-review)`?(?:[^—((::]{0,40}?(?:\bpass(?:ed|es)?\b|通過|\bround\s+\d+\b)(?=\s*$|\s*[((]|\s*[,,—–]\s*[✅⛔❌])|[^—((::]{0,60}?\s*[—–]\s*(?:round\s+\d+|(?:superseded|pending)[^—]{0,30}?(?:round\s+\d+|verdict)|[^—]{0,40}?\btracked below\b(?=\s*$|\s*[((]|\s*[,,—–]\s*[✅⛔❌])|(?:✅\s*(?:PASS|Ready|Mergeable)|⛔\s*(?:Blocked|Needs revision)|❌\s*FAIL))))
Case-insensitive (/i) — `/codex-review-doc` pass is as much a receipt as Pass /codex-review-doc.
Three ways to be a receipt: a receipt word then a gate command; a gate command followed closely by
one; or a gate command whose line ends in an explicit verdict tail after a dash — — round 3,
— ✅ PASS, — ⛔ Blocked. That third branch is why a separator is not an unconditional boundary:
`/codex-review-fast` re-review after the round-2 fixes — round 3, ⛔ Blocked is a receipt whose
decisive token sits past the dash. What the tail must not be is prose — `/precommit` — Try script -> fallback has a dash and is an implementation requirement, and a bare ✅ is not enough
either (— ✅ 已驗證 stays substantive). Only a named verdict sentinel counts, and only as one of the six pairs above — the mark and the
word are matched together, not as a cross-product, so ✅ FAIL, ❌ Ready and ⛔ PASS are not
receipts. A contradictory sentinel is malformed text, and reading it as a receipt would hide a real AC from
the displayed count — or a gate lifecycle tail in the bounded form the table
above requires, because an unchecked gate AC recording why its gate has not run yet is still
bookkeeping, not work. Two real ones live in
docs/features/auto-loop-evolution/requests/2026-08-08-receipt-integrity-issues-9-10-11.md.
The bounded window still stops at ( and (, so a gate AC whose tail sits past a parenthetical
stays counted as work. Two real ones do:
docs/features/auto-loop-evolution/requests/2026-08-08-receipt-integrity-issues-9-10-11.md lines 860
and 878, `/precommit` then `/codex-review-doc` … (task #85) — pending …. These are known,
intentional exceptions, not oversights: widening past parentheses is where behavioural ACs live,
and the failure direction here overstates the displayed remainder rather than understating it. It
does not hold the lifecycle open — under the all-AC rule an unchecked receipt does that on its own.
Revisit only with a corpus measurement showing the widened form adds no false positive.
| Excluded — a receipt that a gate ran | Kept — the command is the subject of real work |
|---|---|
Pass /codex-review-doc(✅ Mergeable) |
`/precommit` — Try script -> fallback + graceful skip |
Pass `/codex-review-fast` → `/precommit` |
`/pr-review` 整合:自動呼叫 fast mode |
`/codex-review-doc` 通過 |
…Stop 回報的事實…且不含 `/codex-review-fast` |
AC-8: Pass /codex-review-doc … ✅ Verified |
…新增 10 個測試(…`/precommit` 路由…) |
`/codex-review-fast` round 1 — ⛔ Blocked |
Skill routing:支援至少 8 個 route target(…) |
`/codex-review-doc` pass |
`/precommit` runner 支援 ecosystem 偵測 — ✅ 已驗證 |
`/precommit` — ✅ PASS (comment_blocks, lint:fix, build, test) |
提供 copy-pasteable 修正指令(如 …) |
Every row is a real AC from this repo's requests/, and both columns are pinned by
test/skills/create-request-scan.test.js. The right column is what a position-only rule got wrong:
it dropped implementation work from the displayed count, so the dashboard understated what was left. The left column's last two rows are what a bold-label-only rule got wrong in
the other direction — a real receipt counted as work overstates the displayed remainder. It does
not hold the lifecycle open: by the all-AC rule an unchecked receipt keeps a ticket open on its own,
whatever this classifier says about it.
Known residuals. The published regex is looser than the prose above in places: forms like
Pass /precommit must preserve selected flags and `/precommit` — round 3 results must be persisted still match, because the terminator rule reaches the bare post-command markers but
not every route. These are accepted approximation residuals, not open defects. Chasing them
produced six refinements, each corpus-clean and each then shown to admit prose or drop a receipt;
the seventh attempt dropped 26 real receipts. Bounding the classifier to display and granularity
is what makes residuals affordable. The cost is a slightly wrong number on a dashboard, or an
advisory split signal that fires when it need not (false negative) or stays silent when it should
fire (false positive); the route that made them dangerous is closed. Tighten one only with a corpus measurement showing it
adds no false negative.
The classifier fails toward substantive — when an AC is genuinely ambiguous, keep it. Since the classifier no longer feeds status, the cost of either error is a display figure or an advisory split signal rather than a lifecycle decision; keeping an ambiguous AC still makes the count honest about what a reader can verify.
Decision Logic
signal_count = primary_count + 0.5 × secondary_count
< 2 → proceed as single request (no suggestion)
≥ 2 → suggest split (advisory AskUserQuestion)
≥ 3 → strongly recommend split
Split Suggestion
When triggered, use AskUserQuestion:
## Granularity Assessment
This request has {N} substantive acceptance criteria (target: ≤8, gate receipts excluded) and {layer_info}.
Suggested split:
1. {Title A} — {scope A} ({AC_count_A} AC)
2. {Title B} — {scope B} ({AC_count_B} AC)
Options:
- "Split into {N} requests" (Recommended)
- "Keep as 1 request"
Split by: layer (behavior vs code) if detected, then functional area if scope breadth detected, then balanced AC groups as fallback.
Sibling Request Output
When user accepts split, create indexed files: YYYY-MM-DD-{title-slug}-r1.md, ...-r2.md, etc. (e.g., 2026-03-18-auth-fix-r1.md, 2026-03-18-auth-fix-r2.md). Each gets its own AC subset (target ≤8 substantive, counted per § Pre-Render AC Count), scoped Related Files, and conditional > **Depends On**: header if dependency exists between siblings.
Create Mode: Interaction
If incomplete info, ask:
1. Feature area: Which feature? (e.g., auth, billing, notifications)
2. Title: Brief description
3. Priority: P0 (urgent) / P1 (high) / P2 (medium)
4. Background: Why is this needed?
5. Requirements: What needs to be done? (list)
6. Acceptance criteria: How do we know it's done?
Update Mode Workflow
Path resolution: --update supports three forms:
| Form | Behavior |
|---|---|
--update <path> |
Use explicit path (must match docs/features/*/requests/*.md) |
--update (no path) |
Auto-detect from feature context (see references/feature-context-resolution.md) |
--update <keyword> |
Resolve feature key, then find active request(s) |
Auto-detection logic (when no explicit path):
- Resolve feature context using the 5-level cascade —
node scripts/resolve-feature.js, the wrapper that owns the failure payload; the CLI behind it is not the entrypoint 1b.scan_errorgate —scan_error !== false⇒ the source sets are unknown, not empty. Report it and take the ⚠️ Need Human exit. This is the step that matters most here: an unreadablerequests/directory returns the same empty set as a feature with no tickets, so without the gate step 5 below reads it as "0 active requests" and creates a duplicate ticket beside the one it could not see. Gate on!== false, not=== true: a{}payload from a shell fallback carries no such field, so a non-nullkeyis not evidence of completeness - Scan
docs/features/<key>/requests/*.mdfor incomplete requests (Status not in[Completed, Done, Superseded, Archived]— the closed set is defined once inscripts/lib/request-status.js; keep this list identical toCLOSED_REQUEST_STATUS) - If exactly 1 active request → auto-select
- If multiple active requests → AskUserQuestion with numbered list
- If 0 active requests → offer to create new via create mode
- If feature not resolved → Gate: Need Human
Phase 0: Freeze -> Reparse Status. Closed (`CLOSED_REQUEST_STATUS`) -> no ordinary update: report frozen, exit.
One path continues: an explicitly authorized factual correction (Phase 4.5), which performs
that correction and nothing else, recorded in `Progress.Note`
Phase 1: Load -> Read existing request document
Phase 2: Analyze -> Analyze Related Files + git changes
Phase 2.4: Preflight -> § AC-Form Preflight (all modes, unconditional)
Phase 2.5: Verify -> (--verify-ac only) agent-based AC verification
Phase 3: Map -> Compare implementation with Acceptance Criteria
Phase 4: Update -> Update Progress / Status / Checkboxes
Phase 5: Report -> Output change summary
Phase 2: Analyze Implementation Progress
# Get changes for Related Files from request document
git log --oneline --since="<created_date>" -- <related_files>
# Check test status
grep -rE "describe|it\(" test/ --include="*<feature>*"
# Check review status
git log --oneline --grep="codex-review" -- <related_files>
AC-Form Preflight (all modes, unconditional)
This runs in every update mode — --update with or without --verify-ac, and --update-all
(its step 2). It is defined here, outside the verify-only phase, because that phase declares itself
"skipped otherwise": a reader following the mode instructions would otherwise skip the only
definition of the check and reach mutation logic with an unparsed AC set.
Order: Phase 0 freeze check → this preflight → any status, Progress-table or checkbox mutation.
That is the whole of what it gates, and the narrowness is deliberate. An authorized factual
correction — Phase 4.5's exception: a wrong path, a wrong date, an unfilled template placeholder —
runs after Phase 0 and does not pass through this preflight, because it derives nothing from the
AC set and asks nothing of it. Gating it here would revoke the one edit Phase 4.5 and
/update-docs § Step 1.5 both keep reachable, and revoke it exactly where it is needed most: a
ticket recording its ACs as an evidence table has no parsed checkboxes, so it would become the one
ticket whose wrong path can never be corrected. Such a correction changes the authorized fact and
Progress.Note only, and says so in the report.
Read the ticket's ACs per § Live Checkbox ACs. If there is no readable live checkbox AC set —
no ## Acceptance Criteria section at all
(docs/features/auto-loop-evolution/requests/2026-08-04-degraded-writer-lost-update.md is a real
one); the section present but containing no checkbox items; ACs recorded as an evidence table
(docs/features/scope-discipline/requests/2026-08-15-scope-discipline-implementation.md); or any
other form this procedure cannot parse — or the section contains a checkbox-like item outside that
grammar at all (* [ ], + [ ], 1. [ ], an item indented past three spaces), or mixes task-list
items with an evidence table — then no status mutation: report it and take the
⚠️ Need Human exit. Never call an unparsed AC set empty, and never derive a status from one —
"every AC is checked" is vacuously true of nothing, and that is how a ticket with no
ACs at all would be promoted.
A non-empty parse is not a complete one, which is why the unsupported-form clause is not
redundant with the empty-set clause. A section holding - [x] done beside * [ ] not done parses
to one item, all of them checked — the unchecked AC written in an unsupported marker does not fail
the check, it disappears, and the ticket promotes with outstanding work. Mixed representation is
refused for the same reason: whichever form this procedure cannot read is the form whose state stops
being counted. Refuse the section as a whole; never parse the part that happens to be readable.
Phase 2.5: AC Verification Agent (--verify-ac only)
Dispatched when --verify-ac flag is present on single-request --update. Supports auto-detected path via feature context 5-level cascade. Skipped otherwise (default path unchanged, <10 sec).
Input: AC_LIST is the complete live checkbox AC set the § AC-Form Preflight parsed (§ Live Checkbox ACs) — not filtered by § Quality-Gate AC Classifier. Filtering it here was the last status-path leak: gate ACs dropped out of the report, so the report could not carry one result per AC and the table read it as unaccounted — the classifier reaching status through report validity after being told it never decides status. RELATED_FILES from ## Related Files table.
Agent({
description: "Verify AC completion for <feature>",
subagent_type: "Explore",
prompt: `AC verification specialist.
AC_LIST: ${AC_LIST}
RELATED_FILES: ${RELATED_FILES}
For each AC: read code, verify implementation.
A ticket is a RECORD of work done at a point in time, not a description of today's code:
a Related File missing from the working tree is NOT evidence the AC was never met.
For every absent path, consult git history before concluding:
git log --diff-filter=D --oneline -- <path> # which commit deleted it
git show <deletion-commit>^:<path> | grep -n '<pattern>' # NOTE the ^ — the path does
# not exist AT the deletion commit; `git show <deletion-commit>:<path>` exits 128.
# For a merge commit pick the parent explicitly (^1 / ^2).
git log -S '<distinctive string>' --oneline -- <path> # find the introducing commit
Output per AC:
- Status: Complete | Complete (later removed) | Partial | Not Found | Inconclusive
- Evidence: file:line references (historical evidence as commit:file:line)
- Confidence: High | Medium | Low
- Gap (if Partial): what is missing`
})
Timeout: 60 sec hard limit. Unverified ACs on timeout marked Inconclusive.
Graceful degradation: Agent dispatch fails → warn the user and fall back to the git-based
heuristic (Phase 2 results). A failed dispatch is not a verification result — it means
--verify-ac did not run. So the run continues as ordinary --update: the decision table below
is skipped entirely, checkboxes come from implementation evidence exactly as they do without the
flag, and the ceiling is Candidate Complete (only a completed verification can set Completed).
Reading a failed dispatch as an "empty report" instead would send it into the invalid-report rules,
where Phase 4 forbids touching any checkbox — and the heuristic's whole job is to set them. Two
directives, two different outcomes for the same input; this sentence is which one wins.
A deleted subject is not an unmet AC. Verification runs against the tree as it is now, but the
ticket records the tree as it was. When a later change removes what an AC was about — this repo's
hook-lightweighting deleted hooks/post-tool-review-state.sh and hooks/session-init.sh in
0b3b8f5, and three test/hooks/*.test.js suites in 91b5fc9 (both 2026-08-13), all of them
named as Related Files by older P0 tickets — a naive run
returns Not Found for every one of them and the mapping above would push a finished ticket back
to In Progress. That is not a status update; it is falsifying the record, and it points the
reader at work that does not exist. Resolve such an AC through git history and record it as
Complete (later removed), naming the removing commit. If history cannot settle it, the AC is
Inconclusive — never Not Found, and never a downgrade.
Write that finding into Progress.Note, never into a new top-level metadata field. Phase 4.5
and skills/update-docs/SKILL.md § Step 1.5 agree that --update's mutable set is exactly four
fields — Status, the Progress table, AC checkboxes, Progress.Note — and adding a Note: or
Verification: line to the ticket's metadata blockquote edits the record itself. A verification
result is commentary on the work, so it belongs in the Progress table beside the phase it concerns.
Confidence-to-status mapping:
Ordered — the first matching rule wins. The rules are a decision procedure, not independent
tests: Inconclusive is a verdict while High / Medium / Low are confidence, so one AC
carries both and would match several independent descriptions at once.
In an accounted report, decisive verdicts drive the status directly; the boxes are consulted
only when the report yields no usable lifecycle conclusion — an invalid or unaccounted report — or
for Inconclusive. The accounting qualifier is not
decoration: an unaccounted report can still be full of decisive-looking verdicts — v3.0.12 records
seven Complete/High results for a nine-AC ticket — and rules 1–2 must ignore every one of them.
For Complete, Complete (later removed), Partial and Not Found in an accounted report the
report carries a
verdict and a confidence per AC, and Phase 4 updates the boxes from that same evidence, so reading
both would only invite them to disagree. Two earlier versions of this table read checkbox state for
those verdicts as well, and each needed a verdict→checkbox transition matrix before it was
deterministic: an AC reported Complete at Medium matched different rules depending on an
unwritten rule about what the checkbox became. Confining the boxes to the cases below removes that
question rather than answering it.
The boxes speak in two situations, and only two. The invalid-report rules, where the report
yields no usable lifecycle conclusion — and note the distinction: an unaccounted report is not an
empty one. It can carry real, valid findings (the two demoted tickets in this repo record 3-of-5 and
7-of-9 verified ACs), and those findings belong in Progress.Note. What it cannot do is settle the
lifecycle, because a conclusion drawn from a partial account is not a conclusion about the whole.
So the boxes decide the status and the partial evidence is kept rather than discarded. And
Inconclusive, which is the one verdict carrying no completion information — "nothing was
learned" is not evidence of done or not-done, so the preserved box is again the only thing that
speaks. An Inconclusive result on an unchecked AC therefore reopens the ticket, while the same
result on a checked one does not: collapsing those two into one status would advance unresolved
work to Candidate Complete while Phase 4 leaves its box unchecked — a ticket simultaneously
Candidate Complete and, by that status's own definition, not eligible for it.
The AC set is every live checkbox AC the ticket has (§ Live Checkbox ACs) — all of them, gate receipts included. This table does not consult § Quality-Gate AC Classifier: that classifier is an approximate reading of free text, and letting it decide status meant one misread could drop an AC from the set a ticket had to satisfy.
The set is accounted for when the report carries exactly one result per AC, in order, each with
a verdict from {Complete, Complete (later removed), Partial, Not Found, Inconclusive} and a
confidence from {High, Medium, Low}. A missing, duplicated, extra or malformed row means it is
not.
| # | Stage | Condition | Status |
|---|---|---|---|
| 1 | report validity | The report is empty, unparseable or unaccounted for, and any AC is unchecked | In Progress. The report settles nothing about the whole, so the ticket's own record stands, and it says the work is unfinished. Any partial findings it did carry go in Progress.Note |
| 2 | report validity | The report is empty, unparseable or unaccounted for, and every AC is checked | Candidate Complete, stating in Progress.Note that verification did not conclude |
| 3 | verdicts | Any AC Partial or Not Found |
In Progress |
| 4 | verdicts | Any AC Inconclusive on an unchecked AC |
In Progress. Nothing was learned, so the preserved box is the only evidence and it says the work is unfinished |
| 5 | verdicts | Any remaining Inconclusive (on an already-checked AC), or any confidence below High |
Candidate Complete + verification summary in Progress.Note |
| 6 | verdicts | Every AC is Complete or Complete (later removed) at High |
Completed. Record every removal commit in Progress.Note (the Acceptance row's Note cell) — one AC or twelve |
The table's domain begins after a successful § AC-Form Preflight. An unreadable AC set exits there and never reaches here, which is why no row covers it — a row that did would be dead.
Rules 1–6 exhaust the declared input space, so there is no catch-all row: rules 1–2 take every invalid or unaccounted report, and rules 3–6 take every combination of the five verdicts and three confidence values that an accounted report can carry. A row labelled "anything else" sat here until two independent reviews enumerated the space and found nothing that reached it — a fallback nothing can reach is not safety, it is a false impression of it. If a future verdict or confidence value is added, add its row rather than relying on a fallback.
Rule 6 is the only rule that yields Completed. It never sees a report that did not conclude,
because rules 1–2 have already taken those. There is no empty-set rule any more: the § AC-Form
Preflight already exits on a ticket with no readable ACs, and now that gate receipts are counted,
classification can no longer empty the set.
Every row names exactly one outcome — a row offering two would put the choice back where this table
exists to remove it.
Phase 3: Progress Mapping Rules
| Implementation Status | Progress Update |
|---|---|
| Related Files have commits | Development -> In Progress |
| Test files added/modified | Testing -> In Progress |
/codex-review-fast passed |
Development -> Done |
/precommit passed |
Testing -> Done |
| Every AC checked (§ Live Checkbox ACs — all of them) | Acceptance -> Done |
Phase 4: Auto-Update Items
Phase 0 and the § AC-Form Preflight must both have passed. --update reparses the Status before anything else and stops on a
closed ticket, exactly as batch mode's step 1 does — the ordering is a step in the declared
workflow, not a clause inside a table row, because a reader following the phases in order would
otherwise reach these mutations before Phase 4.5 tells them the record is frozen. The only path
that edits a closed ticket is the separately authorized factual correction Phase 4.5 defines.
| Section | Update Logic |
|---|---|
Status |
Canonical lifecycle: Pending → In Progress → Candidate Complete → Completed. The Candidate Complete invariant is stated below this table, once. Under --verify-ac the status is whatever Phase 2.5's decision table yields; do not maintain a second mapping here. That table reaches Candidate Complete by more routes than a summary keeps up with — an unaccounted report with every AC checked, a remaining Inconclusive on an already-checked AC even at High, and any confidence below High — which is why this row delegates instead of enumerating. Only that table's closing rule sets Completed. Normalize variants at creation or manual authoring only: In Development/In Dev → In Progress; Done → Completed. --update must not normalize Done: it is a member of CLOSED_REQUEST_STATUS (Phase 4.5), so a ticket carrying it is frozen and an update may change nothing on it — rewriting it to Completed is an edit to a closed record, not a normalization. The freeze check runs before every Phase 4 mutation in single-update mode exactly as it does at batch step 1 |
Progress table |
Update each phase status based on git changes |
Acceptance Criteria |
Under --verify-ac, the transition is per verdict and independent of confidence: Complete and Complete (later removed) → checked; Partial and Not Found → unchecked; Inconclusive → leave the box as it was (nothing was learned); an invalid or unaccounted report → change nothing. Without --verify-ac, check boxes from implementation/test evidence as before. This decides the boxes only. Phase 2.5's status table is driven by the report, with two documented fallbacks to the boxes — the invalid-report rules, and Inconclusive, which carries no completion information — so the two cannot disagree |
Progress.Note |
Add latest commit message summary |
Note (metadata) |
Creation and manual authoring only — --update must not write it. When a ticket is written or hand-edited, commentary about the Status belongs here rather than appended to the Status line: Status is compared by exact equality against a closed-status set, so any annotation reopens the request. --update's mutable set is the four rows above (Phase 4.5); an update's own commentary goes in Progress.Note. See references/template.md |
The Candidate Complete invariant. Candidate Complete means every AC is checked — all of them,
with no exception for gate receipts — and closure-grade verification has not concluded. § Quality-Gate
AC Classifier is display-only and is not consulted.
Phase 4.5: Freeze — a request ticket is a record, not a living document
A request ticket states what was asked for and what happened. That makes it a record: it is
appended to while the work runs, and it is never rewritten afterwards to match what the code later
became. Doc sync (/update-docs) does not touch it at all — see that skill's Step 1.5.
| Status | What --update may change |
|---|---|
Any status not in CLOSED_REQUEST_STATUS — isOpenRequestStatus() is the negation, so this covers Pending, In Progress, Candidate Complete, the variants Phase 4 normalizes (In Development, In Dev), Design, Proposed, and a Status that failed to parse |
Status, Progress table, AC checkboxes, Progress.Note — the fields above. Naming only the three canonical values here would leave every other open status admitted by Phase 0 with no mutable set at all, which reads as frozen and is the opposite of what the parser says |
Any member of CLOSED_REQUEST_STATUS — currently Completed, Done, Superseded, Archived |
Nothing. A closed ticket is frozen |
The closed set is CLOSED_REQUEST_STATUS in scripts/lib/request-status.js — the same list Scan
Mode filters on, and the only place it is defined.
Reopening is a decision, not an update: when work resumes on a closed ticket, say so and create a
new ticket that references it, rather than editing history so it reads as though it was never
finished. The one exception is a factual correction to the record itself — a wrong path, a wrong
date, or an unfilled template placeholder: text that was never a statement about this ticket at
all, such as a trailing **Status**: Pending / In Progress / … legend the author never replaced.
The exception authorizes only that correction, and its eligible targets are closed: a
non-lifecycle recorded fact (a path, a date, a reference), or the removal of an unfilled
placeholder. It must never change Status, a Progress phase status, or AC checkbox state —
those are the lifecycle fields, and they stay governed by the freeze, the AC-form preflight and the
ordinary transition rules whatever else is being corrected. Without that exclusion the exemption
swallows the rule it follows: a wrong Status on a closed ticket is a "fact" in ordinary language,
so an agent could relabel a lifecycle edit as a correction and walk straight past the preflight.
Unre
…(truncated)