arcane-cli 0.14.0 → 0.15.1

package/dist/assets/.github/prompts/spell-implement.prompt.md

@@ -1,101 +1,101 @@
----
-name: Spell — Implement
-description: Autonomous implementation loop — pick a story from stories.json, build it, test it, commit it, repeat until all stories pass
-argument-hint: Path to stories.json or paste story context (optional - uses current directory stories.json by default)
-agent: agent
----
-
-## Executive Summary
-
-- This is the core autonomous loop of the Spell Loop methodology.
-- Each iteration: pick a story → implement → run tests → commit if passing → update stories.json → loop.
-- Uses fresh context per iteration — only stories.json, progress.txt, and git history carry forward.
-- See [[governance/development-methodology|Development Methodology]] for full Spell Loop reference.
-
----
-
-Run the autonomous implementation loop for the current feature.
-
-Use these files for context:
-
-- [governance/development-methodology.md](../../governance/development-methodology.md) — Spell Loop methodology
-- [governance/testing-standards.md](../../governance/testing-standards.md) — Testing frameworks and coverage requirements
-- The feature's `architecture.md` — for tech decisions and patterns
-- The feature's `stories.json` — for the work breakdown
-- The feature's `progress.txt` (in `features/{slug}/`, if present) — accumulated learnings from prior iterations; read it before each iteration and append new learnings as the loop proceeds
-
-Workflow (loop until all stories pass):
-
-0. **Sync workspace** — before any code changes, ensure the workspace is current:
-   ```bash
-   git fetch --prune origin
-   git checkout main && git pull --ff-only
-   ```
-   If `pull --ff-only` fails, halt and report — manual rebase is needed.
-
-1. **Load stories.json** — locate the feature folder from the current branch:
-   ```bash
-   # Derive feature folder from branch name (works for lafayette/feat/541-phase-2a or lafayette/feat/phase-2a)
-   FEATURE_FOLDER="features/$(git symbolic-ref --short HEAD | sed 's|.*/feat/||')"
-   ```
-   Load `$FEATURE_FOLDER/stories.json` and `$FEATURE_FOLDER/architecture.md`. If the branch name doesn't follow the `feat/{slug}` or `feat/{id}-{slug}` pattern, look for the most recently modified `features/*/stories.json` or ask the operator for the path.
-
-   Find the next story where `"passes": false`, ordered by priority.
-
-2. **Read context** — load only what this story needs:
-   - The story's description and acceptance criteria from stories.json
-   - Relevant sections of architecture.md
-   - Latest entries in progress.txt (if exists) for learnings from previous iterations
-   - Files that will be modified (check git status)
-
-3. **Implement the story**:
-   - Follow the architecture decisions — do not deviate without flagging.
-   - Write the minimum code to satisfy acceptance criteria.
-   - Follow project coding conventions and patterns from existing code.
-   - Include tests per governance/testing-standards.md.
-
-4. **Run tests**:
-   - Run the test suite for the affected area.
-   - All existing tests must still pass (no regressions).
-   - New tests must pass.
-   - Check coverage against thresholds (80% line, 95% critical path).
-
-5. **Evaluate results**:
-   - **Tests pass:** proceed to commit.
-   - **Tests fail:** debug and fix. If stuck after 3 attempts, mark the story with the error in stories.json and move to the next story.
-
-6. **Commit the story**:
-   - Use Conventional Commits format (see spell-commit-work).
-   - One commit per story (squash if needed).
-   - Include the story ID in the commit body.
-
-7. **Update stories.json**:
-   - Set `"passes": true` for the completed story.
-   - Set `"testEvidence"` with coverage % and test count.
-
-8. **Append to `$FEATURE_FOLDER/progress.txt`**:
-   ```
-   ## Iteration N — [STORY-ID] — [timestamp]
-   ### What was done
-   - [summary of changes]
-   ### What was learned
-   - [patterns, gotchas, conventions discovered]
-   ### What to watch for
-   - [warnings for future iterations]
-   ```
-   File lives in the feature folder, not the repo root.
-
-9. **Loop** — go to step 1 and pick the next story.
-
-10. **Completion** — when all stories have `"passes": true`:
-    - Summarize what was built.
-    - Report total test count and coverage.
-    - Recommend running `spell-review` for adversarial review.
-
-Rules:
-- **Fresh context:** do not carry assumptions from previous stories. Re-read what you need.
-- **No scope creep:** only implement what the story specifies.
-- **Test first when possible:** write the test, see it fail, then implement.
-- **Commit atomically:** one story = one commit.
-- **Never skip tests:** if there's no test framework set up, set it up as the first story.
-- **Stuck threshold:** if a story fails 3 consecutive attempts, mark it and move on. Human intervention needed.
+---
+name: Spell — Implement
+description: Autonomous implementation loop — pick a story from stories.json, build it, test it, commit it, repeat until all stories pass
+argument-hint: Path to stories.json or paste story context (optional - uses current directory stories.json by default)
+agent: agent
+---
+
+## Executive Summary
+
+- This is the core autonomous loop of the Spell Loop methodology.
+- Each iteration: pick a story → implement → run tests → commit if passing → update stories.json → loop.
+- Uses fresh context per iteration — only stories.json, progress.txt, and git history carry forward.
+- See [[governance/development-methodology|Development Methodology]] for full Spell Loop reference.
+
+---
+
+Run the autonomous implementation loop for the current feature.
+
+Use these files for context:
+
+- [governance/development-methodology.md](../../governance/development-methodology.md) — Spell Loop methodology
+- [governance/testing-standards.md](../../governance/testing-standards.md) — Testing frameworks and coverage requirements
+- The feature's `architecture.md` — for tech decisions and patterns
+- The feature's `stories.json` — for the work breakdown
+- The feature's `progress.txt` (in `features/{slug}/`, if present) — accumulated learnings from prior iterations; read it before each iteration and append new learnings as the loop proceeds
+
+Workflow (loop until all stories pass):
+
+0. **Sync workspace** — before any code changes, ensure the workspace is current:
+   ```bash
+   git fetch --prune origin
+   git checkout main && git pull --ff-only
+   ```
+   If `pull --ff-only` fails, halt and report — manual rebase is needed.
+
+1. **Load stories.json** — locate the feature folder from the current branch:
+   ```bash
+   # Derive feature folder from branch name (works for lafayette/feat/541-phase-2a or lafayette/feat/phase-2a)
+   FEATURE_FOLDER="features/$(git symbolic-ref --short HEAD | sed 's|.*/feat/||')"
+   ```
+   Load `$FEATURE_FOLDER/stories.json` and `$FEATURE_FOLDER/architecture.md`. If the branch name doesn't follow the `feat/{slug}` or `feat/{id}-{slug}` pattern, look for the most recently modified `features/*/stories.json` or ask the operator for the path.
+
+   Find the next story where `"passes": false`, ordered by priority.
+
+2. **Read context** — load only what this story needs:
+   - The story's description and acceptance criteria from stories.json
+   - Relevant sections of architecture.md
+   - Latest entries in progress.txt (if exists) for learnings from previous iterations
+   - Files that will be modified (check git status)
+
+3. **Implement the story**:
+   - Follow the architecture decisions — do not deviate without flagging.
+   - Write the minimum code to satisfy acceptance criteria.
+   - Follow project coding conventions and patterns from existing code.
+   - Include tests per governance/testing-standards.md.
+
+4. **Run tests**:
+   - Run the test suite for the affected area.
+   - All existing tests must still pass (no regressions).
+   - New tests must pass.
+   - Check coverage against thresholds (80% line, 95% critical path).
+
+5. **Evaluate results**:
+   - **Tests pass:** proceed to commit.
+   - **Tests fail:** debug and fix. If stuck after 3 attempts, mark the story with the error in stories.json and move to the next story.
+
+6. **Commit the story**:
+   - Use Conventional Commits format (see spell-commit-work).
+   - One commit per story (squash if needed).
+   - Include the story ID in the commit body.
+
+7. **Update stories.json**:
+   - Set `"passes": true` for the completed story.
+   - Set `"testEvidence"` with coverage % and test count.
+
+8. **Append to `$FEATURE_FOLDER/progress.txt`**:
+   ```
+   ## Iteration N — [STORY-ID] — [timestamp]
+   ### What was done
+   - [summary of changes]
+   ### What was learned
+   - [patterns, gotchas, conventions discovered]
+   ### What to watch for
+   - [warnings for future iterations]
+   ```
+   File lives in the feature folder, not the repo root.
+
+9. **Loop** — go to step 1 and pick the next story.
+
+10. **Completion** — when all stories have `"passes": true`:
+    - Summarize what was built.
+    - Report total test count and coverage.
+    - Recommend running `spell-review` for adversarial review.
+
+Rules:
+- **Fresh context:** do not carry assumptions from previous stories. Re-read what you need.
+- **No scope creep:** only implement what the story specifies.
+- **Test first when possible:** write the test, see it fail, then implement.
+- **Commit atomically:** one story = one commit.
+- **Never skip tests:** if there's no test framework set up, set it up as the first story.
+- **Stuck threshold:** if a story fails 3 consecutive attempts, mark it and move on. Human intervention needed.

