arcane-cli 0.16.2 → 0.16.4

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

@@ -33,16 +33,28 @@ Workflow:
    - Lessons learned (anything that cost time, surprised the user, or should prevent future mistakes).
    - **Capture tie-in tip:** If this session produced durable analysis worth formalizing (a design, an investigation, a reusable explanation), suggest running `spell-document` before closing so it lands in the right doc. For quick ideas worth keeping but not yet actionable, suggest `spell-save-idea`.
 
+1b. **Verify in-flight async work before writing any output artifact (EF-21). Enforcement: structured spell gate (ARC-023) — this workflow requires the observable state of every dispatched item before proceeding to step 2.** "I started it" is not "it worked." Before the journal, TODO.md, or the handoff are written, enumerate every piece of asynchronous work dispatched during this session that could still be running or could have failed after being kicked off — CI/CD runs, deployments, package publishes, long-running background tasks, PR checks. For each, **actively check** its current status through whatever means is available (CI provider API/CLI, deployment dashboard, `gh run view`, `az pipelines runs show`, etc.) — attempt the check before reaching for `unverifiable`; that state exists for genuine access limits (no CLI/API access, no credentials, provider outage), not for skipping a check that was merely inconvenient to run. Then classify into exactly one state:
+
+    - **succeeded** — confirmed complete and correct. Only this state may be described as "done," "completed," or "shipped" anywhere in the journal, TODO.md, or the handoff.
+    - **failed** — confirmed to have failed. Record as a blocker or carry-forward item, never as done.
+    - **pending** — still running at last check. Record as in-flight; do not describe as complete.
+    - **dispatched** — kicked off, but no result has been observed at all (the letter was handed to the post office — you know it was sent, not whether it arrived).
+    - **unverifiable** — only after genuinely attempting the check above and finding this environment cannot query the target system. State the exact command, URL, or action the operator must run to check it themselves — a bare "unverifiable" with no next step is barely better than silence, and reaching for this state without attempting the check first defeats the purpose of this step as surely as skipping it entirely.
+
+    A commit succeeding, code being pushed, or a build being triggered are all **dispatched**, not **succeeded** — do not write any of them as complete until independently confirmed. Carry every non-succeeded item into the handoff's `Pending Verification` field (step 5b), and into `Last completed step` worded as not-yet-complete (also step 5b).
+
+    Step 10's existing PR-merge check ("Verify through the detected provider that the PR is merged before changing branches") is this same requirement applied to one specific, already-shipped case — the close-session's own PR. Running step 10 does not substitute for step 1b's sweep of everything else dispatched this session, and step 1b does not substitute for step 10's specific merge check; both apply.
+
 2. **Update today's journal file** at `journal/YYYY-MM-DD-topic-slug.md`.
    - If it exists and already has a session section from this chat, **update that section in place** (do not create a duplicate).
    - If it exists but has no section for this session, **append** a new `## Session: <title>` section.
    - If it does not exist, **create** it using the existing journal frontmatter style.
    - Journal entries must include:
      - `### Prompt Context` — original prompt text or a faithful paraphrase of the multi-turn request when the session began from a substantive user ask. Include follow-up scope inputs if they materially changed the direction of the work.
-     - `### What Got Done` — numbered list of concrete outcomes with file/ADR references.
+     - `### What Got Done` — numbered list of concrete outcomes with file/ADR references. Only list an outcome here if step 1b classified it `succeeded` (or it never involved async work at all, e.g. a local file edit). A `pending`/`dispatched`/`unverifiable` item belongs in Open Items Carried Forward, not here — do not let this section imply completion step 1b couldn't confirm.
      - `### Decisions Made` — table of ADR number, decision, and rationale. If no decisions were made, omit this section.
      - `### Lessons Learned` — one heading per lesson with enough context to prevent the mistake again. Use narrative, not bullet fragments.
