@aperant/framework 0.8.0 → 0.8.4

package/CHANGELOG.md

@@ -3,7 +3,317 @@
 All notable changes to `@aperant/framework` are documented here. See
 [`VERSIONING.md`](VERSIONING.md) for the per-tier contract.
 
-## [Unreleased]
+## 0.8.4 — 2026-05-22 — `/apt:update` polish + `apt:handoff`, `apt:caveman` skills + `apt:resume` HANDOFF discovery
+
+Bundled release: five `/apt:update` fix bundles (converged from a 3-round
+Codex sparring session at `.aperant/spar/apt-update-fixes-20260522-083919.md`,
+resolving 9 reported issues + 2 hidden defects) plus two new skills and one
+extended skill.
+
+> **VERSIONING.md note.** New skills normally trigger MINOR per the
+> contract. Operator opted for PATCH here because the surface area is
+> small (2 skills, 1 extension) and the apt:update polish is the load-
+> bearing change. Future MINOR bumps remain reserved for transform /
+> manifest / CLI flag additions.
+
+### Added
+
+- **`/apt:handoff`** (new skill at `packages/framework/skills/apt-handoff/SKILL.md`).
+  Agent-to-agent handoff — compacts the current conversation into a
+  `HANDOFF.md` artifact under `.aperant/handoffs/{id}/` (or
+  `{task_dir}/handoffs/{id}/` when inside a routed task), indexed via a
+  new `.aperant/HANDOFFS_INDEX.md`. Distinct from `/apt:pause` along
+  four axes: trigger (agent vs human), audience (different agent vs
+  future-self), uncommitted-work handling (does NOT stash), and index
+  file. `stage: pause`, `intent: capture`, `task_context: none`.
+- **`/apt:caveman`** (new skill at `packages/framework/skills/apt-caveman/SKILL.md`).
+  Ultra-compressed terse output mode — toggles a persistent "smart
+  caveman" style that cuts conversational token usage while keeping
+  full technical accuracy. `stage: ops`, `intent: configure`,
+  `allowed-tools: ""`.
+
+### Changed
+
+- **`/apt:resume`** now discovers HANDOFF artifacts in addition to
+  CONTINUE artifacts. New step `1b` reads `.aperant/HANDOFFS_INDEX.md`;
+  step `1d` scans `.aperant/{tasks/*/handoffs,handoffs}/*/HANDOFF.md` as
+  fallback. The Present Sessions list tags each row `[pause]` or
+  `[handoff]` (handoffs render first — higher urgency). Step 3 splits
+  into `3a` (pause: read CONTINUE.md, pop stash) vs `3b` (handoff: read
+  Focus, verify external state, do NOT pop stash). Cleanup removes the
+  matching index row regardless of type.
+
+### Fixed
+
+- **Bundle A — Workspace-aware version detection.** New helper
+  `findWorkspaceFrameworkVersion(targetDir)` walks up to a sibling
+  `packages/framework/package.json` (max 6 frames, mirroring
+  `route/drift-detect.mjs:32`). The SessionStart worker cache + the
+  `apt-tools check-version --json` envelope now carry an additive
+  `framework.workspace_version: string | null` field. When the
+  workspace is ahead of the running kernel, `update_available` flips
+  true regardless of npm cache state — the workspace is the source of
+  truth on self-host. `--from-source` flag preserved as explicit
+  override per ID-03. Resolves issues 1, 7, 9.
+- **Bundle B — Idempotent kernel install.** `installKernel` short-
+  circuits when the kernel package.json already reports the target
+  version AND the kernel binary exists. Returns the same
+  `status: 'installed'` envelope with `reason: 'already at target
+  version'` + `durationMs: 0` so the three downstream consumers
+  (init.mjs:1441, init.mjs:1735, SKILL.md Scenario D) keep their
+  existing branching. No new enum value (D-02). Resolves issues 5, 6.
+- **Bundle C — SKILL.md doc gaps.** Adds the `pnpm install --filter
+  @aperant/framework... --frozen-lockfile=false` precondition before
+  the `pnpm pack` recipe (AC6); adds a hard warning against
+  substituting `npm pack` — names the `workspace:*` literal +
+  `EUNSUPPORTEDPROTOCOL` keyword (AC7); adds a `Migrated:` line slot
+  to all three Scenario A/B/C templates, conditional on
+  `legacy_cleanup?.ran === true && rmdirs.some(p => p.includes('.codex'))`
+  (AC8). Resolves issues 2, 4, 8.
+- **Bundle D — Workspace-dep chain.** New CLI subcommand
+  `apt-tools install-from-source <project-dir>` walks workspace
+  `dependencies` + `peerDependencies` for `workspace:*` entries
+  (matching by package `name`, not directory name —
+  `@aperant/driver-sdk` lives at `packages/framework-driver-sdk/`),
+  pnpm-packs each, then invokes a single `npm install --prefix
+  .aperant/deps <tarball-list>...` with the existing kernel-install
+  flag set (`--no-save`, `--no-package-lock`, `--no-audit`,
+  `--no-fund`). Handles the same-PR unpublished-pair case
+  (`framework@X` + `driver-sdk@Y` both at `workspace:*`, both
+  unpublished) without `EUNSUPPORTEDPROTOCOL`. SKILL.md §1.7
+  simplified to a single apt-tools invocation; the manual recipe
+  preserved as a debugging-aid footnote. Resolves issue 3.
+- **Bundle E — Init comment inversion + Scenario A null-latest.**
+  Fixed `init.mjs:1253-1268` comment + stderr direction (LEGACY =
+  `.codex/`, CURRENT = `.agents/skills/<folder>/SKILL.md`; was
+  reversed; the v0.8.2 inversion is documented in
+  `runtime-migrate.mjs:7-12`). Scenario A now requires
+  `latest_version != null` to avoid false "version bump" chips when
+  npm-latest is unknown (cache stale, not published, network down).
+  New Scenario E ("no version info available") branch handles that
+  case explicitly — refreshes runtime files for safety, tells the
+  user the bump is deferred. Resolves 2 hidden defects.
+
+### Schema status
+
+Envelope changes are strictly additive — the new
+`framework.workspace_version` field is nullable, existing callers
+ignore unknown fields. **No `schema_version` bump** (cache stays at
+`1`, locked by `update-chips.mjs:97-98` + the
+`check-version-cache-merge.test.ts:137-148` schema-2 rejection
+regression test).
+
+### Decision source
+
+Codex sparring session 2026-05-22 (3 rounds, CONVERGED).
+
+### Tests
+
+- **New:** `find-workspace-framework-version.test.ts`,
+  `install-kernel-idempotent.test.ts`,
+  `apt-update-skill-doc-gaps.test.ts`, `install-from-source.test.ts`,
+  `init-legacy-cleanup-direction.test.ts` (5 files / 23 new cases).
+- **Augmented:** `check-version-cache-merge.test.ts` (+2 cases for
+  the workspace_version envelope field).
+- **Regression-locked:** `apt-update-from-source-skill-structure.test.ts`,
+  `route-source-drift-detection.test.ts`, `legacy-cleanup-codex.test.ts`,
+  `check-version-cache-merge.test.ts` (existing schema_version=2
+  rejection at `:137-148`). All still pass.
+
+## 0.8.3 — 2026-05-21 — FRAMEWORK-RFC-001 — `/apt:spar` pipeline integration with install-time consent
+
+Minor patch release. Flips `/apt:spar` from manual-only (SPAR-07 v1) to
+pipeline-integrated under explicit install-time consent. Adds a per-device
+opt-in question to `/apt:setup` Batch 2 Pipeline; wires `/apt:run` and the
+`/apt` router to honor it with track-aware gates (QUICK rejects, STANDARD
+= `plan` gate, DEEP = `plan,execute` gates); updates SPAR-07 wording.
+Per-invocation `--spar-gates` flag remains as the manual override path;
+rounds always defer to the skill default to avoid reintroducing
+FRAMEWORK-BUG-038.
+
+### What
+
+- **`SparConfig` schema delta** — three per-device fields land in
+  `.aperant/config.local.json` per AUDIT-001: `spar.enabled: boolean`,
+  `spar.partner: 'codex' | 'claude' | 'gemini' | null`, `spar.hint?: boolean`.
+  Added to `packages/framework/src/types/config.ts` as
+  `AperantConfig.spar?: SparConfig`. No migration path needed — spar lands
+  in `config.local.json` from day one with no shared-config legacy.
+
+- **`apt-setup` Sparring Auto-Fire (Batch 2)** — 3-phase question block
+  inserted after PR Review Auto-Suggest:
+  - Phase 1 (Yes/No): master switch.
+  - Phase 2 (partner picker, only if Yes): reads
+    `host.partner_transports.{codex,claude,gemini}` from
+    `apt-tools host-detect` to filter by availability, AND excludes
+    `host.cli` (Open Q1 same-host filter). Graceful skip with
+    `spar.enabled: true, spar.partner: null` when zero partners detected.
+  - Phase 3 (hint sub-picker, only if No): opt-in to per-stage reminder
+    `[apt] {stage} complete. /apt:spar available before next stage.`
+  All three fields route through `writeLocalConfigField` per AUDIT-001.
+
+- **`apt-run` flag + gate handlers** —
+  - `--spar-gates <plan|execute|plan,execute>` flag (per-invocation
+    override of merged-config consent). QUICK hard-rejects with verbatim
+    `[apt:run] --spar-gates ignored for QUICK track (Fast Path Guarantee)`.
+  - §3b "Stage 1.5 — Spar Gate (plan)": resolves effective gates, composes
+    topic frame from spec.md §Scope (task description fallback per
+    Open Q4), dispatches `/apt:spar --timeout-ms 120000 [--with <partner>]`
+    with NO `--rounds` flag (FRAMEWORK-BUG-038 regression guard).
+  - §4b "Stage 2.5 — Spar Gate (execute)": same logic, gate name
+    `"execute"`, topic frame from `build-progress.json`.
+  - Pipeline-mode `--timeout-ms 120000` (2-min Bash-rung fast-fail) is
+    asymmetric with manual mode (5min/15min defaults). Worst-case DEEP
+    wall budget: 2 gates × 3 rounds × 2 min = 12 min (vs ~90 min before
+    this clamp under MCP-rung partner degradation).
+  - §5 Verify spawn context: verifier reads Layer 2 spar findings
+    (`.aperant/spar/<slug>-<ts>.md`) before scoring.
+  - Per-stage `spar.hint` nudge at each of plan/execute/verify/review
+    Output: anchors (4 conditional prints, gated on
+    `spar.hint === true && spar.enabled === false`).
+
+- **`apt` router envelope contract (load-bearing AC11)** — `route.mjs`
+  emits two deterministic consent fields:
+  - `envelope.spar_inject_gates` (flag-override path): pre-computed gate
+    string `"plan"` (STANDARD) or `"plan,execute"` (DEEP) when consent on
+    AND user did NOT pass explicit `--spar-gates`. Absent for QUICK/DEBUG.
+  - `envelope.spar_consent` (host-LLM path): block
+    `{ enabled, partner, user_passed_explicit_gates }` when consent on.
+    Host model composes `--spar-gates` from spar_consent + chosen track.
+  Both fields ABSENT when consent off — envelope byte-equivalent to
+  pre-RFC shape for users who never opted in. `apt/SKILL.md` MODE: classify
+  Step 4 reads ONLY the envelope (never re-reads merged config from
+  prompt-space) — structural test grep-locks this invariant.
+
+- **`apt-plan` + `apt-execute` `--spar` flags** — end-of-process dispatch
+  to `/apt:spar` against local artifacts (spec.md / build-progress.json).
+  Same `--timeout-ms 120000` + no-rounds discipline. Per-skill manual
+  surface for users who don't use `/apt:run` end-to-end.
+
+- **`apt-spar/SKILL.md` SPAR-07 wording** — updated from v1
+  "manually invoked only" to v2 "honors install-time consent". §1-§9
+  process body is byte-equivalent to pre-edit baseline (sha256
+  9c2852ce…7da7b3 preserved by `apt-spar-pipeline-manual-path-preserved.test.ts`
+  hash guard). Manual `/apt:spar` invocation path UNCHANGED.
+
+### Why
+
+Founder usage data confirmed that cross-provider sparring surfaces
+blind-spot defects that single-provider review misses. SPAR-07's v1
+escape hatch was always deferred-pending-data; the data is in. Pipeline
+integration removes the per-task `--spar-gates` flag drudgery while
+preserving QUICK Fast Path Guarantee + manual override surfaces.
+
+### Compatibility
+
+- Backward-compatible. Users who never opt in to `spar.enabled: true`
+  see identical behavior to 0.8.2 — envelope shape byte-equivalent,
+  apt-run pipeline unchanged.
+- Manual `/apt:spar` invocation path BYTE-EQUIVALENT (process body
+  hash-locked).
+- `--spar-gates` flag is opt-in per-invocation. QUICK hard-rejects.
+- Migration: no path needed. Spar lands in `config.local.json` from day
+  one; no shared-config legacy.
+
+### Out of scope (follow-up RFC-001-b candidates)
+
+- Verify-stage spar gate (deferred — verify already iterates fix-and-retry).
+- Pre-ship spar gate (likely redundant with `/apt:pr-review`).
+- Multi-partner concurrent spar (use `/apt:roundtable` for 10-agent).
+- Re-plan-on-spar-cede behavioral feedback loop.
+- `--mcp-timeout-ms` per-invocation flag on `apt-spar` (Open Q5 —
+  MCP-rung pipeline tightening). Today MCP rung is config-only at
+  `apt-spar.mcp_timeout_ms`; pipeline mode accepts the asymmetry.
+
+### Version
+
+- `packages/framework/package.json`: 0.8.2 → 0.8.3
+
+### Commits
+
+- `4d67ca1d` feat(framework): add SparConfig schema for RFC-001 pipeline consent
+- `e301b776` feat(framework): apt-setup Sparring Auto-Fire prompt (RFC-001 install-time consent)
+- `20dea366` feat(framework): update SPAR-07 wording to v2 install-time consent contract
+- `3f9ef384` feat(framework): apt-run --spar-gates flag parsing + QUICK hard-reject
+- `be06429a` feat(framework): apt-run §3b + §4b spar-gate handlers
+- `36c7702d` feat(framework): emit spar_inject_gates + spar_consent envelope fields
+- `d803f8c5` feat(framework): apt router consent-driven --spar-gates auto-inject
+- `726ae3f5` feat(framework): apt-plan + apt-execute --spar per-skill flag
+- `e796580e` feat(framework): apt-run spar.hint nudge at stage success-ends
+
+## 0.8.2 — 2026-05-21 — Codex skill-discovery regression fix
+
+Codex skill-discovery regression fix — install now writes to the
+documented `.agents/skills/<folder>/SKILL.md` surface.
+
+### Fixed
+
+- Codex `installRoot` re-targeted from `.codex` to `.agents` so SKILL.md
+  lands at `<targetDir>/.agents/skills/<folder>/SKILL.md` per
+  https://developers.openai.com/codex/skills. The previous v0.7/v0.8
+  `.codex/agents/` + `.codex/commands/` topology was a dead surface
+  (Codex CLI 0.132.0 doesn't discover skills there) and a fresh
+  `apt-tools init . --codex` reported 95 files installed while
+  `codex debug prompt-input` listed zero apt-* skills.
+- Codex frontmatter strip switched from a 2-key blacklist
+  (`['tools', 'color']`) to an allowed_properties whitelist
+  (`KEEP = ['name', 'description']`), matching
+  `~/.codex/skills/.system/skill-creator/scripts/quick_validate.py:40`
+  and the working third-party skill examples. Drift-proof: any new
+  framework frontmatter key is dropped from Codex output without
+  breaking the validator.
+- Codex transform now emits a single output (`skills/<folder>/SKILL.md`)
+  per canonical skill. The previous two-output emission
+  (`agents/<folder>.md` + `commands/<folder>.md`) is dropped along with
+  the `fileType === 'agent'` branch (markdown agents are not a Codex
+  surface; Codex custom-agents are TOML under `.codex/agents/`).
+- `runLegacyCleanup` now GCs the v0.7/v0.8 `.codex/agents/apt-*.md` +
+  `.codex/commands/apt-*.md` + `.codex/apt-file-manifest.json` misdirect
+  on the next `apt-tools init . --codex`. `.codex/config.toml` and any
+  user-added `.codex/` content is preserved.
+
+### Changed
+
+- `getTrustedSkillSources` now skips the Codex install root in the
+  per-cli filter (`cli !== 'codex'` guard). Keeps
+  `.aperant/logs/route-dropped.jsonl` clean for router invocations on
+  Codex hosts — Codex's stripped frontmatter would otherwise fail
+  `SkillFrontmatterSchema`. Canonical + kernel roots still serve
+  routing.
+- `LEGACY_INSTALL_PATHS` schema gains a `honor_manifest?: boolean`
+  field (default `true`). When `false`, a present
+  `apt-file-manifest.json` at the legacy root does NOT trigger the
+  managed-no-op — used for known-dead surfaces like the v0.7/v0.8
+  codex misdirect. Existing legacy entries are unaffected (default true
+  preserves the managed-install safety).
+
+### Version
+
+- `packages/framework/package.json`: 0.8.1 → 0.8.2
+
+## 0.8.1 — 2026-05-20 — Pi runtime + idempotent re-init repair
+
+Patch release making `apt-tools init` safe to rerun on another machine after
+pulling a current `.aperant/config.json`.
+
+### Fixed
+
+- Current-schema `init` no longer returns `up_to_date` when explicit runtime
+  flags were passed or when suggested runtime roots are missing
+  `apt-file-manifest.json`; it reruns the runtime installer for those roots.
+- True no-op behavior is preserved when no runtime roots are suggested and no
+  explicit runtime flags are passed.
+
+### Added
+
+- Pi is now an installable runtime via `--pi`, with files written under
+  `.pi/skills/` and `.pi/prompts/`.
+- `cliToInstallRoot('pi')` now resolves to `.pi`.
+
+### Version
+
+- `packages/framework/package.json`: 0.8.0 → 0.8.1
+- CLI golden fixtures refreshed
 
 ## 0.8.0 — 2026-05-20 — cross-task fan-out + 5 framework defects (BUG-033..038)
 

package/README.md

@@ -11,6 +11,12 @@
 npx @aperant/framework init .
 ```
 
+For non-interactive install or re-init across common runtimes:
+
+```bash
+npx @aperant/framework init . --claude --codex --pi --yes
+```
+
 ## Usage
 
 Just type `/apt` and describe what you want in natural language. The router classifies your input and dispatches to the right skill.
@@ -25,6 +31,12 @@ Just type `/apt` and describe what you want in natural language. The router clas
 
 You can also call any skill directly (e.g. `/apt:plan ...`, `/apt:debug ...`).
 
+Runtime command surfaces differ slightly:
+
+- Claude: `/apt:plan`
+- Codex: `/apt-plan`
+- Pi: `/apt`, `/apt:plan` via `.pi/prompts/`
+
 ## Available commands
 
 | Stage | Command | Purpose |

package/agents/apt-planner.md

@@ -32,7 +32,8 @@ Before planning, discover project context:
 <environment>
 - **Working directory:** The project root
 - **apt-tools:** Always invoke as `node packages/framework/bin/apt-tools.mjs`
-- **Task directory:** Provided in the spawn prompt as `task_dir`. ALL artifacts (spec.md, implementation_plan.json) are written here, NOT to project root.
+- **Task directory:** Provided in the spawn prompt as `task_dir`. It MUST be an absolute path under the main repo's `.aperant/tasks/{task-id}/`. ALL artifacts (spec.md, implementation_plan.json) are written here, NOT to project root and NOT to a worktree-local `.aperant/tasks/` directory.
+- **Worktree path:** If provided, use it only for code investigation/editing context. Do not derive artifact paths from it.
 - **Config:** `.aperant/config.json` — project preferences
 - **State:** `.aperant/state.json` — execution state
 </environment>
@@ -43,7 +44,7 @@ Before planning, discover project context:
 
 1. Read `CLAUDE.md` and `AGENTS.md` if they exist — extract conventions, stack, constraints
 2. Run `node packages/framework/bin/apt-tools.mjs state .` to understand current project state
-3. Parse the task description and task_dir from the spawn prompt
+3. Parse the task description and task_dir from the spawn prompt. If task_dir is relative, resolve the real main repo path first instead of writing under the current worktree.
 
 ## 2. Assess Complexity
 
@@ -211,7 +212,7 @@ If unable to enumerate (network unavailable, action docs unclear), flag it expli
 
 ## 4. Write Specification
 
-The spec.md content format **branches on track** (Pocock adoption ID-05,
+The spec.md content format **branches on track** (ID-05,
 Fast Path Guarantee). QUICK-routed tasks keep the existing 4-section
 shape; STANDARD/DEEP/COMPLEX tasks get a PRD-shaped artifact that
 survives the task as a second-consumer document.
@@ -344,7 +345,7 @@ fix it now, not later.
 
 ## 5. Create Implementation Plan
 
-Subtask schema branches on track (Pocock adoption ID-05 — Fast Path Guarantee).
+Subtask schema branches on track.
 
 ### 5.A. QUICK track / SIMPLE complexity — legacy flat subtask schema
 

package/dist/cli/commands/adr.mjs

@@ -1,5 +1,5 @@
 /**
- * commands/adr.mjs — `apt-tools adr write` (Pocock adoption ST-6, AC5).
+ * commands/adr.mjs — `apt-tools adr write`.
  *
  * Writes an ADR under `docs/adr/NNNN-slug.md` ONLY when all three Nygard
  * gates pass: hard-to-reverse AND surprising-without-context AND

package/dist/cli/commands/audit-branch-current.d.mts

@@ -0,0 +1,25 @@
+/**
+ * @param {string} projectDir
+ * @param {string[]} extraArgs
+ */
+export function auditBranchCurrent(projectDir: string, extraArgs?: string[]): import("../util/result.mjs").CommandResult;
+export { parseConflictPaths as __parseConflictPathsForTests };
+/**
+ * Parse `git merge-tree --write-tree --no-messages HEAD origin/<base>` output
+ * for conflict file paths. Modern (git ≥ 2.38) merge-tree emits, on conflict:
+ *
+ *   <tree-OID>
+ *   <conflict report lines, each "<mode> <stage> <oid>\t<path>" for stage > 0>
+ *   (NUL separator)
+ *   <textual conflict messages>
+ *
+ * Older variants emit a `+<<<<<<< ... +======= ... +>>>>>>>` diff per file.
+ * For correctness we use the stable form: extract file paths from the conflict
+ * report. The report includes the SAME path multiple times (once per non-zero
+ * stage), so we de-dupe.
+ *
+ * @param {string} stdout
+ * @returns {string[]}
+ */
+declare function parseConflictPaths(stdout: string): string[];
+//# sourceMappingURL=audit-branch-current.d.mts.map

package/dist/cli/commands/audit-branch-current.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-branch-current.d.mts","sourceRoot":"","sources":["../../../src/cli/commands/audit-branch-current.mjs"],"names":[],"mappings":"AAmIA;;;GAGG;AACH,+CAHW,MAAM,cACN,MAAM,EAAE,8CAgHlB;;AAtKD;;;;;;;;;;;;;;;;GAgBG;AACH,4CAHW,MAAM,GACJ,MAAM,EAAE,CAsBpB"}

package/dist/cli/commands/audit-branch-current.mjs

@@ -0,0 +1,252 @@
+/**
+ * commands/audit-branch-current.mjs — pre-PR rebase gate envelope for apt:ship §0.7.
+ *
+ * Pure read-only branch-drift audit. Given a base ref (default `main`), reports
+ * how many commits HEAD is ahead/behind `origin/<base>`, captures the current
+ * `origin/<base>` tip SHA (the lease target for any subsequent
+ * `--force-with-lease=refs/heads/<branch>:<sha>` push), and probes whether a
+ * trial merge against the remote tip would conflict.
+ *
+ * Single network call: `git fetch origin <base>`. Fetch failure is recovered
+ * as `audit_warning: 'fetch-failed'` — the envelope still returns, just with
+ * stale counts. No `git rebase`, no `git push`, no `git reset` — the SKILL.md
+ * prose owns history rewrites.
+ *
+ * Envelope:
+ *
+ *   {
+ *     status:             'ok',
+ *     command:            'audit-branch-current',
+ *     projectDir:         string,
+ *     base:               string,
+ *     ahead:              number,           // commits HEAD has over origin/<base>
+ *     behind:             number,           // commits origin/<base> has over HEAD
+ *     remote_tip_sha:     string | null,    // origin/<base> after fetch
+ *     mergeable:          boolean | null,   // null when probe unavailable
+ *     conflicts_preview?: string[],         // populated only when mergeable=false
+ *     audit_warning?:     string            // 'fetch-failed' | 'git-version-too-old' | ...
+ *   }
+ *
+ * Spec cross-ref: .aperant/tasks/apt-ship-pre-pr-rebase-gate-audit-branch_21-05-26/spec.md
+ *
+ * @internal
+ */
+import { execFileSync } from 'node:child_process';
+import { resolve } from 'node:path';
+import { err, ok } from '../util/result.mjs';
+/**
+ * Try-execute a git command, returning {ok, stdout, stderr, code}. Never throws.
+ *
+ * @param {string} cwd
+ * @param {string[]} args
+ */
+function gitTry(cwd, args) {
+    try {
+        const stdout = execFileSync('git', args, {
+            cwd,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        return { ok: true, stdout, stderr: '', code: 0 };
+    }
+    catch (e) {
+        // execFileSync throws an error whose `stdout`, `stderr`, and `status`
+        // properties carry the captured output and exit code.
+        return {
+            ok: false,
+            stdout: typeof e?.stdout === 'string' ? e.stdout : (e?.stdout?.toString() ?? ''),
+            stderr: typeof e?.stderr === 'string' ? e.stderr : (e?.stderr?.toString() ?? ''),
+            code: typeof e?.status === 'number' ? e.status : 1,
+        };
+    }
+}
+/**
+ * Parse `--base <ref>` (or `--base=<ref>`) from extraArgs. Defaults to 'main'.
+ *
+ * @param {string[]} extraArgs
+ * @returns {string}
+ */
+function parseBaseFlag(extraArgs) {
+    for (let i = 0; i < extraArgs.length; i++) {
+        const a = extraArgs[i];
+        if (a === '--base' && i + 1 < extraArgs.length)
+            return extraArgs[i + 1];
+        if (a.startsWith('--base='))
+            return a.slice('--base='.length);
+    }
+    return 'main';
+}
+/**
+ * Parse `git merge-tree --write-tree --no-messages HEAD origin/<base>` output
+ * for conflict file paths. Modern (git ≥ 2.38) merge-tree emits, on conflict:
+ *
+ *   <tree-OID>
+ *   <conflict report lines, each "<mode> <stage> <oid>\t<path>" for stage > 0>
+ *   (NUL separator)
+ *   <textual conflict messages>
+ *
+ * Older variants emit a `+<<<<<<< ... +======= ... +>>>>>>>` diff per file.
+ * For correctness we use the stable form: extract file paths from the conflict
+ * report. The report includes the SAME path multiple times (once per non-zero
+ * stage), so we de-dupe.
+ *
+ * @param {string} stdout
+ * @returns {string[]}
+ */
+function parseConflictPaths(stdout) {
+    const paths = new Set();
+    for (const rawLine of stdout.split('\n')) {
+        const line = rawLine.replace(/\0/g, '');
+        if (!line.trim())
+            continue;
+        // Match "<mode> <oid> <stage>\t<path>" — git merge-tree --write-tree
+        // emits conflict report lines as "<mode> <oid> <stage>\t<path>".
+        // Stage 0 means no conflict, so we only surface stage ≥ 1.
+        const m = line.match(/^(\d{6})\s+([0-9a-f]{4,40})\s+(\d)\t(.+)$/);
+        if (m) {
+            const stage = Number.parseInt(m[3], 10);
+            if (stage >= 1)
+                paths.add(m[4]);
+            continue;
+        }
+        // Fallback (older git): the textual report block prefixes paths with
+        // "CONFLICT (content): Merge conflict in <path>".
+        const c = line.match(/Merge conflict in (.+)$/);
+        if (c)
+            paths.add(c[1].trim());
+    }
+    return Array.from(paths).sort();
+}
+/**
+ * Detect "git too old" from merge-tree stderr. Pre-2.38 git rejects
+ * `--write-tree` outright; older still rejects merge-tree's modern arg
+ * shape entirely. We treat any non-zero-with-no-output as "version too old"
+ * — callers are expected to fall back gracefully.
+ *
+ * @param {string} stderr
+ * @returns {boolean}
+ */
+function isGitVersionTooOld(stderr) {
+    return /unknown option|did you mean|usage: git merge-tree/i.test(stderr);
+}
+/**
+ * @param {string} projectDir
+ * @param {string[]} extraArgs
+ */
+export function auditBranchCurrent(projectDir, extraArgs = []) {
+    if (!projectDir) {
+        return err('Usage: apt-tools audit branch-current <project-dir> [--base <ref>]');
+    }
+    const targetDir = resolve(projectDir);
+    const base = parseBaseFlag(extraArgs);
+    /** @type {string | undefined} */
+    let auditWarning;
+    /** @type {string[]} */
+    const warnings = [];
+    // 1. Fetch origin <base>. Tolerate failure (offline, no remote, etc.).
+    const fetch = gitTry(targetDir, ['fetch', 'origin', base]);
+    if (!fetch.ok) {
+        auditWarning = 'fetch-failed';
+        warnings.push(fetch.stderr.trim().split('\n').slice(0, 3).join(' | '));
+    }
+    // 2. Resolve origin/<base> tip.
+    let remoteTipSha = null;
+    const tip = gitTry(targetDir, ['rev-parse', `origin/${base}`]);
+    if (tip.ok) {
+        remoteTipSha = tip.stdout.trim();
+    }
+    else {
+        // No origin/<base> ref at all — emit an envelope with null counts so the
+        // caller can recognise the gap. The SKILL.md prose treats null counts as
+        // "audit unavailable, STOP with a clear message" rather than proceeding.
+        return ok({
+            status: 'ok',
+            command: 'audit-branch-current',
+            projectDir: targetDir,
+            base,
+            ahead: null,
+            behind: null,
+            remote_tip_sha: null,
+            mergeable: null,
+            audit_warning: auditWarning ?? 'no-remote-base-ref',
+            warnings,
+        });
+    }
+    // 3. Counts.
+    let ahead = 0;
+    let behind = 0;
+    const aheadOut = gitTry(targetDir, ['rev-list', '--count', `origin/${base}..HEAD`]);
+    const behindOut = gitTry(targetDir, ['rev-list', '--count', `HEAD..origin/${base}`]);
+    if (aheadOut.ok)
+        ahead = Number.parseInt(aheadOut.stdout.trim(), 10) || 0;
+    if (behindOut.ok)
+        behind = Number.parseInt(behindOut.stdout.trim(), 10) || 0;
+    // 4. Mergeability.
+    //    - When behind === 0, the branch is current or strictly ahead — no
+    //      remote changes to integrate, mergeable = true by definition.
+    //    - When behind > 0 AND ahead === 0, the branch is strictly fast-forward
+    //      behind — a clean fast-forward rebase is always mergeable.
+    //    - When diverged (behind > 0 AND ahead > 0), probe via git merge-tree.
+    let mergeable;
+    /** @type {string[] | undefined} */
+    let conflictsPreview;
+    if (behind === 0) {
+        mergeable = true;
+    }
+    else if (behind > 0 && ahead === 0) {
+        mergeable = true;
+    }
+    else {
+        // Diverged. Run modern merge-tree trial.
+        const probe = gitTry(targetDir, [
+            'merge-tree',
+            '--write-tree',
+            '--no-messages',
+            'HEAD',
+            `origin/${base}`,
+        ]);
+        if (probe.ok) {
+            mergeable = true;
+        }
+        else if (probe.code === 1) {
+            // Documented merge-tree exit-code semantics: 0 clean, 1 conflict,
+            // other = invocation error.
+            mergeable = false;
+            conflictsPreview = parseConflictPaths(probe.stdout);
+        }
+        else if (isGitVersionTooOld(probe.stderr)) {
+            mergeable = null;
+            auditWarning = auditWarning ?? 'git-version-too-old';
+            warnings.push(`git merge-tree --write-tree unsupported: ${probe.stderr.trim().slice(0, 200)}`);
+        }
+        else {
+            // Unknown probe failure — treat as unknown rather than asserting
+            // clean.
+            mergeable = null;
+            auditWarning = auditWarning ?? 'merge-tree-probe-failed';
+            warnings.push(`git merge-tree probe failed (code ${probe.code}): ${probe.stderr.trim().slice(0, 200)}`);
+        }
+    }
+    const envelope = {
+        status: 'ok',
+        command: 'audit-branch-current',
+        projectDir: targetDir,
+        base,
+        ahead,
+        behind,
+        remote_tip_sha: remoteTipSha,
+        mergeable,
+    };
+    if (conflictsPreview && conflictsPreview.length > 0) {
+        envelope.conflicts_preview = conflictsPreview;
+    }
+    if (auditWarning)
+        envelope.audit_warning = auditWarning;
+    if (warnings.length > 0)
+        envelope.warnings = warnings;
+    return ok(envelope);
+}
+// Test-only export for unit-level parser coverage (not part of the public CLI
+// contract).
+export { parseConflictPaths as __parseConflictPathsForTests };
+//# sourceMappingURL=audit-branch-current.mjs.map