package/dist/assets/.github/prompts/spell-open-session.prompt.md

@@ -35,9 +35,26 @@ Use these files first:
 Check `ai-context/system-prompt-context.md` for a `## Next Session Handoff` section.
 
 - If present and **not yet marked consumed** (no `> ✓ Consumed:` line): surface it immediately as `## Picking Up From Last Session` at the very top of your output, before all other sections. Use the `Next concrete action` field as the first item in `## Next Session Plan`. Use the `Active task`, `Active files`, and `Branch` fields to pre-populate the State Snapshot.
-- After surfacing it, mark it consumed by appending `> ✓ Consumed: YYYY-MM-DD` (today's date) on a new line inside the block, then save the file.
+- After surfacing it, apply the Mutation Guard below before appending `> ✓ Consumed: YYYY-MM-DD` (today's date). The marker write is a repository mutation.
 - If the section is absent or already marked consumed: skip this step and proceed with the normal workspace scan.
 
+## Mutation Guard (run lazily before the first repository write)
+
+Do not create a branch during a read-only session. Immediately before the first file edit, generated file, staging action, or other repository mutation, classify the current Git/remote state and apply exactly one path:
+
+| Observed state | Required action before mutation |
+| --- | --- |
+| Supported, authenticated GitHub/ADO remote + trunk checked out | Create and switch the **current worktree only** to `sessions/YYYY-MM-DD-<topic-slug>`, derived deterministically from the focus, handoff active task, or top next action. |
+| Already on a compliant `sessions/YYYY-MM-DD-<topic-slug>` branch | Stay on it; do not create or switch branches. |
+| Noncompliant unpushed branch with no active PR | Rename it to the deterministic session name before mutation. |
+| Branch has an active PR | Stay on the PR branch and report it; never rename a branch backing an active PR. |
+| Current path is a linked worktree | Mutate/switch only the current worktree. Never switch or delete a branch attached to another worktree. |
+| No remote, unsupported remote, or provider authentication unavailable | Stay on the repository trunk. Print `Local-only session: no usable remote merge path; mutations remain on <trunk> and close-session must use its local-only path.` |
+
+A usable merge path requires a configured remote on a supported provider (`github.com`, `dev.azure.com`, or `visualstudio.com`) and authenticated provider tooling. A remote URL alone is insufficient. Re-evaluate immediately before the first mutation so a remote added or removed during the read-only portion is handled from observed state.
+
+If branch creation/rename is required, complete it before writing the handoff consumed marker or any other file. If the guard cannot determine the current worktree, active-PR state, or merge capability, fail closed without mutation and ask for operator direction.
+
 **Drift Check (run before deep context gathering):**
 
 Run the `spell-check-drift` spell first, before building the state snapshot or gathering deep context. Drift compounds the longer a session runs, so catch it early.
@@ -52,13 +69,11 @@ Then produce output in this exact structure:
 
 Before anything else, check:
 
-- **Current branch:** Run `git branch --show-current` in the arcane repo. If not on `main`, run `git worktree list`:
-  - If this is a worktree-backed session, staying on the topic branch is expected (do not require switching to `main`).
-  - If not worktree-backed, warn the user and suggest switching back to `main`.
+- **Current branch:** Run `git branch --show-current` and `git worktree list`. Report the current state; do not switch during this read-only check. Branch creation/switching is owned by the lazy Mutation Guard.
 - **Session branch naming compliance:** Branch names must be human-readable and policy-compliant:
   - Interactive session default: `sessions/YYYY-MM-DD-<topic-slug>` (kebab-case topic from current task/session objective).
   - Disallow random adjective-noun generator names (example: `ideal-disco`) as session defaults.
-  - If current branch is non-compliant and no active PR depends on it, rename branch to a compliant name. If it was already pushed, migrate remote tracking (`git push -u origin <new-name>` then `git push origin --delete <old-name>`), then continue.
+  - If current branch is non-compliant and no active PR depends on it, record the required rename for the Mutation Guard. Do not rename during a read-only session.
   - If an active PR uses the old branch name, do not force-delete the old remote branch; flag it and continue with a follow-up rename plan.
 - **Stale local branches:** Run `git branch --merged main` to list branches already merged that should be deleted.
 - **Tracker configuration check (early):** resolve active tracking settings before planning. Read `.arcane.json` first (if present), then the current feature PRD frontmatter if available: