axstack 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Axat Bhardwaj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,132 @@
+# Axstack
+
+Axstack is a standalone toolkit for finishing agreed engineering work with less
+supervision while retaining independent review. Chat drives execution; a Bun
+CLI installs owned skills and role data and checks capabilities. Axstack has no
+daemon, scheduler, runtime database, or workflow state machine.
+
+Orca is the only supported active runtime. Its installed, version-matched
+`orchestration` and `orca-cli` guides own worktrees, sessions, supervised
+dispatch, messages, settlement, and handoff mechanics. Axstack owns scope,
+role choices, evidence, review policy, and one private derived run record.
+
+## How a run works
+
+Invoke `axstack` or the needed phase directly: `axstack-align`,
+`axstack-spec`, `axstack-tickets`, `axstack-implement`, `axstack-review`, and
+`axstack-watch`. Direct `axstack-research`, `axstack-explain`,
+`axstack-improve`, and `axstack-debug` routes need no spec ceremony. `axstack-relay` remains an
+optional inline route for explicit messages and authorized notifications; an
+unavailable or legacy-runtime-only relay falls back to the current conversation
+without changing authority.
+
+1. Classify new engineering work as substantial, small, or unclear with a brief
+   reason. Small, bounded one-PR work uses the current request or selected issue
+   as a snapshotted small-change intent;
+   substantial or stacked work needs an approved spec and matching ticket map.
+2. The current chat drives on whatever model runs it; there is no driver
+   profile. Bind each ready task to the selected role snapshot and an authoritative Orca
+   Run, Task, and Dispatch. Exactly one writer owns a candidate at a time.
+3. Peer PRs receive both configured independent reviewer roles. Authored PRs
+   receive one eligible reviewer from the selected preset's explicit mapping
+   and actual author provenance. Every review binds the exact head and base.
+   Stable IDs are `axstack-reviewer-primary` and `axstack-reviewer-secondary`.
+4. Accepted repairs return to the same author where its session and evidence
+   remain valid. The human merges by default, bottom-up for a stack.
+5. Full handoff requires explicit recipient acceptance of the exact scope and
+   authority before ownership changes. Ordinary resume reconciles the current
+   owner instead of replacing it.
+
+Active PR fanout is dependency- and capacity-driven; there is no fixed count.
+Each PR has one theme and a measured size under the shared
+[PR-shape policy](skills/axstack/references/pr-shape.md). Routine shape and
+fanout choices remain autonomous inside approved scope. Material scope,
+serious-risk, unavailable-model, and human-merge holds remain explicit.
+The autonomous driver records the rationale band's cohesion rationale; the exception band needs a
+reasonable split attempt and full exception record. Size alone never requires
+user approval.
+
+## Install from source
+
+Requirements: Bun >=1.3.14, Git, `gh`, the `gh stack` extension, and a running
+Orca with its runtime-owned guides. Filesystem access uses Bun's implementation
+of `node:fs` and `node:fs/promises`; there are no runtime dependencies.
+
+```sh
+bun bin/axstack.js check --bundle . [--harness claude|codex]
+bun bin/axstack.js install --bundle . --skills-dir <dir> --instructions <file> --preset mixed [--yes]
+bun bin/axstack.js install --bundle . --skills-dir <dir> --preset mixed
+bun bin/axstack.js uninstall --skills-dir <dir> --instructions <file>
+```
+
+Use `--harness codex` or `--harness claude` only for a verified default skill
+directory. `--claude-settings` and `--no-claude-settings` manage the existing
+Claude Code subagent default transaction; they do not configure Orca roles.
+See [installation details](docs/installation.md).
+
+`--instructions` manages one versioned Axstack block in `AGENTS.md` or
+`CLAUDE.md`. Harness defaults resolve those files automatically. The block
+points at the installed entry skill and requires delegated work to use visible
+Orca orchestration rather than a harness-native subagent tool. Text and file
+mode outside the markers are preserved; edited, malformed, unowned, or unsafe
+targets are reported without normal-path adoption. Install exits nonzero when
+an instruction conflict is preserved, while clean and idempotent installs exit
+successfully.
+
+The public bundle preserves three canonical 21-role inputs:
+[mixed](profiles/presets/mixed.json),
+[codex-only](profiles/presets/codex-only.json), and
+[claude-only](profiles/presets/claude-only.json). Each is exactly
+`{ "version": 1, "roles": [...] }`. Installation writes the selected snapshot
+to `<skills-dir>/axstack/roles.json` as
+`{ "version": 1, "preset": "<name>", "roles": [...] }` under normal ownership
+hashes. An edited installed role file is preserved.
+
+Mixed configures independent Astra and Fable advisers at high. Single-provider
+presets preserve both adviser IDs and mark the unavailable one with `model:
+null` inside that preset's provider bounds; installation remains ready, while
+Align and Spec hold because both receipts are required. The mixed
+`axstack-checker` model is also intentionally `null`; that role stays held
+instead of inheriting a provider default. The single-provider presets configure
+the checker. Preset changes affect new runs only. Stored model, effort, and permission
+fields are declared intent until actual Orca launch receipts establish effective
+behavior; installation never proves provider availability or permission parity.
+Subscription availability and quota never select a fallback model.
+End-to-end compatibility remains unverified without matching runtime receipts.
+
+## Runtime evidence and holds
+
+Native Orca exercises have returned Codex and Claude worker completions,
+same-terminal follow-up, separate worktree placement, settlement cleanup,
+`user_takeover` retention, and recovery from `consumer_fenced`. These are
+bounded runtime facts, not proof that every role or harness is compatible.
+
+Input acceptance is not agent readiness. A trust prompt was observed after an
+accepted launch, so startup recovery must inspect the existing attempt, never
+answer trust or permission prompts on the worker's behalf, and never create a
+duplicate writer. A `worker_done` advances work only when its Task and Dispatch
+match the active attempt and its revision evidence verifies.
+
+The user lifted the native-watch hold by decision on 2026-09-16. Orca's native automation
+schema exposes a provider but cannot pin model, effort, or permission, so the
+driver automation records its model identity every tick and the watchdog treats
+a mismatch as a safety hold. Axstack uses no historical fallback and introduces
+no custom scheduler. The five-minute driver, hourly read-only watchdog, quiet
+healthy ticks, and shared 24-hour deadline remain the acceptance contract.
+
+Mobile completion/reply behavior remains unverified. Structural checks and
+qualitative scenario evaluation are not live runtime proof.
+
+## Historical migration boundary
+
+Older releases used Paseo for orchestration and could leave profile ownership
+provenance or retired skills behind. That state is historical and inert in the
+Orca runtime. Migration preserves user-edited and unknown assets and records
+legacy ownership without reading, writing, or deleting live host configuration.
+Use the explicit migration guidance in [installation](docs/installation.md);
+release installation, host cutover, and old-timer cleanup need separate
+authorization.
+
+## License
+
+[MIT](LICENSE) © 2026 Axat Bhardwaj.

