> ## Documentation Index
> Fetch the complete documentation index at: https://xspec.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Renaming and Moving Requirements Safely

> Use xspec rename and xspec move to restructure your specification graph without breaking baselines, reviews, or cross-file references.

Renaming a node ID or relocating a section across files are common maintenance tasks, but hand-editing IDs breaks impact analysis, invalidates review sessions, and leaves dangling references across your codebase. xspec provides two commands — `xspec rename` and `xspec move` — that handle all rewriting atomically and record a journal entry so that baselines remain intact.

## Renaming a node ID

```sh theme={null}
xspec rename <file> <old-id> <new-id>
```

`xspec rename` rewrites the ID within the named file and cascades the change everywhere it matters:

* The section's own `id` attribute and all descendant IDs (by prefix replacement)
* Every reference to the old ID: `id` attributes, `d` dependency refs, `text(...)` targets in both MDX and TypeScript files
* TypeScript markers that cite the ID
* An entry in the identity journal at `.xspec/journal`
* All derived files are regenerated

The result is an **identity guarantee**: running `xspec impact --base <any-ref>` against a baseline that predates the rename produces an empty report. The journal maps the old ID to the new one, and impact analysis follows that mapping transparently.

<Warning>
  Type-only TypeScript references (e.g., a type alias that names the old ID) are **not** rewritten by `xspec rename`. These will surface as TypeScript compiler errors, which is intentional — they require a deliberate human decision about the type shape.
</Warning>

## Moving nodes

`xspec move` has two forms depending on whether you are relocating a whole file or extracting a section.

### File form

```sh theme={null}
xspec move <old-file> <new-file>
```

Relocates the entire source file to a new path. All node IDs stay unchanged. Because no IDs change and the journal records the file-level mapping, this is a **pure** operation: no hash changes, no impact report noise, no invalidated review items.

### Section form

```sh theme={null}
xspec move <file>#<id> <target-file>#<new-id>
```

Extracts the subtree rooted at `<id>` from its origin file and inserts it at the end of the target parent (or at the top level of the target file). The command:

* Removes the subtree from the origin file
* Inserts it into the target file (creating the file if it does not exist)
* Rewrites all references between local and imported forms as needed
* Records the mapping in the journal

The parent nodes of both the origin and the target will reflect a `descendant-changed` in the impact report for the parent nodes only — the moved subtree itself is journaled and invisible to impact.

## The journal

The journal lives at `.xspec/journal`. It is a plain-text, append-only file with one mapping entry per line, written exclusively by `xspec rename` and `xspec move`.

<Warning>
  **Never edit or delete the journal.** It is the source of truth for identity continuity. Hand-editing it will corrupt baseline comparisons and may cause `xspec check` to report errors. If the journal is damaged, restore it from version control.
</Warning>

Key properties:

* **Commit it.** The journal is a durable file — it is not regenerated from sources. It must be in version control alongside your spec files.
* **Concurrent branches merge cleanly.** Because the journal is append-only and each entry is independent, textual merge of concurrent branches works without conflicts in the common case.
* **`xspec check` validates it.** If the current journal is not a forward extension of the journal at a given baseline, `xspec impact` against that baseline exits with a hard error (exit code `2`).

## Refusal conditions

Both commands exit `1` without modifying anything if any of the following conditions hold:

* The workspace does not pass `xspec build` validation (build must be clean first)
* The new ID is invalid, already in use, or structurally inconsistent with its parent
* **Section move only:** the operation would create an import or dependency cycle, the destination file already exists (file form), the target parent node is missing or is inside the subtree being moved, or the destination path is not a valid spec source path

Because refused operations modify nothing, you can safely retry after correcting the issue. Run `xspec check` after any interrupted operation to confirm the workspace is consistent.

## Practical workflow

<Steps>
  <Step title="Keep content edits and structural changes in the same branch">
    You do not need to separate refactoring commits from content changes. xspec handles both in any order.
  </Step>

  <Step title="Use commands even for 'trivial' renames">
    A journal entry is cheap. Even renaming `auth.lockout` to `auth.lockout.v2` takes a fraction of a second and ensures zero impact noise in every baseline comparison going forward.
  </Step>

  <Step title="Verify with impact after refactoring">
    After a rename or move, confirm the identity guarantee holds:

    ```sh theme={null}
    xspec impact --base HEAD
    ```

    A rename or move that was fully journaled produces an empty report.
  </Step>
</Steps>

## Example

```sh theme={null}
$ xspec rename specs/AUTH.mdx auth.lockout auth.throttling
$ echo $?
0

$ xspec impact --base HEAD
baseline ba39f7296cccc1abc4c63ac33189505bb270857c
# empty report — the rename is journaled; baseline sees no change

$ xspec move "specs/AUTH.mdx#auth.throttling" "specs/THROTTLING.mdx#throttling"
```

The section is extracted from `AUTH.mdx` and placed into `THROTTLING.mdx`. All references are rewritten automatically, and the journal gains a second entry.