Implement

---
name: implement
description: Implements a single issue, creates a GitHub Issue/PR, and links them with `Closes #N`. (1 issue = 1 PR)
argument-hint: '[ISSUE-number]'
disable-model-invocation: true
allowed-tools: Read, Glob, Grep, Write, Edit, Bash(bash scripts/checkpoint.sh *), Bash(bash scripts/wt_setup.sh *), Bash(bash scripts/wt_cleanup.sh *), Bash(bash scripts/registry_edit.sh *), Bash(bash scripts/flock_edit.sh *), Bash(bash scripts/worktree.sh *), Bash(python3 scripts/*), Bash(git *), Bash(gh *), Bash(bash ${CLAUDE_PLUGIN_ROOT}/scripts/*), Bash(python3 ${CLAUDE_PLUGIN_ROOT}/scripts/*)
---
<!-- AUTO-GENERATED by scripts/gen_skills.py — DO NOT EDIT. Edit SKILL.md.tmpl instead. -->

## Kit Preamble — implement

### Kit Script Root
Kit root: `${CLAUDE_PLUGIN_ROOT}`
- Absolute path above → plugin install (substituted at load time; no project
  `scripts/` dir): prefix every kit script command with it, e.g.
  `bash <kit-root>/scripts/checkpoint.sh …`. Absolute paths also work from worktrees.
- Literal `${…}` placeholder above → standalone layout: run commands as written.

### Project Context Detection
Run these checks silently at the start. Use results to adapt behavior:
- `[ -f issues.md ]` — if true, this project uses the sprint system. Respect issue numbering and STATUS.md.
- `[ -f docs/sprint_state.md ]` — if true and Status shows `running`, a sprint is active. Be aware of parallel work in worktrees.
- `[ -f docs/prd_digest.md ]` — if true, read it for quick project context before starting.

### Kit Rules
- Verify `gh auth status` before any GitHub operation.

### Checkpoint Verification Pattern
Every phase has a checkpoint. Run the verification command and check the exit code.
- Exit non-zero (blocking gate): **STOP immediately**, report failure, do NOT proceed.
- Exit 0 with an `ADVISORY:` line (advisory gate): report the gap, self-correct, continue.
Standard prefix:
```
bash scripts/checkpoint.sh
```
Append `--skill <name> --phase <phase> --issue <ID>` for the specific check.
`checkpoint.sh` resolves the main repo root internally, so the command stays
a single prefix-matchable form (safe to allowlist as `Bash(bash scripts/checkpoint.sh *)`).

### Worktree Setup Pattern
Pipeline skills operate in git worktrees to isolate changes from main.
- Create + freeze: `WT="$(bash scripts/wt_setup.sh <branch>)"` — creates the
  worktree via `scripts/worktree.sh create` and writes `.claude-kit/freeze-dir.txt`
  inside it in a single step.
- Resolve main root: `bash scripts/worktree.sh root`
- Remove safely: `bash scripts/wt_cleanup.sh <branch>` — cd's to main root
  inside a subshell, then removes the worktree (never leaves CWD dangling).
All file operations happen inside `$WT/`. Shared files live on main only.

### Registry Update Pattern
Shared files (`issues.md`, `STATUS.md`, `CHANGELOG.md`) are managed on main only.
Always use `registry_edit.sh` for concurrent-safe writes — it resolves the
main repo root internally and delegates to `flock_edit.sh`:
```bash
bash scripts/registry_edit.sh issues.md -- bash -c '<update command>'
```
Never commit these files to feature branches.
## Checkpoint Rules — MANDATORY
Every phase in this skill has a CHECKPOINT block. You MUST run the verification command after completing each phase. Blocking gates (**MANDATORY — NEVER SKIP**) exit non-zero on failure: STOP immediately, report, do NOT proceed. Advisory gates (**ADVISORY (report & continue)**) always exit 0 and print an `ADVISORY:` line on failure: report the gap, self-correct, then continue — do NOT halt on them (ISSUE-031). Never skip running a checkpoint of either tier.

**Path convention**: Checkpoint commands use the `bash scripts/checkpoint.sh` wrapper, which resolves the main repo root internally (via `scripts/worktree.sh root`). This ensures the verification script is found regardless of whether CWD is the main repo or a worktree, and keeps the command prefix-matchable for permission allowlists.

Hard requirements:
- Create GitHub Issue if missing: `gh issue create`
- Create/update PR and include `Closes #<issue_number>` in PR body.

Algorithm:
1) Ensure `gh` authenticated (gh auth status).

### Phase 0 — Spec gate (MANDATORY, runs before any other phase)

Before reading the test plan, the issue body, or anything else, evaluate the spec gate for `$ARGUMENTS`. This protects against the failure mode where a non-trivial feature gets coded without any reviewable decision artifact.

0a) **Parse flags**: check `$ARGUMENTS` for `--skip-spec-gate`. If present, the gate logs a telemetry-style bypass note (one line printed to stdout) and proceeds to step 1. Strip the flag from `$ARGUMENTS` before continuing.

0b) **Compute the gate decision**:
```
python3 scripts/spec_gate.py $ARGUMENTS [--skip-spec-gate]
```
The script reads `issues.md`, detects sprint mode via `KIT_SPRINT_MODE=1`, scans the issue body for signals (api/schema/migration/breaking/protocol/데이터모델/new-package + estimate-at-cap), and prints a JSON object with `decision`, `reasons`, `signals`, `spec_path`, `sprint_mode`.

0c) **Branch on `decision`**:

- **`decision: "proceed"`** — log the reasons (and signals if non-empty) inline so the user can see why the gate let it through, then continue to step 1.

- **`decision: "auto_spec"`** (sprint mode, Spec-Required, no SPEC yet) — invoke the `/spec` skill inline on the current branch:
  - Set env `KIT_SPRINT_MODE=1` so `/spec` knows it is being auto-invoked.
  - Pass the issue id: `/spec $ARGUMENTS`.
  - Wait for `/spec` to complete and produce `docs/specs/SPEC-<NNN>.md` with the `Spec:` field updated on the issue.
  - The SPEC commit message format is enforced by `/spec` (`docs(spec): SPEC-<NNN> — <decision summary>`).
  - After `/spec` returns, re-run `python3 scripts/spec_gate.py $ARGUMENTS` to confirm the new decision is `proceed`. If it is still not `proceed`, STOP and report.

- **`decision: "hold"`** (non-sprint, requires user input) — present a structured 3-way choice using the project's question mechanism (e.g., `AskUserQuestion`):
  - **Option 1 — Run `/spec` now**: invoke `/spec $ARGUMENTS`, then resume at step 0b (re-evaluate gate after SPEC lands).
  - **Option 2 — Mark Spec-Required: false**: ask the user for a one-line reason; rewrite the issue's `Spec-Required:` field to `false` and append the reason to the issue's Implementation Notes; then proceed to step 1.
  - **Option 3 — Cancel implement**: print the gate's reasons and STOP cleanly.

  Quote the gate's `reasons` and `signals` to the user so they understand the prompt.

- **`decision: "bypassed"`** (`--skip-spec-gate` was passed) — print the one-line bypass note (telemetry-style: `spec_gate_bypassed issue=$ARGUMENTS`) and continue.

0d) Only after Phase 0 produces a `proceed`-equivalent outcome does the rest of the algorithm run.

> **CHECKPOINT — MANDATORY — NEVER SKIP**
> Run: `bash scripts/checkpoint.sh --skill implement --phase test-plan --issue $ARGUMENTS`
> Verifies `docs/test_plan.md` exists with a non-empty Risk Matrix.
> If exit code ≠ 0: STOP — run `/kickoff` first or create test_plan.md manually.

2) Locate $ARGUMENTS in issues.md. Read the issue's Goal, Scope, AC, and Implementation Notes.
   - **Manual check**: If the issue has `Manual: true`, STOP immediately. Report to the user: "This issue requires manual action — see Implementation Notes." Do NOT proceed with automated implementation.
2a) **Figma prototype upsert — MANDATORY when Figma URLs exist:**
   Scan the issue's Implementation Notes for Figma URLs (pattern: `figma.com/design/` or `figma.com/file/`).

   **If NO Figma URLs found**: skip to step 2a checkpoint.

   **If Figma URLs ARE found — you MUST execute ALL of the following steps:**
   1. Determine the platform from the issue's `Platform` field:
      - `mobile` → `--mobile`
      - `desktop` → `--desktop`
      - `web` or empty → no flag (default)
      Run the fetch script with the platform flag and all extracted URLs:
      ```bash
      python3 scripts/figma_fetch.py [--mobile|--desktop] <url1> <url2> ...
      ```
      If the script exits with non-zero (e.g., FIGMA_TOKEN not set, invalid URL, API error):
      **STOP** and report the error to the user. Do NOT proceed — the issue explicitly requires Figma data.
   2. `figma_fetch.py` automatically generates:
      - `figma-export/design_data.json` — full node tree data
      - `figma-export/figma_styles.css` — complete CSS rules (gradients, shadows, fonts, positioning, responsive, states)
      - `figma-export/component_map.json` — node→class→asset mapping with html_hint
      - `figma-export/assets/` — downloaded SVG/PNG icons and images
      - `figma-export/renders/` — Figma-rendered reference PNGs
   3. **Extract breakpoints from the issue.** Read the issue's Implementation Notes or the PRD for
      responsive breakpoint specs (e.g., "Desktop 1400px+ / Tablet 768px+ / Mobile 360px+").
      If found, pass them explicitly to the figma-converter prompt below.
      If not found, use the Figma frame widths as breakpoints.

   4. Invoke the **figma-converter** agent (via Task). `agents/figma-converter.md` is the
      single source of its workflow — do NOT restate or paraphrase its instructions in the
      prompt. Pass only the per-invocation call parameters:
      ```
      You are the figma-converter agent. Read agents/figma-converter.md and follow it exactly.

      ## Call Parameters
      - Responsive breakpoints (from the project spec — use EXACTLY these values):
        {Insert the breakpoints extracted in step 3, e.g.:
         - Desktop: > 1400px (default)
         - Tablet: ≤ 1400px
         - Mobile: ≤ 768px}
      - Input directory: figma-export/
      - Output path: prototype/screens/desktop.html
      - The output must be a COMPLETE HTML file — a placeholder is NOT acceptable.
        If you cannot complete it, explain what blocked you.
      ```
   5. **Verify the output is not a placeholder.** Read the generated HTML file. If it contains
      "placeholder" or is less than 1KB, the figma-converter failed — retry with the same prompt.

   **Do NOT skip this step when Figma URLs exist. The checkpoint below WILL fail if figma_fetch.py was not executed.**

> **CHECKPOINT — MANDATORY — NEVER SKIP**
> Run: `bash scripts/checkpoint.sh --skill implement --phase figma --issue $ARGUMENTS`
> Auto-passes when no Figma URLs exist. Fails if Figma URLs found but design_data.json not generated.
> If exit code ≠ 0: STOP immediately and report the failure. Do NOT proceed.

2b) Gather context — read the following docs (if they exist, skip silently if not).
   **Read all applicable documents via parallel Read tool calls in a single message. Do NOT read them sequentially.**
   - `docs/prd_digest.md` — quick PRD context (goals, features, NFRs, scope)
   - `docs/architecture.md` — tech stack, modules, API design
   - `docs/data_model.md` — schema, indexes, query patterns, seed data, migrations
   - `docs/requirements.md` — related FRs/NFRs referenced by the issue
   - recalled **review lessons** (native memory) — known recurring review findings to proactively avoid
   - `docs/test_plan.md` — test strategy, risk matrix, critical flows to guide test writing
   - **UI context** — read all of the following in parallel (when the issue has `UI: true`, or contains UI keywords in Track/title):
     - `docs/design_system.md` — CSS tokens, component specs
     - `docs/design_philosophy.md` — aesthetic direction
     - `docs/wireframes.md` — layout for the relevant screen
     - `docs/interactions.md` — states, transitions, animations for the relevant flow
     - `docs/copy_guide.md` — UI labels, error messages, empty states, glossary
     - `prototype/screens/*.html` — visual reference for the relevant screen
     - `figma-export/skeleton.html` — **complete HTML structure** to copy into implementation (semantic tags, text, assets, CSS classes)
     - `figma-export/figma_styles.css` — **ready-to-use CSS rules** (includes responsive @media queries + :hover/:focus states)
     - `figma-export/component_map.json` — maps Figma nodes to CSS classes, asset paths (with html_hint), children order
     - `figma-export/assets/` — downloaded SVG/PNG icons and images from Figma
   - **Mobile UI context** — read all of the following in parallel (when the issue involves mobile/React Native work):
     - `docs/design_system_mobile.md` — React Native design tokens, component specs
     - `docs/design_philosophy.md` — aesthetic direction (shared with web)
     - `docs/wireframes_mobile.md` — mobile layout, gestures, safe areas
     - `docs/interactions_mobile.md` — gesture specs, haptic mapping, transitions
     - `docs/copy_guide.md` — UI labels, error messages (shared with web)
     - `prototype-mobile/src/screens/*.tsx` — React Native screen reference
   - Pass all relevant context to the developer subagent prompt.
3) Ensure Branch is set; if empty, derive `issue/$ARGUMENTS-<slug>` and write back.
   - **File lock**: wrap the issues.md read-modify-write with:
     `bash scripts/registry_edit.sh issues.md -- bash -c '<update command>'`
4) Ensure GH-Issue exists:
   - If empty: `gh issue create --title "[$ARGUMENTS] <title>" --body "<body>"`
   - Body must include: issue goal, scope (in/out), acceptance criteria, and implementation notes from issues.md.
   - Capture issue number/url; write back to issues.md.
   - **File lock**: wrap the issues.md write-back with:
     `bash scripts/registry_edit.sh issues.md -- bash -c '<update command>'`

> **CHECKPOINT — ADVISORY (report & continue)**
> Run: `bash scripts/checkpoint.sh --skill implement --phase issue --issue $ARGUMENTS`
> Advisory: exits 0 even on failure, printing an `ADVISORY:` line — report the gap, self-correct, then continue.

5) Create worktree for the branch (and auto-initialize the freeze marker):
   ```bash
   WT="$(bash scripts/wt_setup.sh issue/$ARGUMENTS-<slug>)"
   ```
   `wt_setup.sh` creates the worktree via `scripts/worktree.sh create` and
   writes `.claude-kit/freeze-dir.txt` inside it in a single step. All
   subsequent file operations (code, tests) happen inside `$WT/`.
   From this point, Edit/Write operations outside `$WT/` will be blocked
   (if `/freeze` or `/guard` hooks are active). Registry files on main
   (`issues.md`, `STATUS.md`) are updated via `bash scripts/registry_edit.sh`
   from the main repo root — this is the only exception.

> **CHECKPOINT — ADVISORY (report & continue)**
> Run: `bash scripts/checkpoint.sh --skill implement --phase worktree --issue $ARGUMENTS`
> Advisory: exits 0 even on failure, printing an `ADVISORY:` line — report the gap, self-correct, then continue.

6) **Write tests FIRST (TDD Red phase)** inside `$WT/`.
   This project follows TDD: write failing tests before writing implementation code.
   - **Read test_plan.md first**: If `docs/test_plan.md` exists, read it. Use the Risk Matrix and Critical Flows to prioritize which scenarios to test. Map your tests to the test cases defined there (TC-NNN).
   - Every new behavior MUST have at least one test. No exceptions.
   - Each AC (Acceptance Criterion) in the issue maps to at least one test case.
   - Cover the happy path AND at least one error/edge case per AC.
   - Test files must follow project conventions (e.g., `test_*.py` in `tests/`).
   - Tests must contain **real assertions** — empty test functions, `pass`-only bodies, or tests without `assert`/`expect` will be rejected at checkpoint.
   - **E2E tests**: If the issue involves a critical user journey (as defined in `docs/test_plan.md` Risk Matrix), write an E2E test. Web: `tests/e2e/*.spec.ts`. Mobile: `e2e/*.yaml` or `e2e/*.test.ts`.
   - Do NOT skip this step. Code without meaningful tests will be rejected at checkpoint.
6b) **Verify test coverage** (self-check before checkpoint):
   - Cross-reference your test files against the issue's AC list. Each AC should have a corresponding test.
   - If `docs/test_plan.md` exists, check that any High-risk flows affected by your changes have test coverage.
   - The checkpoint will warn about potential AC coverage gaps.

> **CHECKPOINT — MANDATORY — NEVER SKIP**
> Run: `bash scripts/checkpoint.sh --skill implement --phase tests-written --issue $ARGUMENTS`
> If exit code ≠ 0: STOP immediately and report the failure. Do NOT proceed.

7) **Verify RED** — Run tests to confirm they FAIL (no implementation yet).
   Tests should fail because the implementation code doesn't exist yet. This ensures tests are testing real behavior, not vacuously passing.

> **CHECKPOINT — MANDATORY — NEVER SKIP**
> Run: `bash scripts/checkpoint.sh --skill implement --phase red --issue $ARGUMENTS`
> If exit code ≠ 0: STOP immediately and report the failure. Do NOT proceed.

8) **Implement minimal code** inside `$WT/`.
   Write the minimum code needed to make all tests pass. Follow existing project patterns.

   **Minimality gate — walk the Decision Ladder before generating code** (the developer subagent enforces this; the orchestrator must not write prompts that contradict it):
   1. Does this need to exist? (YAGNI) → 2. Does stdlib cover it? → 3. Native platform/framework feature? → 4. Already-installed dependency? → 5. Can it be one line? → 6. Only then write the minimum that works.
   Prohibitions: no abstraction with a single implementation, no avoidable new dependency, no unrequested boilerplate — deletion over addition, fewest files possible.
   **This never overrides safety**: it does not license skipping the TDD tests, input validation, error handling, security, accessibility, or Figma/design fidelity. Minimal means *less code*, not *less correct*.

   **If Figma data exists** (`figma-export/` directory present):
   - **BEFORE writing any code**, read `prototype/screens/*.html` — this is your visual target
   - Read `figma-export/figma_styles.css` — import this CSS directly
   - Read `figma-export/component_map.json` — use class names and asset paths
   - Read `figma-export/renders/*.png` — compare your implementation against these
   - Your implementation must visually match the prototype HTML. Do NOT guess the design.

   **🚫 Structure-source prohibition (when `figma-export/` exists) — applies to BOTH this skill and any developer subagent prompt you write:**
   - `prototype/screens/*.html` (generated by figma-converter from Figma) is the **ONLY** structural source of truth. Layout, grid, hero composition, card count, decorative elements, breakpoint thresholds — all come from the prototype.
   - It is **FORBIDDEN** to designate any other existing project file (e.g., a sibling product's template, a previous page in the same repo) as the structure source. Reference other files only for *coding patterns* (Django template tags, view conventions, naming) — **never** for visual structure.
   - When invoking the developer subagent, you MUST NOT write prompts containing phrases like:
     - "model on the existing X.html pattern"
     - "copy X structure as the starting point"
     - "replace X-specific values with Y values" (this implies copying X's structure)
     - "use X.html as the template"
   - Instead, the developer prompt MUST say: "The visual source of truth is `prototype/screens/desktop.html` (and tablet/mobile variants). Reproduce its structure exactly. Use other project files only as a reference for coding conventions, not for layout."
   - Rationale: a previous incident produced a page that visually matched a sibling product instead of the Figma design, because the orchestrator prompt reframed an unrelated template as the structure source. Static checkpoints cannot detect this drift after the fact — the prohibition must be enforced at prompt-authoring time.

> **CHECKPOINT — ADVISORY (report & continue)**
> Run: `bash scripts/checkpoint.sh --skill implement --phase code --issue $ARGUMENTS`
> Advisory: exits 0 even on failure, printing an `ADVISORY:` line — report the gap, self-correct, then continue.

9) **Run tests (GREEN phase)** inside `$WT/`.
   All tests must pass. If any fail, fix the implementation (not the tests) until green.
   The checkpoint also runs platform-specific gates (e2e-web, e2e-mobile, etc.) as **warnings**.
   Gate failures don't block implementation but flag integration risks early.

> **CHECKPOINT — MANDATORY — NEVER SKIP**
> Run: `bash scripts/checkpoint.sh --skill implement --phase test --issue $ARGUMENTS`
> If exit code ≠ 0: STOP immediately and report the failure. Do NOT proceed.

9.5) **Figma fidelity loop** (UI issues with Figma data only — skip if no `figma-export/design_data.json`):
   Iteratively refine the implementation until all Figma tokens match and structure is correct.

   **a) Token compliance (primary — blocking):**
   ```
   MAX_ITERATIONS = 3
   for i in 1..MAX_ITERATIONS:
     Run: python3 scripts/verify_figma_compliance.py --project-path $WT
     IF exit code = 0 (all tokens match): BREAK.
     IF exit code ≠ 0:
       1. Read the violation report — each violation shows file:line, found value, and Figma-allowed values.
       2. Fix the implementation: replace wrong colors/fonts/spacings/etc. with Figma values.
       3. Re-run tests to ensure fixes don't break functionality.
       4. Continue loop.
   IF all MAX_ITERATIONS exhausted: log remaining violations and proceed.
   ```

   **b) Computed style verification loop (primary — blocking):**
   ```
   MAX_ITERATIONS = 3
   for i in 1..MAX_ITERATIONS:
     Run: python3 scripts/verify_computed_styles.py --project-path $WT
     IF exit code = 0 (all computed styles match): BREAK.
     IF exit code ≠ 0:
       1. Read the violation report — shows ACTUAL rendered values vs Figma-allowed values.
          These are real computed values from the browser, not source code regex matches.
       2. Fix: the violation tells you exactly which element, property, and computed value is wrong.
       3. Re-run tests.
       4. Continue loop.
   IF all MAX_ITERATIONS exhausted: log remaining violations and proceed.
   ```

   **c) Structural match loop (primary — blocking, per-viewport):**
   ```
   MAX_ITERATIONS = 3
   for i in 1..MAX_ITERATIONS:
     Run: python3 scripts/verify_structural_match.py --project-path $WT
     IF exit code = 0 (all viewports matched): BREAK.
     IF exit code ≠ 0:
       1. Read the per-viewport report. Each violation shows:
          - Which viewport (desktop/tablet/mobile) has missing elements
          - Missing element types (buttons, inputs, icons, navigation)
          - Missing text content (copy from Figma not found)
          - Missing responsive CSS (@media queries for each breakpoint)
       2. Fix the implementation:
          - Add missing elements for each viewport
          - Add @media queries for tablet/mobile breakpoints
          - Ensure responsive behavior matches Figma's per-viewport design
       3. Re-run tests to ensure fixes don't break functionality.
       4. Continue loop.
   IF all MAX_ITERATIONS exhausted: log remaining violations and proceed.
   ```

   **c) Layout verification loop (primary — blocking):**
   ```
   MAX_ITERATIONS = 3
   for i in 1..MAX_ITERATIONS:
     Run: python3 scripts/verify_layout.py --project-path $WT
     IF exit code = 0 (layout matches): BREAK.
     IF exit code ≠ 0:
       1. Read the violation report:
          - Wrong direction: "sidebar should be row but has flex-direction: column"
          - Wrong order: "nav should be left-of content but appears after it"
       2. Fix: adjust flex-direction, reorder DOM elements, fix container structure
       3. Re-run tests.
       4. Continue loop.
   IF all MAX_ITERATIONS exhausted: log remaining violations and proceed.
   ```

   **e) Same-renderer visual diff (blocking — prototype HTML vs implementation, both Chromium):**
   ```
   Run: python3 scripts/verify_visual_diff.py --project-path $WT --threshold 1
   IF exit code ≠ 0: read diff images, fix visible layout/style issues, re-run.
   ```
   Both prototype and implementation are rendered by the same Chromium engine,
   so there are no font hinting or anti-aliasing false positives.

   **f) Visual diff advisory (non-blocking):**
   ```
   Run: python3 scripts/verify_visual_diff.py --project-path $WT --threshold 5
   ```
   Generates diff images in `figma-export/visual-diff/` for visual inspection.
   Do NOT block on pixel diff — it's an advisory signal due to renderer differences (Figma vs Chromium).
   If diff > 5%: review the diff images and fix obvious layout issues.

10) Commit + push (from `$WT/`).

> **CHECKPOINT — ADVISORY (report & continue)**
> Run: `bash scripts/checkpoint.sh --skill implement --phase push --issue $ARGUMENTS`
> Advisory: exits 0 even on failure, printing an `ADVISORY:` line — report the gap, self-correct, then continue.

11) Create PR (or update):
   - Title: `[$ARGUMENTS] <title>`
   - Body begins with `Closes #<issue_number>`

> **CHECKPOINT — ADVISORY (report & continue)**
> Run: `bash scripts/checkpoint.sh --skill implement --phase pr --issue $ARGUMENTS`
> Advisory: exits 0 even on failure, printing an `ADVISORY:` line — report the gap, self-correct, then continue.

12) Record PR URL in issues.md; set Status=done; update STATUS.md.
   Use `registry_edit.sh` — it resolves the main repo root internally so
   you never have to build paths via command substitution:
   ```bash
   bash scripts/registry_edit.sh issues.md -- bash -c '<update command>'
   bash scripts/registry_edit.sh STATUS.md -- bash -c '<update command>'
   ```

> **CHECKPOINT — ADVISORY (report & continue)**
> Run: `bash scripts/checkpoint.sh --skill implement --phase registry --issue $ARGUMENTS`
> Advisory: exits 0 even on failure, printing an `ADVISORY:` line — report the gap, self-correct, then continue.

## Shared Registry Files
**IMPORTANT**: Never commit `issues.md`, `STATUS.md`, or `CHANGELOG.md` to the feature branch.
These are registry files managed only on main. Always use `bash scripts/registry_edit.sh <file> -- bash -c '<update command>'` — the wrapper resolves the main repo root internally.

## Error Handling
- If `gh auth status` fails: stop and instruct the user to run `gh auth login`.
- If issue not found in issues.md: stop and report the missing issue number.
- If `gh issue create` fails: retry once; if still failing, stop and report the error.
- If tests fail: do NOT push or create PR. Report failing tests and stop.
- If `git push` fails: check for upstream conflicts; report and stop.
- If `gh pr create` fails: retry once; if still failing, the branch is already pushed — report and let user create PR manually.

## Rollback
- Use `bash scripts/wt_cleanup.sh <branch>` for safe worktree removal.
  The wrapper cd's to the main repo root and then removes the worktree in
  a single subshell, so the caller never ends up with a deleted CWD.
- If failure occurs after worktree creation but before PR:
  1. `bash scripts/wt_cleanup.sh <branch>`
  2. `git push origin --delete <branch>` (remote cleanup, if pushed)
- If failure occurs after PR creation:
  1. `gh pr close <pr_number>` to close the broken PR.
  2. Clean up worktree and branch as above.
- Revert issues.md status back to `doing` or `backlog` if it was prematurely set to `done`.