artgraph-rename

name	artgraph-rename
description	Performs a safe rename / split / merge of requirement IDs across spec, code, tests, and lock. Use when the user asks to rename a REQ ID, split one ID into multiple, or merge multiple IDs into one. Make sure to use this skill whenever requirement IDs are being restructured.
allowed-tools	["Bash(npx artgraph *)","Bash(npx --no-install artgraph *)","Bash(pnpm exec artgraph *)","Bash(bunx artgraph *)","Bash(bunx --no-install artgraph *)","Bash(deno run -A npm:artgraph/cli *)","Bash(artgraph *)","Bash(git status*)"]
user-invocable	true
disable-model-invocation	false

Purpose

The agent runs artgraph rename (or its --split / --merge variants) to safely rewrite a requirement ID across spec lists/headings, @impl tags, test [ID] tags, frontmatter depends_on / derives_from, and .trace.lock. The operation is destructive and writes directly to tracked files — always run --dry-run first.

Exit code 1 does not always mean "it failed." rename also exits 1 on a partial success: the rewrite is complete and correct, but some reference it cannot reach was left behind (a task's requirement list — see step 3). Read the output, not just the status, in both --dry-run and apply mode.

Preconditions

• Working tree must be committed — artgraph rename writes directly to tracked files, and an uncommitted state makes the change irreversible.
• Target IDs must be in a form artgraph re-scans: REQ-001, auth/FR-2, doc:xxx. Forms like REQ-COMBINED or REQ-001a are rejected.

Steps

1. Prerequisite check

See install-check for the standard pre-flight check. If artgraph is not installed, stop and invoke the artgraph-setup Skill instead.

<PM-exec> is the project's package runner: npx (npm), pnpm exec, bunx, or deno run -A npm:artgraph/cli. Substitute the one detected by _shared/package-manager.md (or written in .artgraph.json#packageManager).

2. Confirm git is clean

git status --porcelain

The output must be empty. If anything is listed, instruct the user to commit (or stash) before continuing — rename mutates tracked files in place and a dirty tree mixes manual edits with the rewrite.

3. Dry-run the rewrite

Pick the command shape that matches the user's intent and add --dry-run:

# rename
<PM-exec> rename --from REQ-001 --to REQ-100 --dry-run
# split (1 → many)
<PM-exec> rename --split REQ-001 --into REQ-101 REQ-102 --dry-run
# merge (many → 1)
<PM-exec> rename --merge REQ-001 REQ-002 --into REQ-100 --dry-run

The dry-run prints the files, lines, and lock keys that will change. Show the diff summary to the user and get explicit confirmation before applying.

Check the exit code, and do not read it as pass/fail. --dry-run writes nothing, yet it can still exit 1:

exit	output	meaning	what to do
0	the preview	the rewrite reaches everything	proceed to step 4
1	{ "error": ... } (or an ERROR: line)	validation failed, nothing was previewed	fix the input; do NOT apply
1	the normal preview plus one or more WARNING: lines	partial success ahead — the rewrite is correct as far as it goes, but some references will be left pointing at the old ID	show the warnings to the user, then decide together whether to apply

The last row is the one that trips scripts. The usual cause is a task's requirement list (e.g. Kiro's _Requirements: 1.1, 2.3_ in tasks.md), which rename does not rewrite; with --format json it appears as warnings[].type === "unrewritten-task-requirement-ref" with the exact file paths. Never treat --dry-run's exit code alone as "the rename is unsafe" — distinguish the rows above by whether an error envelope or a preview was printed.

4. Apply

Re-run the same command without --dry-run. The lock is auto-reconciled — contentHash, references, and specFile for the rewritten nodes are refreshed in .trace.lock.

The apply run exits 1 under the same partial-success condition as step 3, after the files are already written. That is not a rollback signal: fix the references the warning names by hand (renumber the task's requirement list to match the new ID), then run <PM-exec> reconcile and continue.

5. Follow-up

For split and merge, additional manual work is required (new @impl assignments, scaffold TODO lines, leftover sub-bullets from old headings). See lifecycle-flows for the full handling.

For a plain rename, no follow-up edits are needed.

6. Re-check

<PM-exec> check

• rename and merge should pass immediately.
• split leaves the new IDs as uncovered until @impl is added at the candidate files. Re-run <PM-exec> check after assigning the tags.

Output format

Pass --format json for scripted use; on error the payload is { "error": "..." }. See output schema for the success shape of artgraph rename.