verb

func Allow ¶

func Allow(in AllowInput) AllowResult

Allow runs the I2.5 allow-rule over the given inputs. Pure: no I/O, no git access. Returns a verdict the cmd dispatcher acts on.

Decision tree:

• Empty actor → denied (kernel never lets an unidentified operator commit; the cmd dispatcher should have refused earlier, but defensive). Reason: "actor is required".

• human/... actor: -> Principal must be empty (humans act directly; principal forbidden per the trailer-coherence rules). When non-empty, denied with "principal forbidden for human actor". -> Otherwise: Allowed = true, Scope = nil.

• non-human actor (ai/... / bot/...): -> Principal must be set (every agent needs a human accountor; enforced again by trailer coherence). When empty, denied with "principal required for non-human actor". -> Iterate Scopes (the union of active scopes attached to this actor). Pick the most-recently-opened that satisfies scopeAllows for the given (Kind, TargetID). On match: Allowed = true, Scope = the matching scope. On no match the denial is split (D-0014): if at least one active scope existed but none reached the target, Err is a *ScopeOutOfReachError (provenance-authorization-out-of-scope); if there was no active scope at all, Err is a *NoActiveScopeError (provenance-no-active-scope).

Per the design's "if multiple match, pick the most-recently-opened deterministically" rule, scopes are walked in reverse insertion order so the latest open wins.

func AsCoherenceError ¶

func AsCoherenceError(err error) (ce *CoherenceError, rule string)

AsCoherenceError returns the *CoherenceError if err is one (or wraps one), and the rule name; otherwise returns nil and "". Helper for callers (notably the standing rule in step 7) that switch on rule names rather than message text.

func Import ¶

func Import(ctx context.Context, t *tree.Tree, m *manifest.Manifest, actor string, opts ImportOptions) (*ImportResult, error)

Import processes a manifest against the existing tree and returns either findings (validation failed) or plans (validation passed, orchestrator should apply). Pure with respect to the filesystem; no writes happen here.

The processing pipeline is:

1. resolve --on-collision against entries with explicit ids that already exist in the tree (fail/skip/update).
2. detect intra-manifest duplicate explicit ids (always an error).
3. allocate auto-id entries from max(existing ∪ reserved) + 1.
4. resolve paths for every entry (new or updating an existing one).
5. project the tree (add or replace per entry) with PlannedFiles populated for every OpWrite path.
6. run projectionFindings; abort with findings if any error level issues are introduced.
7. assemble plans according to the manifest's commit mode.

func AcknowledgeIllegal ¶ added in v0.9.0

func AcknowledgeIllegal(ctx context.Context, root, sha, forEntity, actor, reason string) (*Result, error)

AcknowledgeIllegal records a retroactive sovereign override for a historical commit that one of the kernel's audit rules flags. The acknowledgment lives as a current-day empty commit carrying:

aiwf-verb: acknowledge-illegal
aiwf-force-for: <sha>
aiwf-actor: human/<name>
aiwf-reason: <free-form text>
aiwf-entity: <id>       (only when forEntity is non-empty)

The fsm-history-consistent rule (M-0136/AC-2) walks HEAD's reachable history for `aiwf-force-for` trailers and exempts illegal-transition findings whose offending commit appears as a target. Six other rules consume the same SHA set via the M-0159/AC-3 lift.

G-0231 item 3: a SEVENTH consumer rule — `provenance-untrailered-entity-commit` — was added with TIGHTER scope. Its findings are per-(commit, entity) pairs, so it requires per-(SHA, entity) acks: the ack commit must carry BOTH `aiwf-force- for: <sha>` AND `aiwf-entity: <id>`, and the verb verifies at write time that <sha>'s diff actually touches <id>'s file. The kernel-integrity property this adds: even if the operator (human or LLM) writes the wrong entity id with the right SHA, the verb refuses before the ack lands. SHA existence was already verified pre-G-0231 by shaAckable; entity binding is the new check.

Constraints (M-0136/AC-1, extended by G-0231 item 3):