-     - `### Open Items Carried Forward` — items that remain undone from this session.
+     - `### Open Items Carried Forward` — items that remain undone from this session, including every `pending`/`dispatched`/`failed`/`unverifiable` item from step 1b.
 
 3. **Update [DECISIONS.md](../../DECISIONS.md).**
    - Add ADRs for any decisions made during the session (naming choices, tool preferences, workflow standards, security policies, etc.).
@@ -50,7 +62,7 @@ Workflow:
    - Follow the existing format: Date, Status, Context, Decision, Reasoning, Rejected alternatives.
 
 4. **Update [TODO.md](../../TODO.md).**
-   - Mark verifiably completed items as done with date.
+   - Mark an item done with date only if step 1b classified its outcome `succeeded` (or it required no async verification at all). A `pending`, `dispatched`, `failed`, or `unverifiable` item stays open, regardless of how confident the session felt about it.
    - Keep unresolved items open.
    - Remove completed checklist items only when completion is documented in the correct source-of-truth file.
 
@@ -69,11 +81,12 @@ In `ai-context/system-prompt-context.md`, replace the existing `## Next Session
 > Generated: YYYY-MM-DD
 
 - **Active task:** One-line description of the task that was in progress when this session closed.
-- **Last completed step:** The final concrete action taken — include file path or command text.
+- **Last completed step:** The final concrete action taken — include file path or command text. If that action was async work step 1b classified as anything other than `succeeded`, do not describe it as done here — name the action in `dispatched`/in-progress terms (e.g. "Pushed the fix and opened PR #NN" is fine; "Merged PR #NN" is not, unless step 1b confirmed the merge) and let `Pending Verification` carry the actual state.
 - **Next concrete action:** The exact first thing to do at next session start. Be specific: file, command, or decision. Never write "continue work."
 - **Active files:** Files with uncommitted changes or the focus of the last edit (comma-separated).
 - **Branch:** Output of `git branch --show-current`.
 - **Blockers:** Known unresolved blockers or dependencies. Write "None" if clear.
+- **Pending Verification:** One line per non-`succeeded` item from step 1b: `<what> — <state> — <verification action>`. States: `dispatched`, `pending`, `failed`, `unverifiable` (never list a `succeeded` item here — it belongs in `Last completed step` / TODO.md / the journal instead, worded per the gating above). The verification action is required for `dispatched`, `pending`, and `unverifiable` — "N/A" is only valid for `failed`, where the state is already resolved and there is nothing left to check. Write "None" only if step 1b found every dispatched item resolved to `succeeded` or `failed` before this handoff was written.
 - **Notes:** Anything time-sensitive, fragile, or contextual that would be lost if not stated explicitly.
 ```
 
@@ -101,7 +114,8 @@ Rules:
 
 9. **Stage and commit session-close docs.**
 
-   **Remote-capability check:** classify the state created by `spell-open-session` before branching, staging, push, or PR operations.
+   **Remote-capability check:** classify the state created by `spell-open-session` before branching, staging, push, or PR operations. Check for **not a repository at all** first — every other classification assumes a `.git` directory exists.
+   - **Not a Git repository (EF-05):** `git rev-parse --is-inside-work-tree` fails. Do not attempt any git operation (branch, add, commit, push). Fail closed with: `No Git repository detected. Run \`git init -b main\` first (explicit -b avoids landing on "master" on systems where that's the init.defaultBranch default), then re-run spell-close-session.` This mirrors `spell init`'s own next-steps guidance for the same state.
    - **Usable supported remote/merge path:** requires an authenticated supported provider (`github.com`, `dev.azure.com`, or `visualstudio.com`). Keep the current compliant session/PR/worktree branch, resolve the actual remote name and integration branch, and use the provider-neutral PR path below.
    - **No usable remote/merge path:** remain on the current trunk. Do not create a dead session branch, push, pull, or open a PR. Apply the EF-28 interactive commit approval gate, commit locally on trunk after approval, report `Local-only close: committed on <trunk>; no remote PR/pull performed`, and skip steps 9a, 9c, and 10's remote operations.
    - **Read-only session:** if no repository mutation occurred, do not create a branch or commit.
