axstack 0.9.0

package/docs/installation.md

@@ -0,0 +1,239 @@
+# Installation
+
+Axstack's Bun CLI installs owned chat skills plus one selected role snapshot and
+checks host capabilities. Orca is the only supported active runtime. The CLI
+does not dispatch agents, edit Orca settings, run a scheduler, or maintain a
+workflow database.
+
+Requirements: Bun >=1.3.14, Git, `gh`, the `gh stack` extension, and a running
+Orca whose version-matched `orchestration` and `orca-cli` guides are available.
+There are no runtime dependencies. Filesystem access uses Bun-backed `node:fs`
+and `node:fs/promises`; no other Node runtime contract is introduced.
+
+## Commands
+
+### Install
+
+```text
+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]
+```
+
+- `--preset` is required. `codex` and `claude` are aliases for the canonical
+  `codex-only` and `claude-only` names. Axstack never infers a preset from the
+  harness, available tools, provider credentials, subscriptions, or quota.
+- `--bundle` defaults to the package root and contains `skills/` plus
+  `profiles/presets/*.json`.
+- `--skills-dir` is required unless a verified harness default resolves it.
+- `--instructions` selects the instruction file that receives Axstack's owned
+  marker block. `--harness claude` defaults to `~/.claude/CLAUDE.md`;
+  `--harness codex` defaults to `$CODEX_HOME/AGENTS.md` or `~/.codex/AGENTS.md`.
+- `--harness` may resolve the documented `claude`, `codex`, or `opencode`
+  skill directory. Grok remains explicit-path only.
+- `--claude-settings` and `--no-claude-settings` control the existing Claude
+  Code subagent-default transaction. They do not configure Orca roles.
+- `--force` may replace an edited owned asset; it never adopts or removes
+  unrelated state.
+- `--yes` confirms writes under the user's home directory. Tests use temporary
+  homes and fixtures only.
+
+## Role presets
+
+The selected bundle input is one of:
+
+```text
+profiles/presets/mixed.json
+profiles/presets/codex-only.json
+profiles/presets/claude-only.json
+```
+
+Each has exactly `{ "version": 1, "roles": [...] }` with the same 21 stable
+role IDs. Installation writes `<skills-dir>/axstack/roles.json` as
+`{ "version": 1, "preset": "<selected preset>", "roles": [...] }` and records
+its ownership hash like every other installed skill asset. There is no second
+role store and no Orca configuration merge.
+
+### Check
+
+```text
+axstack check [--bundle <dir>] [--instructions <file>] [--skills-dir <dir>|--harness <name>]
+```
+
+The check separates Bun/Git/`gh stack` availability, resolved Orca executable,
+runtime readiness, required runtime-owned guide discovery, and bundle validity.
+With an instruction target, it separately reports whether the marker block is
+owned, missing, unowned, edited, or bound to a different path.
+It must honor Orca's executable-resolution rules, including the Linux screen
+reader name collision, and must not switch binaries after a failed resolution.
+
+A successful check is not provider/model availability, effective permission,
+skill reload, task execution, mobile delivery, or end-to-end compatibility
+proof. Those require their own runtime receipts.
+
+### Uninstall
+
+```text
+axstack uninstall --skills-dir <dir> [--instructions <file>] [--claude-settings <file>|--no-claude-settings] [--harness <name>] [--force] [--yes]
+```
+
+Uninstall removes only unchanged Axstack-owned files whose current bytes match
+the manifest. Edited, custom, unknown, and unrelated files survive. Directories
+are pruned only when empty, and the target root is never removed.
+
+## Owned instruction block
+
+The deterministic `<!-- axstack:begin v1 -->` / `<!-- axstack:end -->` block
+contains the target-derived Axstack entry path and model-free routing prose. It
+also routes subagents, delegated workers, reviewers, and cross-harness work
+through Orca's `orca` CLI and forbids harness-native subagent delegation.
+
+Create, update, repeated install, check, and uninstall preserve every byte and
+the file mode outside the markers. The manifest binds the canonical instruction
+path and exact block hash while retaining older file/profile hash semantics.
+Uninstall removes only an unchanged owned block plus the recorded separator;
+the instruction file itself remains. Edited or unowned blocks, malformed or
+duplicate markers, symlinks, concurrent edits, and legacy Haoshoku routing text
+are preserved or refused with an explicit report. Combined failures roll back
+skills, instruction bytes and modes, Claude settings, and manifest state; any
+failed recovery is reported as incomplete.
+
+`axstack install` exits with status 1 when the selected instruction block is in
+conflict and was preserved, so scripts can detect that routing was not
+installed. A clean or idempotent install exits 0; preserved edits to ordinary
+owned skill files keep their existing non-failing install semantics.
+
+## Safety and ownership behavior
+
+The complete bundle is validated before writes:
+
+- every skill directory contains a real `SKILL.md`;
+- bundle and destination symlink/escape checks pass;
+- each preset is a real JSON file with version 1, a non-empty `roles` array,
+  the filename's selected identity supplied by the caller, and the same role-ID
+  set as its peers;
+- every role has valid preserved fields, while the mixed checker and the
+  unavailable adviser in each single-provider preset explicitly permit
+  `model: null`;
+- obsolete runtime configuration flags fail before mutation with migration
+  guidance.
+
+Reinstalls are idempotent. Unknown files are never silently overwritten or
+adopted. Edited owned files keep their previous ownership baseline unless
+`--force` explicitly replaces them. Owned files the bundle no longer ships
+are stale: a pristine stale copy (on-disk bytes still match the manifest
+hash) is deleted, dropped from the written manifest, and reported as
+`removed`; an edited or already-missing stale copy is left alone, keeps its
+manifest hash, and stays reported as `stale`. Only manifest-owned paths are
+ever deleted, through the same ownership-hash guard uninstall uses. The stale
+plan is validated read-only before any write, and each deletion re-checks
+its target through that guard immediately before removal, so a copy edited
+during the run is preserved rather than deleted. Partial failures restore overwritten files, restore removed stale
+files with their prior bytes and mode,
+remove files created by that run, restore Claude settings/sidecar state, and
+leave the prior manifest intact. An incomplete rollback reports exact manual
+recovery needs.
+
+Manifest validation covers version, owned file shape, safe relative paths, and
+symlink rejection. The role snapshot is ordinary owned data. Invalid or edited
+destination roles are preserved and reported rather than treated as permission
+to rewrite them.
+
+## Role behavior after installation
+
+The runtime reads `roles.json` relative to the actually loaded `axstack` skill.
+A new run records the selected preset plus all 21 role rows. An active run keeps
+that snapshot after a later preset install unless the user explicitly changes
+it and accepts the resulting evidence invalidation.
+
+The mixed checker has `model: null`; checker dispatch is held and never inherits
+a provider default. The single-provider presets configure the checker. Their
+unavailable adviser remains an explicit same-provider `model: null` role, which
+does not make installation unready; Align and Spec still hold until both Astra
+and Fable can return independent receipts. The current chat drives on whatever
+model runs it; no preset carries a driver role. Every other missing, invalid, unsupported, or unavailable role value holds only
+the affected work. There is no model substitution, subscription inference, or
+quota routing.
+
+`modeId` and similar permission fields remain conservative declared intent.
+They do not prove the effective Orca launcher mode, sandboxing, or permission
+parity. Requested provider/model/effort, input acceptance, effective session
+settings, and completed behavior are separate evidence classes.
+
+## Claude Code subagent default
+
+The preserved Claude-settings feature manages only
+`env.CLAUDE_CODE_SUBAGENT_MODEL = "opus"` when its existing ownership and
+availability conditions allow. It does not change the main conversation,
+select an Axstack role, force built-in agents, or configure Orca.
+
+Axstack merges that one key and preserves all unrelated settings and environment
+values. A pre-existing value is preserved and never adopted. Missing Claude,
+`--no-claude-settings`, or an unconfirmed home write produces a documented skip.
+New settings and ownership files use mode `0600`; existing modes survive.
+Malformed JSON, symlinks, or a conflicting saved path fail before mutation.
+
+Ownership remains per key and shared across skill roots through the existing
+`.axstack-settings.json` sidecar. A later installation can join ownership
+without rewriting the value. Uninstall drops one root and removes the key only
+when the last owner leaves and the value remains unchanged. A user edit always
+survives.
+
+## Harness skill locations
+
+| Harness | Default directory | Status |
+| --- | --- | --- |
+| Claude | `~/.claude/skills` | documented upstream |
+| Codex | `$CODEX_HOME/skills` (default `~/.codex/skills`) | documented upstream |
+| OpenCode | `~/.config/opencode/skills` | documented upstream |
+| Grok | explicit `--skills-dir` only | auto-discovery unverified |
+
+Prefer explicit paths and current upstream CLI guidance. Installing files does
+not prove that a running harness reloaded them.
+
+## Runtime guide discovery
+
+The installed Axstack bundle does not own or copy Orca's guides. At an action
+boundary, the skill resolves one Orca executable and loads that binary's
+version-matched `orchestration` and `orca-cli` guides. Automation guidance is
+loaded only for the watch branch. Missing discovery is a setup gap, not a reason
+to fall back or invent commands.
+
+Native watch activation is currently held: provider selection exists, but
+model, effort, permission, and bounded-expiry support do not preserve the
+accepted contract. Installation creates no production schedule and adds no
+custom scheduler.
+
+## Historical migration
+
+Older releases installed Paseo profiles and used Paseo for execution. Those
+profile records are inert historical manifest provenance after upgrade: they
+do not trigger configuration reads, writes, path-binding refusal, readiness
+checks, uninstall mutation, runtime fallback, or timer cleanup. Preserve them
+for audit and report the explicit migration path.
+
+The next ordinary upgrade without `--force` removes pristine retired
+`axstack-handoff` and `axstack-docs` copies directly: they are deleted,
+dropped from the manifest, and reported as removed, while retaining edited
+or already-missing retired copies of axstack-handoff and axstack-docs as
+recorded, preserved stale entries. The
+retired `axstack-driver` row leaves `roles.json` on the next install because
+that file is rewritten as one owned snapshot. A --force uninstall/install
+cycle remains only for discarding edited copies you have decided to abandon;
+edited, custom, and unknown assets otherwise survive. `axstack-explain`
+supersedes the old docs route. Full ownership transfer uses Orca's runtime-owned
+handoff guidance and still requires explicit recipient acceptance.
+
+Do not mutate live historical configuration during development or migration
+tests. Host cutover, old-timer cleanup, release installation, and global cleanup
+need separate authority and verified backups.
+
+## Examples
+
+```sh
+axstack install --preset mixed --bundle ./bundle --skills-dir /tmp/ax-skills --instructions /tmp/AGENTS.md
+axstack install --preset mixed --bundle ./bundle --skills-dir /tmp/ax-skills --instructions /tmp/AGENTS.md
+axstack check --bundle ./bundle --skills-dir /tmp/ax-skills --instructions /tmp/AGENTS.md
+axstack uninstall --skills-dir /tmp/ax-skills --instructions /tmp/AGENTS.md
+```
+
+The second install should report no changes. These scratch examples do not
+activate Orca sessions or schedules.