• reason must be non-empty after trim (sovereign acts require a written rationale).
• actor must be `human/...` (sovereign acts trace to a named human; no LLM / bot ack).
• sha must match the 7-40-hex SHA pattern (the trailer's value constraint, enforced via gitops.ValidateTrailer).
• forEntity is OPTIONAL. When empty, the ack is per-SHA blanket (the legacy shape covering the first six rules). When set, the verb verifies <sha>'s diff touches <id>'s file and emits `aiwf-entity: <id>` in the ack commit (the per-(SHA, entity) shape required by provenance-untrailered-entity-commit).

M-0136/AC-4 + G-0236: sha must resolve to a real commit in the local object database (see shaAckable) — covering both a SHA still on trunk (the AC-4 case) and an orphan SHA reachable only via reflog (the G-0236 case: `isolation-escape-orphaned-ai-commit` findings' offending SHAs are by construction unreachable from HEAD, force-pushed-away tips surfaced via the reflog walker at internal/check/reflog_walk.go).

Typo guard preserved: a SHA that resolves to no commit is rejected. The per-SHA closed-set scoping (each ack covers only the named SHA, and rules only fire on SHAs they independently enumerated) bounds the silencing surface — accepting any object-DB-present SHA doesn't widen any rule's reach.

Returns a Result with a Plan carrying the empty commit's trailers. The Apply pipeline materializes the `git commit --allow-empty` once the human gate clears.

func AcknowledgeMistag ¶ added in v0.18.0

func AcknowledgeMistag(ctx context.Context, t *tree.Tree, id, actor, reason string) (*Result, error)

AcknowledgeMistag records a sovereign acceptance that an entity's area tag and its commits' landing zone legitimately disagree — the escape valve for the area-mistag check (M-0181/AC-6). Like AcknowledgeIllegal it is a current-day empty commit, but keyed per-ENTITY rather than per-SHA, carrying:

aiwf-verb: acknowledge-mistag
aiwf-entity: <canonical-id>
aiwf-actor: human/<name>
aiwf-reason: <free-form text>

The check's WalkAcknowledgedMistags walks HEAD for these commits and exempts the named entities from area-mistag. The acknowledgement lives in git (queryable via aiwf history), aligns with the existing sovereign-act semantics, and does not pollute aiwf.yaml — the same rationale as acknowledge-illegal.

Constraints (mirroring acknowledge-illegal):

• reason must be non-empty after trim (sovereign acts require a written rationale);
• actor must be `human/...` (no LLM / bot ack — the cross-cutting judgment is the human's);
• the id must resolve to a real entity (composite AC ids roll up to their milestone); a typo is refused rather than recording a no-op ack that silently suppresses nothing.

"What verb undoes this?" — none, by deliberate design (the acknowledge-illegal answer): the ack is one-way; if regretted, the operator re-tags the entity (`aiwf set-area`) so the mistag no longer fires, or lives with the suppressed finding. The verb is human-sovereign by construction.

func Add ¶

func Add(ctx context.Context, t *tree.Tree, kind entity.Kind, title, actor string, opts AddOptions) (*Result, error)

Add creates a new entity of the given kind. Allocates the next free id, builds the entity, projects it onto the tree, runs `aiwf check` against the projection, and either returns findings (no changes staged) or a Plan that the orchestrator applies.

For contracts with all three Bind* options set, Add additionally splices the binding into aiwf.yaml.contracts.entries[] and the returned Plan carries a second OpWrite so the entity creation and the binding land as a single commit.

Returns a Go error only when arguments are malformed (missing required option, parent epic not found, contract-only flag on non-contract kind, partial bind triplet). Tree-integrity issues arising from the addition are returned as findings, not errors.

func AddAC ¶

func AddAC(ctx context.Context, t *tree.Tree, parentID, title, actor string) (*Result, error)

AddAC creates a new acceptance criterion under the named milestone. Single-title convenience wrapper around AddACBatch — the existing signature is preserved so callers that want exactly one AC don't need to wrap their input in a slice. See AddACBatch for the batched-creation contract; this entry point applies the same rules with len(titles)=1. No body content is supplied; callers that want to populate the AC body in the same atomic commit use AddACBatch directly with a non-nil bodies slice.

func AddACBatch ¶

func AddACBatch(ctx context.Context, t *tree.Tree, parentID string, titles []string, bodies [][]byte, actor string) (*Result, error)

AddACBatch creates one or more acceptance criteria under the same milestone in a single atomic commit (M-057). Each title gets a consecutive AC id starting at len(parent.ACs)+1, position-stable per existing rules (cancelled entries count toward position). A matching `### AC-<N> — <title>` heading is appended to the milestone body for each created AC.

Every new AC is seeded at the pre-cycle empty phase regardless of the parent's tdd: policy — `red` means "a failing test exists," which a just-created AC has not written. The live "" -> red promote records the failing test.

Validation is whole-batch (M-057/AC-2): titles are checked first (empty-after-trim, not-prosey), then the milestone projection runs once with all N new entries; if any rule fires, the entire batch aborts with no commit. The plan returns exactly one OpWrite for the milestone file regardless of N (M-057/AC-4), so per-mutation atomicity is preserved.

The commit carries N `aiwf-entity:` trailers — one per created composite id, in allocation order (M-057/AC-3). `aiwf history M-NNN/AC-X` finds the commit because git's --grep matches any trailer line. The single-title invocation produces exactly one aiwf-entity trailer, matching pre-batch behavior (M-057/AC-5).

When bodies is non-nil and bodies[i] is non-empty, its bytes are appended under the matching AC's `### AC-N — <title>` heading in the same atomic commit (M-067/AC-1). Other AC-067 ACs (count validation, frontmatter rejection, stdin pairing) bring their own rules in subsequent cycles; the AC-1 cycle does only the wiring.

Returns a Go error for setup failures (empty titles slice, empty or prosey title, milestone not found, kind mismatch). Tree-level findings caused by the addition are returned in Result.Findings.

func Archive ¶ added in v0.8.0

func Archive(ctx context.Context, root, actor, kindFilter string) (*Result, error)

Archive sweeps terminal-status entities from the active tree into their per-kind `archive/` subdirectories per ADR-0004's storage table. The verb is multi-entity: one invocation rewrites every qualifying entity and produces a single commit (CLAUDE.md §7).

Behavior:

• Default is dry-run: the verb computes a Plan and the caller prints planned ops without applying. `--apply` (caller flag) causes the dispatcher to run verb.Apply on the Plan.
• Single commit per --apply per kernel principle #7. Trailer is `aiwf-verb: archive`; no `aiwf-entity:` trailer (multi-entity sweep, same shape as `aiwf rewidth`).
• Idempotent. An already-swept tree returns a NoOp Result; the caller prints "no changes needed" and exits 0.
• Sweep is by status, not by id. There is no positional id arg — ADR-0004 §"`aiwf archive` verb" rejects per-id housekeeping ("that would be a hand-edit detour, not a verb").

Per-kind storage table (verbatim from ADR-0004 §"Storage — per-kind layout"):

| Kind     | Active                              | Archive                                      |
|----------|-------------------------------------|----------------------------------------------|
| Epic     | work/epics/<epic>/                  | work/epics/archive/<epic>/ (whole subtree)   |
| Milestone| work/epics/<epic>/M-NNNN-<slug>.md  | does not archive independently — rides w/ epic|
| Contract | work/contracts/<contract>/          | work/contracts/archive/<contract>/           |
| Gap      | work/gaps/<id>-<slug>.md            | work/gaps/archive/<id>-<slug>.md             |
| Decision | work/decisions/<id>-<slug>.md       | work/decisions/archive/<id>-<slug>.md        |
| ADR      | docs/adr/<id>-<slug>.md             | docs/adr/archive/<id>-<slug>.md              |

`internal/entity/transition.go::IsTerminal` is the single source of truth for terminal statuses.

kindFilter scopes the sweep. "" sweeps every kind; a non-empty value must be one of entity.AllKinds().

func Authorize ¶

func Authorize(ctx context.Context, t *tree.Tree, id, actor string, opts AuthorizeOptions) (*Result, error)

Authorize runs the `aiwf authorize` verb. Refusal rules per docs/design/provenance-model.md §"The aiwf authorize verb":

• Actor must be human/...; only humans authorize.
• For AuthorizeOpen, the scope-entity must not be in a terminal status (overridable with Force + non-empty Reason).
• For AuthorizePause, an active scope on the entity must exist.
• For AuthorizeResume, a paused scope on the entity must exist.
• Reason is required for pause/resume (non-empty after trim); optional for AuthorizeOpen unless Force is set.

Each invocation produces exactly one commit. The commit's diff is empty; Plan.AllowEmpty makes Apply use `git commit --allow-empty`. The agent is recorded in `aiwf-to:` (consistent with the existing trailer schema: the scope is the "entity" being acted on, with its target state encoded by who can act under it).

func Cancel ¶

func Cancel(ctx context.Context, t *tree.Tree, id, actor, reason string, force bool) (*Result, error)

Cancel promotes an entity to its kind's terminal-cancel status — `cancelled` for epic/milestone, `rejected` for adr/decision, `wontfix` for gap, `retired` for contract. Errors when the entity is already in a terminal state or when the kind is unknown.

reason is optional free-form prose; when non-empty, it lands in the commit body so the cancellation's "why" is preserved for future readers. Empty reason matches today's body-less behaviour.

force=true emits an `aiwf-force: <reason>` trailer alongside the standard ones so the cancellation is auditable as a forced action. Cancel has no FSM transition rule to relax (it always sets status to the kind's terminal-cancel target), so force is purely an audit signal here. The "already at target" guard remains in place even under force — there is no diff to write. Force requires a non-empty reason; the caller is responsible for enforcing that.

func CancelAuditOnly ¶

func CancelAuditOnly(ctx context.Context, t *tree.Tree, id, actor, reason string) (*Result, error)

CancelAuditOnly records that <id> was cancelled via a path that bypassed the kernel. Refuses when the entity is not already at the kind's terminal-cancel target. Composite ids dispatch to cancelACAuditOnly (which checks against the AC `cancelled` state).

func ContractBind ¶

func ContractBind(ctx context.Context, t *tree.Tree, doc *aiwfyaml.Doc, current *aiwfyaml.Contracts, id, actor, repoRoot string, opts ContractBindOptions) (*Result, error)

ContractBind creates or replaces the binding for a contract entity in aiwf.yaml.contracts.entries[].

The verb is idempotent against an exact match (returns a NoOp result), errors out when the existing binding differs unless opts.Force is set, and validates that:

• the contract entity exists in the tree;
• the validator name is declared in aiwf.yaml.contracts.validators (unless current is nil — then the verb refuses, since there is no validator universe to choose from yet);
• the bound schema and fixtures paths exist on disk (G18) — verified by running contractcheck.Run on the projected config and surfacing any introduced contract-config findings as a Result with Findings populated. Without this projection check, the only enforcement was the pre-push hook (a watch-point violation per design-lessons §2).

On success, the returned Plan carries one OpWrite for aiwf.yaml with the spliced contracts: block; the orchestrator commits it with the bind trailers.

repoRoot is the consumer repo root, needed to resolve schema and fixtures paths for the existence check. The CLI dispatcher passes the same value it uses to load the tree.

func ContractUnbind ¶

func ContractUnbind(ctx context.Context, t *tree.Tree, doc *aiwfyaml.Doc, current *aiwfyaml.Contracts, id, actor, repoRoot string) (*Result, error)

ContractUnbind removes the binding for a contract from aiwf.yaml.contracts.entries[]. The contract entity is left untouched; its status governs whether pre-push verification still runs (it doesn't, once unbound). Errors when no binding exists.

t and repoRoot feed the shared diff-based gate (D-0041): unbinding can never resolve a missing-schema/-fixtures finding since it only removes an entry, but it can introduce a fresh no-binding warning on the now-unbound contract entity — the gate is a safety net that makes that visible rather than one more unchecked mutation path.

func EditBody ¶

func EditBody(ctx context.Context, t *tree.Tree, id string, body []byte, actor, reason string) (*Result, error)

EditBody replaces the markdown body of an existing entity file. The frontmatter is left untouched — that stays the domain of the structured-state verbs (promote, rename, cancel, reallocate).

M-058 introduced the explicit-content path; M-060 added bless mode. The verb has two modes, dispatched on body:

• body == nil: bless mode (M-060). Read the working-copy bytes and HEAD bytes, refuse if there is no diff (no changes to commit), refuse if the diff includes frontmatter changes (point at promote/rename/cancel/reallocate), commit the working-copy bytes verbatim with edit-body trailers. This is the natural human workflow: edit the file in $EDITOR, then bless the change with a verb route.

• body != nil: explicit-content mode (M-058). The supplied bytes replace the body; the verb re-serializes the existing entity frontmatter with the new body and writes the result. This is the AI/script workflow — the body content was drafted elsewhere and is supplied via `--body-file <path>` or stdin.

Both modes refuse leading-`---` content via validateUserBodyBytes, refuse composite ids, return one OpWrite, and emit the same trailer set (`aiwf-verb edit-body`, `aiwf-entity`, `aiwf-actor`).

reason is optional free-form prose; when non-empty it lands in the commit body so future readers can see *why* the body was rewritten, not just *what* changed.

Returns a Go error for "couldn't even start": id not found, composite id, body validation failure, no-diff in bless mode, frontmatter-changed in bless mode. Tree-level findings caused by the projection are returned in Result.Findings.

func MilestoneDependsOn ¶

func MilestoneDependsOn(ctx context.Context, t *tree.Tree, id string, deps []string, clearList bool, actor, reason string) (*Result, error)

MilestoneDependsOn writes the depends_on frontmatter array on a milestone. Closes the post-allocation half of G-072 (the create-time half is the --depends-on flag on `aiwf add milestone`).

Two modes, dispatched on `clear`:

• clear == false: replace-not-append. The supplied `deps` list becomes the milestone's depends_on. To add a single dependency to an existing list, the caller passes the full updated list.
• clear == true: empty the list. `deps` must be empty (the mutex is enforced by the dispatcher; this verb pins the contract).

Both modes emit one OpWrite with `aiwf-verb: milestone-depends-on` trailers, producing the kernel's per-mutation atomicity guarantee.

Each id in `deps` must resolve to an existing milestone; the verb refuses before the commit otherwise. Cycle detection stays at `aiwf check`'s layer — different concern, different chokepoint.

Forward-compatibility note: the verb shape `aiwf milestone depends-on M-NNN --on <ids>` is a clean subset of the future `aiwf <kind> depends-on <id> --on <ids>` cross-kind generalisation (G-073). The verb-name segment "milestone" is the *kind*; the generalisation extends to other kinds without renaming this verb.

reason is optional free-form prose; when non-empty it lands in the commit body so the rationale surfaces in `aiwf history`.

func Move ¶

func Move(ctx context.Context, t *tree.Tree, id, newEpicID, actor string) (*Result, error)

Move relocates a milestone from its current epic to a different epic. The id is preserved (so references in other entities still resolve); only the file's location on disk and the milestone's `parent:` frontmatter field change. One commit per move with trailers `aiwf-verb: move`, `aiwf-entity: <M-id>`, `aiwf-prior-parent: <old-epic>`, `aiwf-actor: …` so `aiwf history` can answer "where did this milestone come from?" from either the milestone's or the old epic's perspective.

Returns a Go error for "couldn't even start": id not found, kind not milestone, target epic missing or wrong kind, milestone already under the target epic. Tree-level findings caused by the move (e.g. a depends_on cycle introduced by the new neighborhood) are returned in Result.Findings.

func Promote ¶

func Promote(ctx context.Context, t *tree.Tree, id, newStatus, actor, reason string, force bool, opts PromoteOptions) (*Result, error)

Promote advances an entity's status. The transition is validated against the kind's FSM (entity.ValidateTransition) before any projection runs, so unknown statuses and illegal jumps are rejected with a clear error rather than as a `status-valid` finding.

reason is optional free-form prose explaining *why* the transition happens. When non-empty, it lands in the commit body (between subject and trailers) so future readers can see the why, not just the what. Empty reason produces a body-less commit.

force=true relaxes the FSM transition rule so any-to-any moves are permitted; coherence (closed-set membership of the target status, id format, ref resolution) still runs via projection findings, so promoting to an unknown status is still rejected. Force requires a non-empty reason; the caller (cmd dispatcher) is responsible for enforcing that. When force is set, the standard trailers gain `aiwf-force: <reason>` so the audit trail is queryable.

opts carries optional resolver pointers that need to be written in the same commit as the status change (see PromoteOptions). The resolver is validated against the entity's kind and the target status before any disk work — a mismatch is a Go error.

Returns a Go error for "couldn't even start": id not found, illegal transition (when not forced), resolver-flag/kind/status mismatch. Tree-level findings caused by the change are returned as a Result with non-empty Findings.

func PromoteACPhase ¶

func PromoteACPhase(ctx context.Context, t *tree.Tree, compositeID, newPhase, actor, reason string, force bool, tests *gitops.TestMetrics) (*Result, error)

PromoteACPhase handles `aiwf promote M-NNN/AC-N --phase <p>`. Advances the AC's tdd_phase along the linear FSM (red → green → (refactor →) done). Mutex with status changes — the dispatcher rejects passing both a positional state and --phase. force=true skips the FSM transition rule but coherence (closed-set membership of newPhase) still runs via projection findings.

Trailers: aiwf-to: carries the new phase value (same trailer as for status changes; the verb name + composite id make it unambiguous which dimension moved). aiwf-force: when forced.

func PromoteACPhaseAuditOnly ¶

func PromoteACPhaseAuditOnly(ctx context.Context, t *tree.Tree, compositeID, newPhase, actor, reason string) (*Result, error)

PromoteACPhaseAuditOnly is the audit-only variant of PromoteACPhase: refuses unless the AC's tdd_phase already equals newPhase. Same trailer + empty-commit shape as the status variant.

func PromoteAuditOnly ¶

func PromoteAuditOnly(ctx context.Context, t *tree.Tree, id, newStatus, actor, reason string) (*Result, error)

PromoteAuditOnly records that <id> reached <newStatus> via a path that bypassed the kernel (manual commit, import, etc.). Refuses when the entity is not already at newStatus — audit-only never transitions, only documents.

Composite ids dispatch to promoteACAuditOnly. Top-level ids run against the per-kind FSM only insofar as the closed-set membership of newStatus must hold (an unknown status is rejected).

func Reallocate ¶

func Reallocate(ctx context.Context, t *tree.Tree, idOrPath, actor string) (*Result, error)

Reallocate gives an entity a new id of the same kind, renames its file/dir to reflect the new id, and rewrites every reference to the old id — both in frontmatter and in body prose — across the whole tree, including the entity's own body.

The reference grammar (E-NN, M-NNN, ADR-NNNN, G-NNN, D-NNN, C-NNN) is regular and unambiguous, so prose rewriting is mechanical and safe. Word boundaries prevent false matches against longer ids (e.g., reallocating M-001 leaves M-0010 untouched).

The argument may be an id (e.g., "M-007") when unambiguous, or a repo-relative path (e.g., "work/epics/E-01-platform/M-007-cache.md") when the id is duplicated — required after a merge collision where two files share the same id.

The commit gets an aiwf-prior-entity: <old-id> trailer in addition to the standard three, so `aiwf history <old-id>` continues to find the entity's lifecycle even after the renumber.

func RecipeInstall ¶

func RecipeInstall(ctx context.Context, t *tree.Tree, doc *aiwfyaml.Doc, current *aiwfyaml.Contracts, name string, validator aiwfyaml.Validator, actor, repoRoot string, opts RecipeInstallOptions) (*Result, error)

RecipeInstall registers `validator` under `name` in aiwf.yaml.contracts.validators. The verb is idempotent on exact match (NoOp result), errors when an existing validator carries the same name with different fields unless opts.Force is set.

The returned Plan trailers carry one `aiwf-entity:` per binding currently referencing `name` in aiwf.yaml.contracts.entries[] so `aiwf history` for those contracts surfaces the recipe change.

t and repoRoot feed the shared diff-based gate (D-0041): installing a validator only touches contracts.validators, never entries[], so in practice the gate can never find an introduced finding here — it is wired in as a safety net, not because this mutation is expected to trip it.

func RecipeRemove ¶

func RecipeRemove(ctx context.Context, t *tree.Tree, doc *aiwfyaml.Doc, current *aiwfyaml.Contracts, name, actor, repoRoot string) (*Result, error)

RecipeRemove removes the named validator from aiwf.yaml.contracts.validators. Errors when one or more bindings in entries[] still reference the validator — the user must `unbind` or rebind those contracts first. That referential- integrity check runs before the shared gate and keeps its own precise error message (the milestone's constraint): the gate is an additional safety net on top, not a replacement for it.

func Rename ¶

func Rename(ctx context.Context, t *tree.Tree, id, newSlug, actor string, slugMaxLength int) (*Result, error)

Rename changes the slug portion of an entity's file or directory path. The id is preserved (per the design's "ids are immortal" invariant); the title in frontmatter is unchanged. Hand-edit the title in markdown if you want it to track the new slug.

For epic and contract (directory-based kinds), the directory itself is moved; nested files (milestones under an epic, the schema/ subdir under a contract) move with it. For file-based kinds, the single file moves.

For composite ids (M-NNN/AC-N), Rename dispatches to renameAC: the second argument is interpreted as a new title (not a slug), the AC's frontmatter title is updated, and the matching `### AC-<N>` body heading is rewritten in place. No path change.

Returns a Go error for "couldn't even start": id not found, slug produces an invalid path, source path missing on disk. Tree-level findings caused by the move are returned in Result.Findings. slugMaxLength caps the rewritten slug per `entities.title_max_length` (G-0102, kernel default 80). Title and slug share the same length budget so on-disk filenames and frontmatter titles stay in sync. Pass 0 from tests that don't care about cap policy.

func RenameArea ¶ added in v0.18.0

func RenameArea(
	ctx context.Context,
	t *tree.Tree,
	doc *aiwfyaml.Doc,
	members []config.Member,
	oldName, newName, actor string,
) (*Result, error)

RenameArea renames a declared workstream area (E-0044, M-0177). It rewrites the `areas.members` entry in aiwf.yaml from oldName to newName AND rewrites the `area:` frontmatter of every entity tagged oldName to newName, in one atomic commit — the same referential- integrity discipline `aiwf reallocate` applies to ids. Renaming an area by hand-editing aiwf.yaml would orphan every entity still carrying the old value (the `area-unknown` finding flags them and the grouping view buckets them into the untagged complement); this verb closes that hole.

members is the consumer's declared areas (the validated single source of truth from config.Load, passed by the CLI layer); the verb never invents members and reads it only to validate the rename. doc is the parsed aiwf.yaml the CLI loads for the comment-preserving splice, mirroring how ContractBind receives its aiwfyaml.Doc.

Validation (no Plan on failure, so nothing is written):

• oldName and newName are non-empty and distinct;
• oldName is a declared member;
• newName is NOT already a declared member.

The commit carries `aiwf-verb: rename-area`, one `aiwf-entity:` trailer per rewritten entity (sorted by id for determinism), and `aiwf-actor:`. The `aiwf-verb` trailer suppresses the untrailered- entity audit; the per-entity trailers make the rename appear in each affected entity's `aiwf history`. When no entity references oldName, only the verb+actor trailers ride along (an aiwf.yaml-only change).

What undoes this? The same verb with swapped args: after `rename-area platform infra`, `rename-area infra platform` restores the prior member name and every entity tag.

func Retitle ¶

func Retitle(ctx context.Context, t *tree.Tree, id, newTitle, actor, reason string, titleMaxLength int) (*Result, error)

Retitle updates the frontmatter `title:` of an existing entity (top-level kind) or AC (composite id). For top-level entities, the on-disk slug is also re-derived from the new title and the file is renamed atomically in the same commit (G-0108) — so frontmatter title and filesystem slug never drift apart. A canonical `# <ID> — <title>` body H1, if present, is rewritten to track the new title in the same commit (G-0083); bodies without a canonical H1 are left untouched, so an operator-shaped non-canonical heading is never silently clobbered. Use `aiwf rename` when you want a slug change without touching the title.

For composite ids (M-NNN/AC-N), Retitle dispatches to retitleAC, which updates the AC's title in the parent milestone's acs[] array AND regenerates the matching `### AC-<N> — <title>` body heading. Both changes land in one atomic commit per kernel rule. ACs have no slug, so no rename happens on the composite path.

reason is optional free-form prose; when non-empty it lands in the commit body so the rationale surfaces in `aiwf history`.

Returns a Go error for "couldn't even start": id not found, empty new title (after trimming), no-op (current title equals new title), or a title that slugifies to the empty string (e.g., punctuation- only). Tree-level findings caused by the projection are returned in Result.Findings.

titleMaxLength caps the new title per `entities.title_max_length` (G-0102, kernel default 80). Title and slug share the same budget; retitle is also the natural verb to migrate existing entities whose pre-cap titles are over the cap (the operator picks the shorter form). Pass 0 from tests that don't care about cap policy.

func Rewidth ¶

func Rewidth(ctx context.Context, root, actor string) (*Result, error)

Rewidth sweeps a consumer's active planning tree from narrow legacy id widths (E-NN, M-NNN, G-NNN, D-NNN, C-NNN) to canonical 4-digit width (E-NNNN, M-NNNN, G-NNNN, D-NNNN, C-NNNN). Per ADR-0008:

• Default is dry-run: the verb computes a Plan and the caller prints planned ops without applying. `--apply` (caller flag) causes the dispatcher to run verb.Apply on the Plan.
• Single commit per --apply per kernel principle #7. Trailer is `aiwf-verb: rewidth`; no `aiwf-entity:` trailer (multi-entity sweep, same shape as `aiwf archive`).
• Active-tree only. Files under `<kind>/archive/` are skipped entirely per ADR-0004's forget-by-default principle.
• Idempotent. An already-canonical or empty tree returns a NoOp Result; the caller prints "no changes needed" and exits 0.

The verb walks each kind's active directory in a fixed sequence (epic, milestone, gap, decision, contract, adr) and within a kind iterates in alphabetical order by current filename. Determinism is load-bearing: a second invocation on the same tree visits files in the same order and produces zero ops.

Three reference patterns are rewritten in active-tree markdown bodies:

• Bare id mentions in prose (`E-22` → `E-0022`). Word-boundary guarded so `E-220` doesn't match.
• Composite ids (`M-22/AC-1` → `M-0022/AC-1`).
• Markdown links to active-tree paths (`(work/epics/E-22-foo)`). Links targeting `<kind>/archive/...` are excluded by design.

Code fences (triple-backtick) and inline-code spans (single-backtick) are excluded from rewriting — content inside them stays as-is.

The F-prefix is included in the regex by spec (planned 7th kind from the §07 TDD architecture proposal). No F entities exist today, so it's a forward-compatible no-op for current consumers.

Rewidth does not call check.Run on a projected tree the way other verbs do: the operation is purely structural (rename + body rewrite) and `aiwf check` is the chokepoint for post-migration validation. The pre-push hook will run check after the user pushes the rewidth commit; spurious mid-verb check noise from a tree mid-rename is not what we want.

func SetArea ¶ added in v0.18.0

func SetArea(
	ctx context.Context,
	t *tree.Tree,
	members []string,
	id, member string,
	clearTag bool,
	actor string,
) (*Result, error)

SetArea points a single entity at an existing declared area member — or clears its area tag — in one trailered commit (E-0044, M-0183). It is the membership-change sibling of RenameArea: where RenameArea rewrites the *vocabulary* (a member's name, carrying every referrer), SetArea changes one entity's *membership* against a fixed vocabulary.

It is the guaranteed remediation for `areas.required` (M-0178): when the knob flags an untagged entity, `aiwf set-area <id> <member>` is the one-command unblock. It also owns the inverse — `aiwf set-area <id> --clear` untags an entity back to the untagged state (legitimate and never-flagged unless `areas.required` is set, under which an untagged entity is itself flagged by area-required), the clean correction for a mis-tag.

Two modes, dispatched on `clear`:

• clear == false: set the entity's area to <member>. <member> must be a declared member of `members` (the validated single source of truth the CLI passes from config.Load); the verb never invents a member (that is RenameArea's and config's job). With no areas block declared, `members` is empty and every member is undeclared, so a set refuses.
• clear == true: empty the area field. `omitempty` on entity.Area drops the cleared key on serialize, so the on-disk frontmatter returns to the untagged shape byte-for-byte.

Validation precedes any Plan, so a refusal writes nothing:

• a composite/AC id or a milestone target refuses — area derives from the parent epic; the message names the epic and the remediation command;
• an unknown id refuses;
• <member> and clear given together refuse (mutex);
• a non-empty <member> not in `members` refuses, naming the declared set;
• a no-op (already tagged <member>, or --clear on an already-untagged entity) refuses.

The commit carries `aiwf-verb: set-area`, `aiwf-entity: <canonical id>`, and `aiwf-actor:`. The verb trailer suppresses the `provenance-untrailered-entity-commit` audit a hand-edit would trip — the whole point of the verb, for tag, retag, AND untag.

What undoes this? The same verb, total: a tag (untagged→tagged) reverses with `--clear`; a retag reverses with the prior member; a `--clear` reverses by setting the prior member. One verb owns one field with a complete reversal story.

func SetPriority ¶ added in v0.27.0

func SetPriority(
	ctx context.Context,
	t *tree.Tree,
	id, level string,
	clearTag bool,
	actor string,
) (*Result, error)

SetPriority points a single gap or decision at a closed-set priority level — or clears its priority tag — in one trailered commit (G-0078, E-0066, M-0262). It is the write-surface sibling of SetArea: where SetArea validates <member> against a config-declared set, SetPriority validates <level> against the fixed Go-hardcoded set (entity.IsAllowedPriorityLevel) — the same SSOT predicate the priority-valid check rule reads, so there is no parallel value check here.

Two modes, dispatched on `clear`:

• clear == false: set the entity's priority to <level>. <level> must be one of entity.AllowedPriorityLevels().
• clear == true: empty the priority field. `omitempty` on entity.Priority drops the cleared key on serialize, so the on-disk frontmatter returns to the unset shape byte-for-byte.

Validation precedes any Plan, so a refusal writes nothing:

• an unknown id refuses;
• a target whose kind does not carry a priority (!CarriesOwnPriority) refuses — priority is legal only on gap and decision;
• <level> and clear given together refuse (mutex);
• an out-of-range <level> refuses, naming the allowed set;
• a no-op (already set to <level>, or --clear on an already-unset entity) refuses.

The commit carries `aiwf-verb: set-priority`, `aiwf-entity: <canonical id>`, and `aiwf-actor:`. The verb trailer suppresses the `provenance-untrailered-entity-commit` audit a hand-edit would trip — the whole point of the verb, for set, reset, AND clear.

What undoes this? The same verb, total: a set (unset->set) reverses with --clear; a reset reverses with the prior level; a --clear reverses by setting the prior level. One verb owns one field with a complete reversal story.