@@ -196,7 +210,7 @@ Route the user to the right next spell based on the end state:
 
 Rules:
 
-- Do not invent completions — only mark items done if verifiable from context.
+- Do not invent completions — only mark items done if verifiable from context. "Verifiable" means classified `succeeded` under step 1b's five-state vocabulary (`dispatched`/`pending`/`succeeded`/`failed`/`unverifiable`), not merely "I can see it was started" (EF-21).
 - Keep frontmatter date values in `YYYY-MM-DD`.
 - Preserve existing checklist and journal style.
 - Keep edits minimal and factual.

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

@@ -35,6 +35,7 @@ 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.
+- **If the handoff's `Pending Verification` field lists anything other than "None" (EF-21):** surface each listed item explicitly, then actively re-check its current status (per the item's stated verification action) rather than treating the state recorded at close-session time as still current — a `dispatched`/`pending` item may have since succeeded, failed, or still be running, and carrying it forward as inert text would repeat the exact failure mode this field exists to prevent. Report what you found (resolved succeeded / resolved failed / still pending / still unverifiable) before relying on anything downstream that depended on it.
 - 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.
 

package/dist/assets/ai-context/system-prompt-context.md

@@ -29,4 +29,5 @@
 **Active files:** —
 **Branch:** main
 **Blockers:** None.
+**Pending Verification:** None.
 **Notes:** —

package/dist/index.js

@@ -1751,13 +1751,50 @@ async function inspectGitRepository(cwd) {
     uncommittedChanges: lines.length === 0 ? 0 : lines.split("\n").length
   };
 }
-async function countUncommittedChanges(cwd) {
+async function correctUnbornMasterDefault(cwd) {
+  let current;
   try {
-    const { stdout } = await runGit(cwd, ["status", "--porcelain", "-uall"]);
-    const lines = stdout.trim();
-    return lines.length === 0 ? 0 : lines.split("\n").length;
+    const { stdout } = await runGit(cwd, ["symbolic-ref", "--short", "HEAD"]);
+    current = stdout.trim();
   } catch {
-    return 0;
+    return { corrected: false, to: "main" };
+  }
+  if (current !== "master") {
+    return { corrected: false, to: "main" };
+  }
+  try {
+    await runGit(cwd, ["rev-parse", "--verify", "HEAD"]);
+    return { corrected: false, to: "main" };
+  } catch {
+  }
+  try {
+    await runGit(cwd, ["rev-parse", "--verify", "refs/heads/main"]);
+    return { corrected: false, to: "main" };
+  } catch {
+  }
+  await runGit(cwd, ["symbolic-ref", "HEAD", "refs/heads/main"]);
+  return { corrected: true, from: current, to: "main" };
+}
+async function ensureLocalPullRebase(cwd) {
+  let rawLocalValue;
+  try {
+    const { stdout } = await runGit(cwd, ["config", "--local", "--get", "pull.rebase"]);
+    rawLocalValue = stdout.trim();
+  } catch {
+    rawLocalValue = void 0;
+  }
+  if (rawLocalValue === void 0) {
+    await runGit(cwd, ["config", "--local", "pull.rebase", "true"]);
+    return { action: "set" };
+  }
+  try {
+    const { stdout } = await runGit(cwd, ["config", "--local", "--type=bool", "--get", "pull.rebase"]);
+    if (stdout.trim() === "false") {
+      return { action: "explicit-false-preserved" };
+    }
+    return { action: "already-set" };
+  } catch {
+    return { action: "already-set" };
   }
 }
 
@@ -1837,21 +1874,42 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
   console.log(chalk2.hex("#a855f7")(`
   \u2726 Arcane v${packageVersion}
 `));
+  let repoNotFound = false;
   if (!options.dryRun) {
-    const dirtyCount = await countUncommittedChanges(targetDir);
-    if (dirtyCount > 0) {
-      printWarning(`This repo has ${dirtyCount} uncommitted change${dirtyCount === 1 ? "" : "s"}.`);
-      printInfo("Running spell init will add new files to your working tree.");
-      console.log();
-      const continueAnyway = await confirm({
-        message: "Continue anyway?",
-        default: true
-      });
-      if (!continueAnyway) {
-        console.log("\nCancelled. Commit or stash your changes first.");
-        return;
+    const gitState = await inspectGitRepository(targetDir);
+    if (gitState.status === "not-repository") {
+      repoNotFound = true;
+    } else {
+      if (gitState.status === "no-commits") {
+        const correction = await correctUnbornMasterDefault(targetDir);
+        if (correction.corrected) {
+          printInfo(
+            `Repointed the unborn branch from "${correction.from}" to "${correction.to}" (avoids the Git for Windows default-branch trap).`
+          );
+        }
+      }
+      if (gitState.status === "ready" && gitState.uncommittedChanges > 0) {
+        printWarning(
+          `This repo has ${gitState.uncommittedChanges} uncommitted change${gitState.uncommittedChanges === 1 ? "" : "s"}.`
+        );
+        printInfo("Running spell init will add new files to your working tree.");
+        console.log();
+        const continueAnyway = await confirm({
+          message: "Continue anyway?",
+          default: true
+        });
+        if (!continueAnyway) {
+          console.log("\nCancelled. Commit or stash your changes first.");
+          return;
+        }
+        console.log();
+      }
+      const rebaseResult = await ensureLocalPullRebase(targetDir);
+      if (rebaseResult.action === "explicit-false-preserved") {
+        printWarning(
+          "This repo's pull.rebase is explicitly set to false, but Arcane's governance mandates rebase-and-fast-forward (see .arcane/governance/git-conventions.md). Left as-is since you set it explicitly."
+        );
       }
-      console.log();
     }
   }
   let profile = options.profile;
@@ -2000,6 +2058,12 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
       "Review .arcane/governance/ docs and customize for your project"
     );
   }
+  if (repoNotFound) {
+    printNextStep(
+      step++,
+      'Initialize Git for this project: `git init -b main` (avoids defaulting to "master" on systems where that\'s the system default)'
+    );
+  }
   printNextStep(
     step++,
     "Commit the new files: git add .arcane .github .claude AGENTS.md CLAUDE.md .arcane.json"
@@ -2680,6 +2744,29 @@ async function checkArcaneManifest(targetDir) {
     };
   }
 }