package/docs/workflows.md

@@ -0,0 +1,220 @@
+# Axstack workflows
+
+Chat drives execution. Orca is the only supported active runtime and owns
+worktrees, sessions, supervised dispatch, messaging, settlement, and handoff.
+Axstack owns workflow policy, role data, evidence, and the private derived run
+record. It adds no daemon, scheduler, runtime database, or escalation engine.
+
+The bundled skills are self-contained. Retiring another skill does not claim
+Axstack implements that skill's specialist capability.
+
+## Routing and scope identity
+
+`axstack` classifies the request and loads only the applicable phase plus shared
+references for routing, lifecycle, Orca runtime boundaries, role/model/risk
+contracts, the run record, and PR shape.
+
+Direct routes need no spec ceremony:
+
+- `axstack-research` answers one bounded source-backed question.
+- `axstack-explain` separates implemented, intended, tested, live, and unknown
+  behavior; complex visuals receive exact-artifact QA where applicable.
+- `axstack-improve` returns a small ranked set of evidenced improvement
+  candidates without editing code.
+- `axstack-debug` builds a red loop, diagnoses to root cause, escalates hard
+  bugs through adviser-directed investigator fan-out, and hands off a
+  classified repair without landing a change.
+- Peer review uses the linked issue, PR description, and repository rules as
+  untrusted intent evidence.
+- Existing-PR maintenance uses one accepted maintenance snapshot.
+- Ordinary resume reconciles existing ownership and launches no handoff.
+
+Small, clear, bounded one-PR work uses its request or selected issue plus
+explicit acceptance checks and exclusions as a snapshotted small-change intent.
+Substantial work requires an approved spec and matching ticket map, including
+multi-PR or stacked work. Unclear work is clarified, then classified. A deeper phase checks
+the same identity before action; missing preparation names the gap and holds
+only affected work.
+
+## Role presets
+
+Installation requires one explicit canonical preset. The three bundle files
+under `profiles/presets/` each contain exactly
+`{ "version": 1, "roles": [...] }` and the same 21 stable IDs.
+
+The current chat drives on whatever model runs it; no preset carries a driver
+role.
+
+| Preset | Author | Ordered peer reviewers | Astra / Fable advisers | Auditor |
+| --- | --- | --- | --- | --- |
+| `mixed` | Sol medium | Sol medium; Opus medium | Astra high / Fable high | Luna max |
+| `codex-only` | Sol medium | Sol medium; Terra xhigh | Astra high / unavailable | Luna max |
+| `claude-only` | Opus medium | Opus medium; Sonnet xhigh | unavailable / Fable high | Sonnet xhigh |
+
+The installed `<skills-dir>/axstack/roles.json` adds the selected preset name:
+`{ "version": 1, "preset": "<name>", "roles": [...] }`. The runtime reads it
+relative to the actually loaded `axstack` skill and records the whole table for
+a new run. Active runs retain their snapshot after later installation changes.
+
+Peer roles keep the stable IDs `axstack-reviewer-primary` and
+`axstack-reviewer-secondary`; their provider/model mappings come only from the
+selected preset.
+
+The unavailable adviser in each single-provider preset stays explicitly
+`model: null` within that provider's bounds. Installer readiness accepts that
+intentional absence, but Align and Spec hold because both independent receipts
+are required. The mixed checker also stays explicitly `model: null`; checker work holds instead of
+launching a provider default. Missing or unavailable roles hold only affected
+work. Model, effort, and permission values express requested intent until real
+Orca receipts establish the effective session. Stored `modeId` is not permission
+parity or a sandbox. No route is inferred from subscription, quota, harness,
+provider defaults, or installed tools, and no model is substituted silently.
+
+## Orca runtime boundary
+
+Immediately before dispatch, delivery processing, settlement, recovery, or
+handoff, load the shared `skills/axstack/references/orca-runtime.md`. It resolves
+one Orca executable, loads that binary's version-matched `orchestration` and
+`orca-cli` guides, and follows their advertised schemas. Axstack does not vendor
+the guides or restate a competing command protocol.
+
+Supervised work uses native Run, Task, and Dispatch identity. Preserve actual
+terminal, agent, worktree, requested/effective role, and revision receipts.
+`input_accepted` proves only terminal input; `turn_started` and session
+inspection are separate. Trust, permission, hook-review, authentication, and
+model prompts are visible holds. Never answer trust or permission prompts for a
+worker. Reconcile the existing attempt through the runtime guide before retry,
+so one candidate never gains a duplicate writer.
+
+Process each whole delivery before acknowledgment. A `worker_done` belongs only
+to its expected active Task and Dispatch, and its revision evidence still needs
+verification. `consumer_fenced` stops consumption under the stale identity;
+never forge, borrow, or bypass a coordinator identity. Runtime settlement owns
+reuse, retention, and release. A `user_takeover` terminal remains retained and
+is not reused or closed as cleanup.
+
+Ordinary restart reconciles the same owner, author, Task, Dispatch, worktree,
+revisions, and pending receipts. Idle, silence, contact loss, or missing status
+never proves exit. Authorized fixes return to the same original author when its
+session and evidence remain valid.
+
+## Phases
+
+- `axstack-align` maps facts and dependencies, asks prioritized questions, and
+  consults Astra and Fable independently with the same bounded evidence and
+  question. It synthesizes disagreements and reuses unchanged receipts.
+- `axstack-spec` writes observable acceptance, exclusions, decisions, and one
+  user-approved revision baseline.
+- `axstack-tickets` maps user-visible capabilities to dependency-aware internal
+  tasks. Linear is the default selected store with access preflight; repository
+  Markdown is explicit fallback. Only the driver mutates lifecycle state.
+- `axstack-implement` uses strict behavioral RED, GREEN, then refactor. The
+  narrow accepted structure-preserving route uses old-green and the same check
+  new-green. One author writes and returns a local receipt without pushing. The
+  owner reconciles it, publishes the unchanged commits through `gh stack`, and
+  confirms the remote SHA before review. Local green and CI green remain
+  separate evidence.
+- `axstack-review` gives peer PRs two isolated same-brief reviewers and authored
+  PRs one eligible cross-family/preset-mapped reviewer. All cover security,
+  correctness, integration, requirements, design, and simplicity. Report-only
+  never publishes; authorized submission binds the exact commit.
+- `axstack-watch` adopts an existing PR under observation-only, peer, or
+  authorized-maintenance scope. A changed head or comment is an event, not
+  repair authority. Repairs return to the original author only for a
+  run-launched session and receive refreshed authored review before scoped
+  `gh stack` publication. `gh stack` publication does not apply to automation
+  repairs: the automation session (or a dispatched `axstack-author`) repairs in
+  a per-PR child worktree, the local SHA is reviewed and gated, and the repair
+  lands by fast-forward `git push` after `proceed`.
+- `axstack-audit` separates execution outcome, procedure, and measurement
+  coverage with evidenced denominators; it proposes but never self-edits.
+
+One Orca execution host owns a run, one persistent owner owns each PR, and one
+writer owns each candidate. Fanout has no fixed PR count; it follows real
+dependencies, writer isolation, host capacity, and spending limits. Each PR has
+one theme and a measured size under the shared
+[PR-shape policy](../skills/axstack/references/pr-shape.md). The human merges
+by default; review approval never grants merge authority.
+For the rationale band, the autonomous driver records a cohesion rationale. The exception band
+requires a reasonable split attempt and full exception record. These are
+autonomous driver choices; size alone never requires user approval.
+
+## Explicit handoff
+
+Only an explicit user request transfers ownership. Record the intended
+recipient, exact scope, revisions, authority, and pending request, then follow
+the runtime-owned `orca-cli` handoff guide. Input acceptance and turn start do
+not transfer ownership. The recipient must explicitly accept the exact handoff;
+only then does the prior owner stop. Missing capability or ambiguous acceptance
+keeps the current owner and a resumable record.
+
+## Notifications and relay
+
+Serious security, downtime, data-loss, and major-design risks are raised in a
+prompt immediately and hold dependent dangerous work. This is not a runtime
+gate. An applicable `Notification policy` may use `axstack-relay`; otherwise the
+current Orca conversation is the fallback. The relay delivers one-way through
+native `hermes send`: it checks CLI lookup and the configured target, binds the
+recipient, deduplicates on the run record, records the returned `message_id`,
+and treats Telegram replies as neither receipts nor authority. Delivery failure
+never clears the underlying hold.
+
+Healthy watch observations remain quiet. The optional `axstack-monitor` is
+read-only and never sends; `axstack-watchdog` never mutates GitHub and performs
+exactly one kind of send, a gate-authorized automation-health escalation
+recorded in `watchdog.json`.
+
+## Native watch automations
+
+The accepted monitoring contract is a five-minute driver automation, an hourly
+watchdog, quiet healthy snapshots, deduplicated actionable events, verified
+handshakes, one owner, and one shared default 24-hour deadline.
+
+The user lifted the native-watch hold by user decision on 2026-09-16. The driver
+automation is a mutating owner for the PRs it handles; the watchdog keeps the
+independent read-only contract. The driver is the automation session itself,
+with no `axstack-monitor` or `axstack-owner` role row. Native Orca automations still select only a
+provider, so the driver records its model identity every tick and the watchdog
+treats a mismatch as a safety hold. Axstack adds no custom scheduler, polling
+loop, or historical runtime fallback.
+
+## Automations
+
+Two native Orca automations run the installed skills without a human in the
+loop: a driver every five minutes that discovers own and peer PRs, repairs own
+PRs in the mutation allowlist, and reviews peer PRs; and a read-only
+watchdog every hour that reports automation health. After every
+mode-required reviewer settles, the `axstack-auditor` gate returns
+exactly one token, `escalate` or `proceed`.
+`escalate` records and notifies a hold and publishes nothing.
+Only `proceed` plus no unresolved validated blocking finding permits publication
+(a fast-forward push or one `COMMENT` review). The approved contract is
+`docs/specs/orca-automations.md`; the skill-facing restatement an automation
+session loads is `skills/axstack/references/automations.md`.
+
+## Run record and evidence
+
+Substantive delegated or resumable work uses one compact `progress.md` rooted at
+`git rev-parse --path-format=absolute --git-common-dir`. It is shared across
+worktrees but never tracked. The driver alone writes it; actual Orca state, Git
+revisions, forge state, and approved scope remain authoritative.
+
+Structural checks verify packaging and declared policy, not agent behavior.
+Predeclared scenario evaluation is qualitative behavior evidence, not deterministic proof. Runtime
+compatibility requires actual guide discovery, role/session evidence, worktree
+and Dispatch receipts, completion delivery, and cleanup as applicable. Mobile
+completion and reply behavior remain unverified.
+
+## Historical migration
+
+Older releases used Paseo for orchestration. Legacy profile ownership remains
+inert provenance and may be cleaned only through the explicit migration path;
+it never authorizes active configuration reads, writes, timer changes, or
+fallback. Release, installation, cutover, mobile pairing, and old-timer cleanup
+require separate authority.
+
+## Runtime
+
+Bun >=1.3.14, with no runtime dependencies. Workflow checks use
+`bun test tests/workflows/`; the only approved Node built-ins are Bun-backed
+`node:fs` and `node:fs/promises`.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "axstack",
+  "version": "0.9.0",
+  "description": "Axstack installer and setup CLI: installs owned chat skills and role data, configures supported harness settings, and checks Orca capabilities.",
+  "keywords": [
+    "claude-code",
+    "codex",
+    "orca",
+    "agents",
+    "skills",
+    "orchestration"
+  ],
+  "homepage": "https://github.com/axatbhardwaj/axstack#readme",
+  "bugs": "https://github.com/axatbhardwaj/axstack/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/axatbhardwaj/axstack.git"
+  },
+  "author": "Axat Bhardwaj",
+  "type": "module",
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "bin": {
+    "axstack": "bin/axstack.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "skills/",
+    "profiles/",
+    "docs/installation.md",
+    "docs/workflows.md"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "test:all": "bun test"
+  },
+  "license": "MIT"
+}