Migrate

Spec 008 created this skill from scratch. The deterministic filesystem walk + verdict logic + report rendering live in migrate.py; this SKILL.md drives the judgment layer (when to invoke, how to interpret ambiguities, what operations to suggest in what order).

What this skill does

Closes the "already spec-driven" gap that scaffold-init doesn't handle: projects that organically grew the same workflow jig codifies but landed on different conventions (folder names, filename prefixes, slice topology). Direct example: a project with docs/slices/ (flat) and docs/decisions/ (validator-style) — scaffold-init would not detect it as scaffolded and would either refuse confusingly or pollute the tree.

migrate flips that around: detect existing shape first, then propose a migration plan, then (in later slices) apply the rename / restructure operations.

migrate.py exposes six subcommands:

• report — strictly read-only inventory + plan.
• adopt-layout — validates an existing custom-root corpus and writes only its scaffold.json sentinel/config; supports --dry-run.
• rename-decisions — applies ADR-0004's rename. Idempotent; refuses on conflict; has a --dry-run mode; --host claude|codex selects whether cross-reference rewrites scan CLAUDE.md/.claude/ or AGENTS.md/.codex/.
• split-slices — extracts embedded slice sections into sibling slice files.
• seed-decisions — seeds docs/decisions/lightweight-decisions.md from jig's template. Idempotent; supports --dry-run and --docs-root; never overwrites an existing file.
• copy-machinery — copies jig runtime machinery into the target's host-local scaffold runtime; --host claude writes .claude/, and --host codex writes .codex/.

How to use

Run the migration report

python3 "${CLAUDE_PLUGIN_ROOT}/skills/migrate/migrate.py" report \
  <project-dir> [--docs-root <relative-root>]

• <project-dir> — path to the project root (e.g. /path/to/repo, . for cwd).
• --docs-root . — inventory a track-local corpus whose specs/, decisions/, workflow.md, and architecture.md live directly under the selected subproject instead of under docs/.

Adopt an existing custom-root corpus

Preview first, then apply:

python3 "${CLAUDE_PLUGIN_ROOT}/skills/migrate/migrate.py" \
  adopt-layout <subproject-dir> --docs-root . --dry-run
python3 "${CLAUDE_PLUGIN_ROOT}/skills/migrate/migrate.py" \
  adopt-layout <subproject-dir> --docs-root .

The operation refuses incomplete/ambiguous corpora and existing or malformed sentinels before mutation. Apply writes only <subproject-dir>/scaffold.json using scaffold-init's canonical manifest builder; it does not move or rewrite the existing artifacts. Afterward, workflow.py transition, status-board, and ADR helpers discover the subproject through that sentinel.

Run the rename-decisions migration

Once report has been reviewed and the verdict is adoptable, the recommended sequence is:

# 1. Preview the plan (no writes).
python3 "${CLAUDE_PLUGIN_ROOT}/skills/migrate/migrate.py" \
  rename-decisions <project-dir> --dry-run

# 2. After reviewing the planned operations, apply them.
python3 "${CLAUDE_PLUGIN_ROOT}/skills/migrate/migrate.py" \
  rename-decisions <project-dir>

What it does, in display order:

1. docs/adrs/ → docs/decisions/ (directory rename, atomic).
2. Per-file renames: NNN-<slug>.md → adr-NNNN-<slug>.md (pad 3-digit to 4-digit; add adr- prefix where missing).
3. Cross-reference rewrites in text files under docs/, CLAUDE.md, and .claude/ by default. With --host codex, rewrites scan docs/, AGENTS.md, and .codex/ instead. The helper itself (migrate.py and its fixtures) is never rewritten.

Refusal cases (exit 2, no mutations):

• Both docs/adrs/ and docs/decisions/ present (manual merge first).
• Two source files normalize to the same target name (collision).
• <project-dir> missing, not a directory, or unreadable.

No-op cases (exit 0):