+async function checkPullRebase(targetDir) {
+  const name = "Git pull.rebase (rebase-and-fast-forward mandate)";
+  try {
+    const { stdout } = await runGit(targetDir, ["config", "--type=bool", "--get", "pull.rebase"]);
+    const value = stdout.trim();
+    if (value === "true") {
+      return { name, passed: true, message: "pull.rebase=true" };
+    }
+    return {
+      name,
+      passed: false,
+      message: `pull.rebase resolves to "${value}", not "true" -- a bare \`git pull\` will create merge commits, contradicting git-conventions.md's rebase-and-fast-forward mandate. Run: git config --local pull.rebase true`,
+      blocking: false
+    };
+  } catch {
+    return {
+      name,
+      passed: false,
+      message: "pull.rebase is unset, not a recognized boolean, or this isn't a Git repository -- effective behavior may not be rebase-and-fast-forward, and Git for Windows defaults this to false when unset. Run: git config --local pull.rebase true",
+      blocking: false
+    };
+  }
+}
 function checkIncidentReleaseGate() {
   const result = evaluateIncidentGate(INCIDENT_QUEUE);
   if (result.blocked) {
@@ -2742,7 +2829,8 @@ async function runDoctor(targetDir, options = {}, assetsDir) {
     checkNodeVersion(),
     checkVSCodeExtension("GitHub.copilot-chat", "GitHub Copilot (Chat)"),
     checkArcaneManifest(targetDir),
-    Promise.resolve(checkIncidentReleaseGate())
+    Promise.resolve(checkIncidentReleaseGate()),
+    checkPullRebase(targetDir)
   ]);
   const sessionResults = await checkSessionContinuity(targetDir);
   results.push(...sessionResults);