| name | aiwf-retitle |
| description | Use when the user wants to fix or change an entity's title — "the title doesn't match anymore", "fix the title", "retitle to reflect new scope", "correct the title", or change an AC's title inside its parent milestone. Runs `aiwf retitle` so the frontmatter mutation rides through a verb route with proper trailers, instead of a hand-edit that triggers a `provenance-untrailered-entity-commit` warning. |
aiwf-retitle
The aiwf retitle verb updates the frontmatter title: of an existing entity (any of the six top-level kinds) or AC (composite id), in one atomic commit. For top-level entities whose slug still tracks the title, the on-disk slug is re-derived from the new title so the filesystem stays in sync; a slug you chose with aiwf rename is preserved instead, so renaming for a shorter path is not undone by a later retitle. Any canonical # <ID> — <title> body H1 is rewritten to track the new title — H1 sync is a no-op when the body has no H1 or carries an operator-shaped non-canonical heading. For composite ids the matching ### AC-N — <title> body heading is regenerated.
When to use
Scope refactors that change an entity's intent leave the frontmatter title: stale. The slug can be corrected via aiwf rename, but the title — which is what humans read in aiwf status, aiwf show, aiwf history, and the roadmap — stays misleading. aiwf edit-body can't fix it (frontmatter is off-limits to that verb). Plain git commit against the entity file triggers provenance-untrailered-entity-commit on the next aiwf check. aiwf retitle is the verb-route answer.
Triggers:
- "the title doesn't match anymore"
- "fix the title"
- "retitle to reflect new scope"
- "correct the title"
- "rename the title" — this phrasing overlaps with
aiwf-rename. Title and slug are different fields; aiwf-rename does slugs only. If the user means the title (the prose label), this is the right verb. If they mean the slug (the path component), use aiwf-rename.
What to run
aiwf retitle <id> "<new-title>" [--reason "..."]
aiwf retitle M-NNN/AC-N "<new-title>" [--reason "..."]
Two positional arguments matching aiwf rename's shape: id (or M-NNN/AC-N), new-title. The optional --reason flag lands in the commit body and surfaces in aiwf history, matching the pattern from aiwf promote/cancel/authorize/edit-body.
What aiwf does
- Looks up the entity (or AC) by id.
- For top-level entities: rewrites the frontmatter
title: field; re-derives the on-disk slug from the new title and renames the file/dir in the same commit, but only when the current slug is still the one the current title derives — a slug you chose with aiwf rename is left alone; and rewrites a canonical # <ID> — <title> body H1 if one is present. Non-canonical H1s and bodies without an H1 are left untouched.
- For composite ids: rewrites the AC's
title inside the parent milestone's acs[] AND regenerates the matching ### AC-N — <new-title> body heading. Both happen in one atomic file write.
- Validates the projected tree before touching disk; if a finding would be introduced, aborts with no changes.
- Creates one commit with
aiwf-verb: retitle, aiwf-entity: <id> (or <id>/AC-N for composite ids), aiwf-actor: <actor> trailers.
The body prose under ## Goal, ## Scope, etc. and the id are unchanged. To change those, use a different verb: aiwf edit-body for body prose; aiwf reallocate for id. aiwf rename stays the slug-only verb for when you want a different path without touching the title — and the slug it sets is durable, because a later retitle preserves any slug that no longer tracks the title.
Validation
- Empty new title (after trimming whitespace) is rejected with a usage error.
- Same-as-current title reports "nothing to retitle" at exit 0 and commits nothing, provided the canonical body H1 already matches it. When the H1 has drifted, the same command rewrites it and commits — the title is not the only surface being compared.
- Unknown entity id is rejected.
- Unknown AC id (e.g.
M-001/AC-99 when the milestone has fewer ACs) is rejected.
Don't
- Don't hand-edit frontmatter to "skip the verb" —
aiwf history won't show the retitle and the next aiwf check will surface provenance-untrailered-entity-commit.
- Don't use
aiwf retitle for slug-only changes when the title is fine — that's aiwf rename. (Retitle re-derives the slug only while the slug still tracks the title. Once aiwf rename has set one, retitle preserves it; to put an entity back on the title-derived path, aiwf rename it to that slug.)
- Don't expect the body prose under
## Goal, ## Scope, etc. to track the new title. That's aiwf edit-body's job. (The canonical # <ID> — <title> H1 is synced; sub-section prose is not.)