• Neither dir present, OR all files already on the canonical shape — emits "already aligned: nothing to do" and returns.

Run the seed-decisions operation

seed-decisions backfills docs/decisions/lightweight-decisions.md — the home /jig:memory-sync's decisions.py add-lightweight records into, and the one the Stop-hook decision nudge points at.

Reach for it when report flags the gap, or when a project's add-lightweight fails because the file is missing. Every project that adopted jig before the lightweight-decisions feature landed needs it: scaffold-init seeds the file only at init and cannot be re-run on an already-scaffolded project, so there was previously no supported way to obtain it (bug 012 / #109).

# preview
python3 "${CLAUDE_PLUGIN_ROOT}/skills/migrate/migrate.py" \
  seed-decisions <project-dir> --dry-run

# apply
python3 "${CLAUDE_PLUGIN_ROOT}/skills/migrate/migrate.py" \
  seed-decisions <project-dir>

Idempotent — a second run reports "already present" and exits 0.

It never overwrites. If the file exists but is not in jig's format (no ## Entries heading — typically a hand-rolled table an agent invented from the old shapeless nudge), the command refuses with exit 1 and names both ways out: add an ## Entries heading to the existing file (entries append at end-of-file, so existing content is undisturbed), or move it aside, re-run, and port the entries into the seeded template. Deciding which is a judgment call about the owner's content — make it with the owner, not for them.

Run the copy-machinery operation

copy-machinery brings a migrated project to scaffold-mode parity — the same host-local runtime shape /jig:scaffold-init produces by default for greenfield projects. See the dedicated section ## Copying machinery into your project below for the full description.

Quick reference:

python3 "${CLAUDE_PLUGIN_ROOT}/skills/migrate/migrate.py" \
  copy-machinery <project-dir>

Exit codes