package/bin/axstack.js

@@ -0,0 +1,396 @@
+#!/usr/bin/env bun
+// axstack — installation/setup CLI. Installs owned skill bundles and selected
+// role data, configures Claude settings, and checks host capabilities. Chat
+// CLI performs installation bookkeeping only (no runtime, scheduler, or
+// model calls).
+import { readFileSync } from 'node:fs';
+import { join, resolve } from '../src/posixpath.js';
+import {
+  checkInstructionBinding,
+  installBundle,
+  uninstallBundle,
+  validateBundle,
+} from '../src/installer.js';
+import { BUN_FLOOR, checkCapabilities, meetsFloor, runRealCheck } from '../src/capabilities.js';
+import { harnessLocations } from '../src/locations.js';
+
+// import.meta.dir is already a filesystem path (no URL conversion, so
+// spaces/percent/hash characters survive verbatim).
+const HERE = import.meta.dir;
+const PACKAGE_ROOT = resolve(HERE, '..');
+
+function homeDir() {
+  // Tilde expansion needs a known absolute home; with HOME missing, empty,
+  // or relative the destination is unknown, so refuse even with --yes.
+  const home = Bun.env.HOME;
+  if (!home || !home.startsWith('/')) {
+    throw new Error('HOME is missing, empty, or not absolute; pass explicit paths instead of ~');
+  }
+  return home;
+}
+
+function packageVersion() {
+  try {
+    return JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8')).version;
+  } catch {
+    return 'unknown';
+  }
+}
+
+const HELP = `axstack — Axstack setup CLI (installation bookkeeping only)
+
+Usage:
+  axstack install --preset <mixed|codex-only|claude-only> --bundle <dir> --skills-dir <dir> [--instructions <file>] [--claude-settings <file>|--no-claude-settings] [--harness <name>] [--force] [--yes]
+  axstack check [--bundle <dir>] [--instructions <file>] [--skills-dir <dir>|--harness <name>]
+  axstack uninstall --skills-dir <dir> [--instructions <file>] [--claude-settings <file>|--no-claude-settings] [--harness <name>] [--force] [--yes]
+  axstack --help | --version
+
+Commands:
+  install    Validate a skill bundle, then copy owned skills and selected role
+             data and record ownership hashes.
+  check      Probe Bun, Git, gh stack, and resolved Orca runtime/guide
+             capabilities. Probes do not prove model or execution compatibility.
+  uninstall  Remove only unchanged Axstack-owned assets. User edits survive.
+
+Flags:
+  --bundle <dir>      Bundle root holding skills/axstack-*/SKILL.md and
+                      profiles/presets/*.json role data. Defaults to the package root.
+  --preset <name>     Required routing preset: mixed, codex-only, or claude-only.
+                      Aliases: codex = codex-only; claude = claude-only.
+  --skills-dir <dir>  Explicit install target (required). Overrides --harness.
+  --instructions <file>
+                      Instruction file to receive the owned routing block.
+                      Harness defaults: ~/.claude/CLAUDE.md for Claude and
+                      $CODEX_HOME/AGENTS.md for Codex (default ~/.codex).
+  --claude-settings <file>
+                      Manage the Claude Code user settings file at this path.
+                      This forces testable availability without installing Claude.
+  --no-claude-settings
+                      Skip Claude Code user-settings management.
+  --harness <name>    Known harness (${harnessLocations().map((h) => h.harness).join(', ')}).
+                      Grok has no verified auto-discovery: --skills-dir is required.
+  --force             Overwrite/remove user-edited owned assets and take
+                      ownership of unknown files. Off by default.
+  --yes               Confirm writes inside your home directory. Temp dirs
+                      outside home never need this.
+
+Migration:
+  --profile is obsolete. Axstack installs the selected preset as
+  <skills-dir>/axstack/roles.json and never reads or writes Paseo config.
+
+Safety:
+  Bundles with symlinks, absolute paths or '..' escapes are rejected before
+  any write. Unknown pre-existing files are never silently overwritten.
+  Partial failures roll back files created in that run.
+`;
+
+function parseArgs(argv) {
+  const out = { command: null, flags: {} };
+  const rest = [...argv];
+  if (rest.length === 0 || rest[0] === '--help' || rest[0] === '-h') {
+    out.command = 'help';
+    return out;
+  }
+  if (rest[0] === '--version' || rest[0] === '-V') {
+    out.command = 'version';
+    return out;
+  }
+  out.command = rest.shift();
+  const wantsValue = new Set([
+    '--bundle', '--skills-dir', '--instructions', '--harness', '--preset', '--claude-settings',
+  ]);
+  while (rest.length > 0) {
+    const tok = rest.shift();
+    if (tok === '--profile') {
+      throw new Error(
+        '--profile is obsolete in the Orca-only installer; role data is installed as axstack/roles.json and legacy Paseo cleanup is separate',
+      );
+    }
+    if (wantsValue.has(tok)) {
+      const val = rest.shift();
+      if (val === undefined || val.startsWith('--')) {
+        throw new Error(`${tok} requires a value (got ${val ?? 'nothing'}); refusing`);
+      }
+      out.flags[tok.slice(2)] = val;
+    } else if (tok === '--force') out.flags.force = true;
+    else if (tok === '--yes') out.flags.yes = true;
+    else if (tok === '--no-claude-settings') out.flags['no-claude-settings'] = true;
+    else if (tok === '--help' || tok === '-h') out.command = 'help';
+    else throw new Error(`unknown argument: ${tok}`);
+  }
+  return out;
+}
+
+function defaultClaudeSettingsPath() {
+  if (Bun.env.CLAUDE_CONFIG_DIR) {
+    return join(resolve(Bun.env.CLAUDE_CONFIG_DIR), 'settings.json');
+  }
+  const home = Bun.env.HOME;
+  return home?.startsWith('/') ? join(home, '.claude', 'settings.json') : null;
+}
+
+function isInsideRawHome(path) {
+  const home = Bun.env.HOME;
+  if (!home?.startsWith('/') || !path) return false;
+  const absoluteHome = resolve(home);
+  const absolutePath = resolve(path);
+  return absolutePath === absoluteHome || absolutePath.startsWith(`${absoluteHome}/`);
+}
+
+function resolveClaudeOption(flags, command) {
+  if (flags['claude-settings'] && flags['no-claude-settings']) {
+    throw new Error('--claude-settings and --no-claude-settings cannot be used together');
+  }
+  if (flags['no-claude-settings']) {
+    return { available: false, settingsPath: null, skip: true, reason: 'disabled by --no-claude-settings' };
+  }
+  if (flags['claude-settings']) {
+    return { available: true, settingsPath: expandHome(flags['claude-settings']), explicit: true };
+  }
+
+  const settingsPath = defaultClaudeSettingsPath();
+  const available = Bun.which('claude') !== null;
+  if (command === 'install' && available && !flags.yes && isInsideRawHome(settingsPath)) {
+    return {
+      available: false,
+      settingsPath: null,
+      reason: 'default settings path is inside HOME; re-run with --yes',
+    };
+  }
+  return {
+    available,
+    settingsPath: available ? settingsPath : null,
+    reason: available ? undefined : 'Claude Code is not available',
+  };
+}
+
+function printClaudeSettings(report, { uninstall = false } = {}) {
+  if (!report) return;
+  if (report.status === 'skipped') {
+    console.log(`claude settings: skipped — ${report.reason}`);
+  } else if (!uninstall && report.status === 'set') {
+    console.log(`claude settings: set env.CLAUDE_CODE_SUBAGENT_MODEL=opus in ${report.path}`);
+  } else if (!uninstall && report.status === 'unchanged') {
+    console.log('claude settings: unchanged (owned)');
+  } else if (!uninstall && report.status === 'preserved') {
+    console.log(`claude settings: preserved existing value ${JSON.stringify(report.value)} (not owned)`);
+  } else if (uninstall && report.status === 'removed') {
+    console.log(`claude settings: removed env.CLAUDE_CODE_SUBAGENT_MODEL from ${report.path}`);
+  } else if (uninstall && report.status === 'retained') {
+    console.log('claude settings: unchanged (owned by another skills install)');
+  } else if (uninstall && report.status === 'preserved') {
+    console.log(`claude settings: preserved edited value ${JSON.stringify(report.value)} (ownership released)`);
+  } else if (uninstall && report.status === 'released') {
+    console.log('claude settings: ownership released (bound settings file missing)');
+  }
+}
+
+function expandHome(p) {
+  if (p === '~') return homeDir();
+  if (p.startsWith('~/')) return join(homeDir(), p.slice(2));
+  return p;
+}
+
+function resolveHarnessTarget(harness) {
+  const table = harnessLocations();
+  const entry = table.find((h) => h.harness === harness);
+  if (!entry) throw new Error(`unknown harness: ${harness} (known: ${table.map((h) => h.harness).join(', ')})`);
+  if (entry.discovery === 'unverified') {
+    throw new Error(
+      `harness '${harness}' has no verified auto-discovery; pass an explicit --skills-dir override`,
+    );
+  }
+  if (entry.harness === 'codex') {
+    // User skills live under $CODEX_HOME/skills; CODEX_HOME defaults to ~/.codex.
+    const home = Bun.env.CODEX_HOME ? expandHome(Bun.env.CODEX_HOME) : join(homeDir(), '.codex');
+    return join(home, 'skills');
+  }
+  return expandHome(entry.skillsDir);
+}
+
+function resolveHarnessInstructions(harness) {
+  if (harness === 'claude') return join(homeDir(), '.claude', 'CLAUDE.md');
+  if (harness === 'codex') {
+    const codexHome = Bun.env.CODEX_HOME
+      ? expandHome(Bun.env.CODEX_HOME)
+      : join(homeDir(), '.codex');
+    return join(codexHome, 'AGENTS.md');
+  }
+  return null;
+}
+
+function printCheckReport(report) {
+  console.log('Capability check:');
+  for (const c of report.checks) {
+    console.log(`  [${c.ok ? 'ok' : 'MISSING'}] ${c.label}: ${c.detail}`);
+  }
+  if (report.gaps.length > 0) {
+    console.log('Gaps detected:');
+    for (const g of report.gaps) console.log(`  - ${g}`);
+  } else {
+    console.log('No gaps detected.');
+  }
+  console.log('Probe limits:');
+  for (const line of report.limitations) console.log(`  - ${line}`);
+}
+
+function checkRuntimeFloor() {
+  if (!meetsFloor(Bun.version, BUN_FLOOR)) {
+    console.error(`axstack: requires Bun >= ${BUN_FLOOR} (running ${Bun.version})`);
+    process.exitCode = 1;
+    return false;
+  }
+  return true;
+}
+
+async function main() {
+  if (!checkRuntimeFloor()) return;
+  let parsed;
+  try {
+    parsed = parseArgs(Bun.argv.slice(2));
+  } catch (err) {
+    console.error(`axstack: ${err.message}`);
+    console.error(HELP);
+    process.exitCode = 1;
+    return;
+  }
+  const { command, flags } = parsed;
+
+  if (command === 'help') {
+    console.log(HELP);
+    return;
+  }
+  if (command === 'version') {
+    console.log(`axstack ${packageVersion()}`);
+    return;
+  }
+
+  try {
+    if (command === 'install') {
+      let skillsDir = flags['skills-dir'] ? expandHome(flags['skills-dir']) : null;
+      if (!skillsDir && flags.harness) skillsDir = resolveHarnessTarget(flags.harness);
+      const instructionsPath = flags.instructions
+        ? expandHome(flags.instructions)
+        : flags.harness
+          ? resolveHarnessInstructions(flags.harness)
+          : null;
+      const summary = await installBundle({
+        bundleDir: flags.bundle ? resolve(flags.bundle) : PACKAGE_ROOT,
+        skillsDir,
+        preset: flags.preset,
+        instructionsPath,
+        force: !!flags.force,
+        yes: !!flags.yes,
+        claude: resolveClaudeOption(flags, 'install'),
+        log: (m) => { if (m !== 'plan complete') console.log(m); },
+      });
+      const changed =
+        summary.added.length + summary.updated.length + summary.removed.length +
+        (['created', 'updated'].includes(summary.instructions?.status) ? 1 : 0);
+      if (changed === 0) {
+        console.log('Install complete: no changes (idempotent, everything unchanged).');
+      } else {
+        if (summary.added.length) console.log(`added: ${summary.added.join(', ')}`);
+        if (summary.updated.length) console.log(`updated: ${summary.updated.join(', ')}`);
+        if (summary.removed.length) console.log(`removed: ${summary.removed.join(', ')}`);
+        if (summary.unchanged.length) console.log(`unchanged: ${summary.unchanged.join(', ')}`);
+      }
+      if (summary.preserved.length) {
+        console.log(`preserved user edits (use --force to overwrite): ${summary.preserved.join(', ')}`);
+      }
+      if (summary.stale.length) console.log(`stale owned files left on disk: ${summary.stale.join(', ')}`);
+      if (summary.instructions) {
+        const i = summary.instructions;
+        if (i.status === 'conflict') {
+          console.log(`instruction conflict: ${i.path} preserved (${i.reason})`);
+          process.exitCode = 1;
+        } else {
+          console.log(`instruction ${i.status}: ${i.path}`);
+        }
+      }
+      if (summary.notes?.length) {
+        for (const note of summary.notes) console.log(`note: ${note}`);
+      }
+      if (summary.roles) {
+        const p = summary.roles;
+        console.log(
+          p.ready
+            ? `preset ${summary.preset}: ready`
+            : `preset ${summary.preset}: NOT ready — ${p.gaps.join('; ')}`,
+        );
+        if (!p.ready) process.exitCode = 1;
+      } else {
+        console.log('role data was not installed; readiness is unverified.');
+      }
+      printClaudeSettings(summary.claudeSettings);
+      return;
+    }
+    if (command === 'check') {
+      const report = await checkCapabilities(runRealCheck);
+      printCheckReport(report);
+      if (flags.bundle) {
+        const bundle = await validateBundle(resolve(flags.bundle));
+        const presetNames = Object.keys(bundle.presets);
+        console.log(
+          `bundle ok: ${bundle.files.length} skill files, ` +
+            (presetNames.length > 0 ? `role presets ${presetNames.join(', ')}` : 'no role presets'),
+        );
+      }
+      if (flags.instructions || flags.harness) {
+        let skillsDir = flags['skills-dir'] ? expandHome(flags['skills-dir']) : null;
+        if (!skillsDir && flags.harness) skillsDir = resolveHarnessTarget(flags.harness);
+        const instructionsPath = flags.instructions
+          ? expandHome(flags.instructions)
+          : resolveHarnessInstructions(flags.harness);
+        const instruction = await checkInstructionBinding({ skillsDir, instructionsPath });
+        console.log(
+          `instruction ${instruction.status}: ${instruction.path}` +
+            (instruction.reason ? ` (${instruction.reason})` : ''),
+        );
+        if (instruction.status !== 'owned') process.exitCode = 1;
+      }
+      if (report.gaps.length > 0) process.exitCode = 1;
+      return;
+    }
+    if (command === 'uninstall') {
+      let skillsDir = flags['skills-dir'] ? expandHome(flags['skills-dir']) : null;
+      if (!skillsDir && flags.harness) skillsDir = resolveHarnessTarget(flags.harness);
+      const instructionsPath = flags.instructions
+        ? expandHome(flags.instructions)
+        : flags.harness
+          ? resolveHarnessInstructions(flags.harness)
+          : null;
+      const summary = await uninstallBundle({
+        skillsDir,
+        instructionsPath,
+        force: !!flags.force,
+        yes: !!flags.yes,
+        claude: resolveClaudeOption(flags, 'uninstall'),
+        log: (m) => console.log(m),
+      });
+      if (summary.note) console.log(summary.note);
+      if (summary.removed.length) console.log(`removed: ${summary.removed.join(', ')}`);
+      if (summary.preserved.length) {
+        console.log(`preserved user edits (use --force to remove): ${summary.preserved.join(', ')}`);
+      }
+      if (summary.instructions) {
+        const i = summary.instructions;
+        if (i.status === 'conflict' || i.status === 'preserved') {
+          console.log(`instruction ${i.status}: ${i.path} preserved (${i.reason})`);
+        } else {
+          console.log(`instruction ${i.status}: ${i.path}`);
+        }
+      }
+      printClaudeSettings(summary.claudeSettings, { uninstall: true });
+      return;
+    }
+    console.error(`axstack: unknown command: ${command}`);
+    console.error(HELP);
+    process.exitCode = 1;
+  } catch (err) {
+    console.error(`axstack: ${err.message}`);
+    process.exitCode = 1;
+  }
+}
+
+await main();