Menu
Use when the user wants to advance an entity (or acceptance criterion) to a new status, or step an AC's TDD phase. Runs `aiwf promote` so the transition is checked against the kind's legal moves and recorded as a single commit.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Closes an aiwf epic — verifies all milestones done, scaffolds a wrap artefact, harvests ADR candidates, runs scoped doc-lint, merges the epic branch into mainline with a trailered merge commit, promotes the epic to done. Use when the user says "wrap E-NN" or "close the auth epic" and every milestone in the epic is wrapped. Commit and push require explicit human approval.
Closes an aiwf milestone — verifies all ACs met, runs scoped doc-lint, finalizes the milestone spec's wrap-side sections, promotes status to done, prepares the wrap commit. Use when the user says "wrap M-NNNN" or "finish the cache milestone" and the readiness check per `aiwfx-start-milestone` has passed. Commit and push require explicit human approval.
The aiwf per-repo code-health ritual — the whole-codebase companion to wf-review-code's per-diff gate. A stack-agnostic field guide of code-health principles: module boundaries, contracts, data discipline, tests that pin behavior, errors/logs/audit, reasoning aids, operational properties. Use when designing a new module, planning a refactor, reviewing a non-trivial diff, writing a spec that introduces new boundaries, or scoring an inherited codebase Strong/Weak/Missing with file:line evidence. These are advisory forces, not rules — consult them, don't enforce them; the project's own conventions win.
Sets up and begins an aiwf milestone — preflight checks, branch setup, status promotion to in_progress, then iterative TDD via wf-tdd-cycle. Use when the user says "start milestone M-NNNN" or "implement M-NNNN" and a draft milestone spec exists. Commits and pushes require explicit human approval.
Use when terminal-status entities have accumulated in the active tree and the operator wants to sweep them into per-kind `archive/` subdirs, or when `aiwf check` reports `archive-sweep-pending`. Explains dry-run vs `--apply`, the no-reverse rule, the `archive.sweep_threshold` knob, merge edge cases, and the per-kind storage layout.
Use when the user wants to edit (rewrite or replace) the markdown body of an existing entity — goal/scope/context prose, AC body sections inside a milestone, ADR rationale, gap problem statement, etc. Runs `aiwf edit-body` so the change rides through a verb route with proper trailers, instead of a plain `git commit` that triggers a `provenance-untrailered-entity-commit` warning.
| name | aiwf-promote |
| description | Use when the user wants to advance an entity (or acceptance criterion) to a new status, or step an AC's TDD phase. Runs `aiwf promote` so the transition is checked against the kind's legal moves and recorded as a single commit. |
The aiwf promote verb edits an entity's status field — or, for composite ids, an AC's status or tdd_phase. Allowed transitions are hardcoded per kind; illegal moves are refused before any disk change. Promoting to the status already recorded is not an illegal move — it reports "already <status>" at exit 0 and commits nothing.
The user says something is "ready", "done", "in progress", "accepted", "deprecated", etc. — i.e. wants to move an entity from one status to another. Also for stepping an AC through red → green → done.
aiwf promote <id> <new-status> # top-level entity
aiwf promote <M-id>/AC-N <new-status> # AC status (composite id)
aiwf promote <M-id>/AC-N --phase <p> # AC tdd_phase (mutex with positional state)
| Kind | Statuses |
|---|---|
| epic | proposed, active, done, cancelled |
| milestone | draft, in_progress, done, cancelled |
| adr | proposed, accepted, superseded, rejected |
| gap | open, addressed, wontfix |
| decision | proposed, accepted, superseded, rejected |
| contract | proposed, accepted, deprecated, retired, rejected |
| AC status | open, met, deferred, cancelled |
AC tdd_phase | red, green, refactor, done (linear; refactor optional) |
aiwf promote enforces the per-kind legal-transition function. If the move is illegal it reports a finding and exits without writing; if the target status is the one already recorded there is no move to make, so it exits 0 having written nothing. To reach a terminal-cancel status use aiwf cancel <id> instead — same end state, clearer intent in the log.
When a transition the FSM disallows must happen anyway (rare), pass --force --reason "<text>":
aiwf promote E-01 done --force --reason "shipped without staging review for hotfix"
--reason is required (non-empty after trim) when --force is set. It becomes both the commit body and an aiwf-force: <reason> trailer, so the audit trail is queryable. --force relaxes only the FSM transition rule — coherence checks (status in closed set, refs resolve, AC body coherence) still run.
For milestones with open ACs, --force lets the milestone reach done but the standing aiwf check will keep surfacing milestone-done-incomplete-acs until the ACs reach a terminal state. The kernel reports the inconsistency every time; force only relaxes the verb-time refusal.
Two transitions require a pointer to what addressed the entity before the kernel considers the tree clean: gap → addressed (resolver-or-commit) and adr → superseded (replacement ADR). Pass the resolver via flag at promote time so the status flip and the resolver write land in one commit:
aiwf promote G-NNN addressed --by M-007 # gap closed by milestone (single id)
aiwf promote G-NNN addressed --by M-007,E-03 # gap closed by multiple entities
aiwf promote G-NNN addressed --by-commit abcdef1234 # gap closed by a specific commit (sha goes into addressed_by_commit)
aiwf promote ADR-NNNN superseded --superseded-by ADR-NNNN
| Flag | Field written | Valid when |
|---|---|---|
--by <comma-list> | addressed_by | gap → addressed |
--by-commit <comma-list> | addressed_by_commit | gap → addressed |
--superseded-by <id> | superseded_by | adr → superseded |
A flag/kind/status mismatch is a usage error (Go-error before any disk work), not a finding. The flags are mutex with --audit-only (audit-only is empty-diff by definition; resolver flags imply a mutation) and not valid in phase mode (resolver fields apply to entity status, not AC tdd_phase).
Use the verb route, not hand-editing: the gap-addressed-has-resolver and adr-supersession-mutual checks fire whenever the field is missing, and the verb route writes the field atomically with the status change so the standing check goes silent immediately.
When state was already reached via a manual git commit (no aiwf trailers), aiwf promote <id> <state> --audit-only --reason "..." records an empty-diff commit with the trailer block so aiwf history reflects the move. The verb refuses unless the entity is already at the named state — audit-only records what's true, not transitions. Mutex with --force. Human-only (the kernel refuses non-human actors). See aiwf-authorize and the G24 recovery story.
| Flag | When |
|---|---|
--actor <role>/<id> | Override the runtime-derived identity (default: human/<localpart-of-git-config-user.email>). |
--principal human/<id> | Required when --actor is non-human; forbidden when --actor is human/.... |
For agents acting under an active authorization scope, the kernel matches the scope automatically (no --scope flag) and stamps aiwf-on-behalf-of: + aiwf-authorized-by: on the commit. Open the scope first with aiwf authorize. Without an active scope, agent promotions refuse with provenance-no-active-scope.
When the scope-entity reaches a terminal status via aiwf promote (e.g., aiwf promote E-03 done), every active scope on that entity auto-ends — the commit carries one aiwf-scope-ends: <auth-sha> per ended scope.
acs[]. Everything else preserved.aiwf-verb: promote, aiwf-entity: <id> (composite for ACs), aiwf-to: <new-state> (status or phase), aiwf-actor: <actor>. aiwf-force: <reason> is added when --force is set, aiwf-audit-only: <reason> when --audit-only is set, plus the I2.5 provenance trailers (aiwf-principal, aiwf-on-behalf-of, aiwf-authorized-by, aiwf-scope-ends) where applicable.status: in markdown — the trailer chain disappears and aiwf history won't surface the move.proposed → done for an epic) without --force --reason. The legal-transition function refuses it by default; that's intentional.--phase with a positional new-status. Phase changes and status changes are separate transitions; the dispatcher refuses both at once.--phase on a top-level (bare) id. Phases are AC-only.--audit-only with --force — the two are mutually exclusive (audit-only records reality; force makes a transition happen).