• 0 — verdict is adoptable OR not-yet-spec-driven (the report is the deliverable regardless of verdict).
• 1 — verdict is partial (borderline; report still emits, but /jig:scaffold-init may be a better fit).
• 2 — user error (missing argument, dir doesn't exist, target is a file not a directory).

Verdict logic

migrate counts four migration triggers in <project-dir>:

1. Spec-or-slice dir (docs/specs/ or docs/slices/).
2. Decision-or-ADR dir (docs/decisions/ or docs/adrs/).
3. Workflow doc (docs/workflow.md).
4. Architecture doc (docs/architecture.md).

Report structure

Six sections, in fixed order:

1. Inventory — table of detected artifacts (paths + counts + shape notes). Inventories everything the helper found, including items that are inventoried-only (spikes, custom skills, custom agents).
2. Mapping — table of "current path/name → jig target name". For ADR files this includes the 3-digit-to-4-digit pad and the adr- prefix add (per ADR-0004). For flat slices, the row points to the Ambiguities section because no automated topology mapping exists in slice 008-01.
3. Conflicts — situations that block specific migration operations (e.g. docs/adrs/ AND docs/decisions/ both present means rename-decisions refuses on this project). Empty if no conflicts.
4. Ambiguities — judgment calls the user must make. Common entries: "flat slices reference M1–M6 milestones — map each to a parent spec?"; "custom skills overlap jig's stock set — replace or layer?"; "CLAUDE.md is 59KB with sprint log — port subset or leave?"; "N ADRs use a status format the → DONE gate can't read" (a bare inline **Status:** Accepted line is neither frontmatter status: nor a ## Status section, so the first ADR-dependent → DONE transition would refuse — add one of those two encodings). Note that adoptable attests to directory/filename structure, not deep per-artifact format conformance; this Ambiguities entry is how the report surfaces the ADR-status gap the verdict alone can't.
5. Contract surfaces detected — (added by spec 022-02) flags external-interface artifacts already on disk and prose API contracts that would benefit from standard schemas (OpenAPI / JSON Schema / AsyncAPI / .proto / GraphQL SDL). Four detection types: (a) existing schema artifacts, (b) prose API contracts in canonical doc files, (c) env-contract triple (markdown + .env.example + checker), (d) hand-typed boundary types (e.g. problem-details.ts). Each detected surface gets a one-line classification + recommendation; "No contract surfaces detected" prose when empty. Companion to the /jig:contracts skill's per-surface recommendation table.
6. Operations — ordered list of migrate.py <subcommand> calls the user should run, with --dry-run first. For slice 008-01, the only operations mentioned are future subcommands marked (slice 008-NN, not yet implemented) — so the report's main value right now is the first five sections.

When to invoke

Auto-trigger phrases (in this SKILL.md's description):

• "migrate this project to jig"
• "adopt jig here"
• "this repo already has specs — set up jig"
• "scaffold-init refused — what now"
• "introduce jig to an existing codebase"

Typical session flow:

1. User invokes the skill against an existing project.
2. Helper runs migrate.py report <dir>.
3. SKILL.md (this file's body) helps interpret ambiguities: what's a real conflict vs. just an open question? What's safe to defer?
4. User makes the judgment calls flagged in Ambiguities.
5. Once future slices land (008-02 rename-decisions, 008-04 slice-to-spec), the user runs those operations from the report's suggested order, with --dry-run first.

End-to-end example

# 1. Inventory the project.
python3 .../migrate.py report /path/to/existing-project

# Expected output (when 3+ triggers are present):
#
#   # Migration report — `/path/to/existing-project`
#
#   **Verdict:** adoptable
#
#   _Three or more migration triggers detected. Proceed with the
#   operations below._
#
#   ## Inventory
#
#   | Path | Count | Note |
#   |------|-------|------|
#   | `docs/slices/` | 27 | flat slice files (validator-style) |
#   | `docs/decisions/` | 22 | decision records (ADR-0004 aligned) |
#   | `docs/spikes/` | 4 | spike memos (inventoried only) |
#   | `docs/workflow.md` | 1 | workflow doc present |
#   | `docs/architecture.md` | 1 | architecture doc present |
#   | `CLAUDE.md` | 1 | 59231 bytes (larger than baseline) |
#
#   ## Mapping
#
#   | Current | jig target | Note |
#   |---------|------------|------|
#   | `docs/decisions/` | `docs/decisions/` | kept (already aligned) |
#   | `docs/decisions/adr-001-foo.md` | `docs/decisions/adr-0001-foo.md` |
#       pad to 4-digit + ensure `adr-` prefix |
#   | `docs/slices/slice-NN-*.md` (27 files) | topology question |
#       no automated mapping in 008-01 |
#
#   ## Conflicts
#
#   _None detected._
#
#   ## Ambiguities
#
#   - **Flat slices reference 6 milestone(s) (M1, M2, M3, M4, M5, M6).**
#     Under jig's nested model, each could become a parent spec...
#
#   ## Operations
#
#   Suggested order (each operation is `--dry-run` first):
#
#   1. **`migrate.py rename-decisions <dir>`** (slice 008-02, not yet
#      implemented) — apply ADR-0004 rename...
#   2. **`migrate.py slice-to-spec <dir>`** (slice 008-04, not yet
#      implemented) — interactively map flat slices...

Copying machinery into your project

copy-machinery brings a migrated project to scaffold-mode parity — the same host-local runtime shape /jig:scaffold-init produces by default for greenfield projects. After running it, the project owns its own copy of jig's skills, agents, hook scripts, templates, and hook registration. The dev can edit those files in their own repo, and they ride along under version control.

When to use it:

• After rename-decisions has applied ADR-0004 to existing ADRs.
• After split-slices has split any monolithic spec.md files with embedded slices into the file-per-slice layout.
• Standalone, when a project already has spec-driven layout but the dev wants the machinery in their tree (rather than only in the installed plugin under ${CLAUDE_PLUGIN_ROOT}).

migrate.py report will surface this subcommand in the Operations section when the verdict is adoptable or partial and the default host scan does not find pre-existing jig-managed skills. Codex users can also run the explicit copy-machinery --host codex command when they want Codex runtime machinery even if the conservative report wording is not the deciding signal.

Host selection:

• --host claude writes Claude scaffold machinery under .claude/ and is the source-checkout default.
• --host codex writes Codex scaffold machinery under .codex/.
• --host auto is the CLI default; helpers copied under .codex/skills/ infer Codex, and all other invocations infer Claude.

How to run it:

python3 "${CLAUDE_PLUGIN_ROOT}/skills/migrate/migrate.py" \
  copy-machinery <project-dir>

What it does:

1. Copies skills into the host runtime (.claude/skills/jig-<name>/ or .codex/skills/jig-<name>/), rewriting helper paths in SKILL.md bodies to that runtime.
2. Copies agents into the host runtime (.claude/agents/jig-*.md for Claude, .codex/agents/jig-*.toml for Codex).
3. Copies hook scripts into the host runtime, pinning each script's mode to 0o755.
4. Copies jig's templates/ tree into the host runtime (.claude/templates/ or .codex/templates/), rewriting helper paths in *.md.template bodies to that runtime. This is what lets the copied helpers seed from a template with no plugin root — decisions.py (lightweight-decisions), adr.py new, migrate.py seed-decisions, workflow.py's slice-template render, and memory.py's people.md bootstrap all resolve parents[2]/templates/. Claude gained this in slice 095-01; Codex has always had it. Re-run copy-machinery from a jig install to refresh a project scaffolded before 095-01 — it is the repair path decisions.py names when a template is unreachable.
5. Generates or merges host hook registration. --host claude uses .claude/settings.json, with per-entry metadata.managed_by_jig: true markers. --host codex uses .codex/hooks.json, with a schema-clean top-level hooks object.

Subsequent runs are idempotent: re-running copy-machinery overwrites the copied files in place and updates jig-managed hook registration. On --host claude, non-jig hooks in .claude/settings.json survive untouched. On --host codex, jig-managed .codex/hooks.json is regenerated as a whole because Codex hook registration is a single file and jig ownership is detected from generated jig hook command paths.

Refusal: unmanaged hooks

If the host hook configuration already exists and is not jig-managed, copy-machinery exits non-zero (exit code 3) and emits the UnmanagedHooksError refuse-message to stderr — no filesystem writes occur. For --host claude, this means .claude/settings.json has hooks under hooks.<event> but none carry the managed_by_jig marker. For --host codex, this means .codex/hooks.json exists and does not look like a jig-generated hook config. This matches the same safety stance scaffold-init enforces.

The documented escape is --force:

python3 "${CLAUDE_PLUGIN_ROOT}/skills/migrate/migrate.py" \
  copy-machinery <project-dir> --force

With --force, --host claude appends jig's hooks alongside existing entries, which survive unchanged. With --force, --host codex replaces an unmanaged .codex/hooks.json with jig's generated hook registration. Use the Codex force path only when you are sure the existing hook config should be replaced or has been backed up.

Converting a plugin-mode project (bug 018)

When the target was scaffolded --plugin-only, copy-machinery is the conversion route to in-repo mode. A project's mode lives in three places, and the command treats them differently:

1. The machinery on disk — copied, as described above.
2. scaffold.json's scaffold_mode — flipped from plugin-only to in-repo automatically once the copy succeeds, and reported as scaffold_mode: plugin-only -> in-repo. Machine-owned, no user content at stake. A project with no scaffold.json makes no mode claim, so nothing is written for it.
3. The paths the project's own docs cite — reported, never rewritten. See below.

Stale plugin-root citations after conversion

docs/workflow.md and docs/decisions/lightweight-decisions.md are rendered with plugin-root helper commands in plugin mode. After conversion that variable is unset — that is exactly the population this route rescues — so those commands no longer run.

copy-machinery prints a warning naming each affected file and its hit count, followed by the in-repo form the paths should take.

The two halves of that warning come from two different places, on purpose. The variable it searches for is the one the project was rendered against — scaffold.json's host_renderer — because that is what its docs actually contain, whichever host you happen to be running from. The path it offers as the replacement is this invocation's, because that is where this run just put the machinery.

Run a helper installed for one host against a project scaffolded for the other and each half still names something real: the variable its docs really cite, and the directory the skills really landed in. When both are the same host — the ordinary case — you will not notice the distinction.

The command does not touch these files, and you must not silently touch them either. They ship as Status: Draft (wizard-generated) with an explicit invitation to make them the project's own, so by conversion time they may hold real project content. Re-rendering them would destroy work the user cannot get back — a worse outcome than the stale paths.

copy-machinery is effectively always run inside a session, so ask the user what they want. Surface the warning, then offer the options and let them pick:

• Leave them — correct if the project still has the plugin installed and the paths resolve.
• You edit them — apply the replacement the warning prints, targeting only the cited paths and leaving surrounding prose alone. Show the diff before writing.
• They edit them — hand over the file list and stop.

Do not pick for them, and do not treat a general "go ahead, migrate my project" as consent to rewrite their documentation.

Relationship to scaffold-mode

migrate.py copy-machinery is the migration-path equivalent of scaffold-init --in-repo (the opt-in as of slice 099-01 / ADR-0041; --with-machinery is an accepted alias, and it was the default only between slices 016-03 and 099-01). Both end up calling the same host-aware copy_machinery(plugin, target, *, force, host) façade in scaffold.py, so the resulting host runtime shape is equivalent regardless of which adoption path produced it. Closing this gap for Claude was spec 021's reason for being; spec 059-01 extends the same adoption path to Codex.

Agentic slice-to-spec migration

For projects where migrate.py report returns Verdict: adoptable AND the inventory shows flat slice files under docs/slices/ rather than nested docs/specs/NNN-slug/spec.md form, there is no deterministic helper to do the grouping (slice 008-04 was deferred deliberately — see Non-goals on spec 020). Instead, the LLM driving the migration follows the algorithm below. Output is a new docs/specs/ tree; originals stay where they are until the caller verifies and chooses to clean up.

When to invoke

After migrate.py rename-decisions (so ADR filenames are jig-shaped), when the report's Ambiguities section names "Flat slices reference N milestone(s)" or similar. The follow-up is this agentic workflow. Do NOT run it if specs already live under docs/specs/NNN-slug/spec.md — that's already the jig shape.

Algorithm

For each migration, in order:

1. Read milestone summaries. Walk docs/milestones/*.md (or whatever the source's milestone-doc convention is). For each milestone, capture the title, scope, and slice list. These become the basis for spec naming.
2. Decide milestone → spec mapping. Each milestone becomes one spec folder. Naming convention: docs/specs/NNN-mM-<title-slug>/ where:
   • NNN is a 3-digit spec number (start at 001, ascend per milestone order — match the project's chronology when possible);
   • mM is the milestone tag lowercased (e.g. m1, m4.5);
   • <title-slug> is a slug of the milestone's headline ("EDS thin E2E" → eds-thin-e2e). Skip milestones that have no slices.
3. For each source slice file:
   1. Read its body. Locate the milestone tag (prose - **Milestone:** M1, frontmatter milestone: M1, or filename prefix — adapt to what the source uses).
   2. Locate its status. The source's vocabulary is usually 4-state — translate per the table below.
   3. Locate the heading. Source shape is usually # Slice NN — Title (H1, single number, no spec prefix). Transform to ## Slice NNN-NN — <slug-of-title> (H2, jig spec-slice fragment, slug-form title). Use the target spec's NNN from step 2 and the original slice number for the second NN.
   4. Prepend a frontmatter block (frontmatter shape per spec 015
      • 018):

      ---
      status: <translated-status>
      dependencies: []
      last_verified:
      ---
      

      Leave dependencies: [] for now — backfilling structured deps from prose "Depends on" lines is per-slice judgment work, not bulk-migration scope.

   5. Preserve the original slice body verbatim AFTER the new heading (Status / Milestone / Depends on / Estimated size prose lines included — they're harmless trailing context).
4. Write new files under docs/specs/NNN-mM-<title-slug>/:
   • spec.md synthesized from the milestone summary (header + overview + ## Decomposition + ## Slices link list).
   • One slice-NN-<original-shortname>.md per source slice. Keep the original filename's shortname (no re-slugging) so existing cross-references resolve.
5. Do NOT delete originals. The source docs/slices/ and milestone summaries stay in place. Caller decides when to clean up after verifying.
6. Verify with jig helpers. Run the following against the new spec dir and confirm clean output:

   # All slices resolvable
   python3 -c "import sys; sys.path.insert(0, 'skills/_common'); \
     from parsing import iter_slices; \
     [print(l.label) for l in iter_slices('docs/specs/NNN-mM-slug/spec.md')]"
   
   # Lint walks all slices, no AC contradictions
   python3 "${CLAUDE_PLUGIN_ROOT}/scripts/spec_lint.py" docs/specs/NNN-mM-slug/spec.md
   
   # Status board generates the table
   python3 skills/spec-workflow/workflow.py status-board <project-dir>
   

   land.py prepare --no-deviation-log (slice 019-01) lands without complaining about absent deviation logs on pre-jig DONE slices.

State translation

REVIEWED and RECONCILED are intermediate gates the source never had. Pre-jig slices that landed under the old lifecycle skip those gates by definition — the auto-tick on jig's REVIEWED→RECONCILED transitions doesn't fire for them and shouldn't. Use spec 019's --no-deviation-log flag when landing these retroactively.

Worked example

The shallow-validator M1 dogfood (2026-05-15) is the canonical reference. See worked-example-slice-to-spec.md for the source → target before/after, status-board output, and verification report.

Limitations

• No backfill of dependencies:. Prose "Depends on" lines stay in the slice body; the frontmatter dependencies: [] is empty. Future slices can populate them per-slice.
• No backfill of ### Deviation log. Pre-jig slices never had one. Use land.py prepare --no-deviation-log to land them retroactively (spec 019-01).
• Originals NOT deleted. Caller decides post-verification.
• No status-vocabulary auto-detection. The 4-state vocabulary above is the most common, but adapt to what the source actually uses (e.g., "In Review" might map to IN_PROGRESS or REVIEWED depending on context).
• CLAUDE.md references to old slice paths are NOT rewritten. Cross-references like [slice-01](docs/slices/slice-01.md) in CLAUDE.md / milestone summaries / etc. keep pointing at the original files. After the caller deletes originals, those refs must be updated by hand or via a follow-up migrate.py rename-decisions-style sweep (out of scope here).

Gotchas

• migrate.py report is read-only; migration operations are bounded mutators. The first mutating region was introduced by rename-decisions and remains protected by the sentinel comment (# ---------- BEGIN MUTATING CODE PATH (rename-decisions) ----------); later mutators (split-slices, copy-machinery) have their own command-specific preflights and tests. The report subcommand stays pure-read.
• rename-decisions is bounded by <project-dir>. It never reads or writes outside the directory passed on the CLI. Within scope it scans shared docs/ plus the selected host primer/runtime: CLAUDE.md and .claude/ for --host claude, or AGENTS.md and .codex/ for --host codex. Well-known skip paths (.git, node_modules, .venv, __pycache__, dist, build, etc.) are excluded from cross-reference scanning.
• Always --dry-run first. Even with idempotency and refusal on conflict, the plan output is the canonical preview surface. Two consecutive --dry-run invocations produce byte-identical output (AC #7), which is also how the test suite verifies stability.
• Remote links (GitHub URLs) are NOT rewritten. docs/adrs/ paths inside https://github.com/.../docs/adrs/... URLs stay untouched — external surface area the user may have published. Only local paths are rewritten.
• No git awareness. rename-decisions performs filesystem renames; if the project is a git repo, the user must git add -A to record the renames as tracked changes. Future slice if it bites.
• migrate.py's self-protection is path-anchored. The helper refuses to rewrite files under its own skills/migrate/ directory (so the canonical regexes + fixtures never get mangled by the helper running on its own repo). If a user copies migrate.py into their own project at e.g. <project>/tools/migrate.py, the copy is NOT covered by the self-protection — it would be rewritten like any other text file in scope. Invoke migrate.py from the installed plugin path (${CLAUDE_PLUGIN_ROOT}/skills/migrate/migrate.py), never a copied-in-tree version, to keep the guarantee.
• The verdict counts trigger directories, not files. A project with 100 ADR files but no workflow.md or architecture.md still scores only 1 trigger. The four triggers are about kinds of artifact, not volume.
• Flat-slice → nested-spec mapping is deferred. Slice 008-01's Mapping table flags flat slices as a topology question and points to slice 008-04. The helper does NOT propose a concrete parent-spec grouping — that requires user judgment (or the milestone manifest 008-04 will accept). For 008-01, the report just names the question.
• CLAUDE.md size is reported as a tripwire, not migrated. The validator's 59KB CLAUDE.md contains sprint-log content jig's Hot Cache doesn't model. The report's Ambiguity row flags it; the user decides what to port verbatim, summarize, or leave behind. No automation in 008-01 (or any planned 008 slice).
• Custom skills and agents are inventoried but never migrated. Out of 008's scope by explicit non-goal. The Inventory row lists them; the Ambiguity row asks the user how to reconcile.
• The report scans one validated docs root. It defaults to docs; pass --docs-root . (or another safe project-relative path) for an existing custom-root corpus. Arbitrary per-directory maps remain out of scope.
• Spikes are inventoried but not migrated. jig has no spike-workflow skill yet (separate gap; tracked in inbox/refinement -todo). The Ambiguity section notes the count and recommends keeping docs/spikes/ as-is.

Relationship to other skills

• scaffold-init is the greenfield counterpart. migrate is for existing projects; scaffold-init is for blank slates. Slice 008-05 (deferred) will teach scaffold-init to detect validator-style layout and suggest /jig:migrate instead of refusing opaquely.
• adr-workflow depends on docs/decisions/ matching ADR-0004's layout. migrate.py rename-decisions (slice 008-02, deferred) will produce that layout from a docs/adrs/ source. Until then, projects already on the legacy layout can run adr-workflow against docs/adrs/ directly via the helper's path-tolerance (open question in ADR-0004 §"Backwards compatibility window for adr.py").
• spec-workflow assumes nested specs (docs/specs/NNN-*/spec.md). Projects with flat slices need migrate.py slice-to-spec (slice 008-04, deferred) before spec-workflow operations can target them the way they target jig's own specs.
• slice-land is orthogonal — it operates on whatever shape the project ends up with after migration. No direct coupling.

Out of scope for slice 008-01

• Any filesystem mutation. The report subcommand is read-only by design; mutating operations land in slices 008-02 (rename-decisions), 008-03 (jig-self-migration via 008-02's helper), 008-04 (slice-to-spec-mapping), 008-05 (scaffold-init suggestion wiring).
• Importing CLAUDE.md content into jig's Hot Cache template. Inventoried only; the user ports manually.
• Cross-format ADR template conversion (MADR, Y-statements, etc.). ADR-0004 just covers path/filename rename.
• JIRA / Linear / Asana milestone-to-ticket mapping.
• Custom-skill / custom-agent migration.
• Roundtripping (post-migration rollback). The user keeps the pre-migration commit as their rollback.
• Multi-project batch migration. One project at a time.