axstack 0.9.0

package/skills/axstack-tickets/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: axstack-tickets
+description: When an approved capability needs executable tasks, use axstack-tickets to map work and track lifecycle state.
+---
+
+# Tickets
+
+Produce an executable capability map tied to the exact approved spec revision.
+Keep user-visible capabilities in the selected store, keep implementation detail
+in the repository, reconcile lifecycle state, and stop before implementation.
+
+Before mapping, load [Standing contracts](../axstack/references/contracts.md).
+Follow its required edge to [Shared lifecycle](../axstack/references/lifecycle.md),
+including the lifecycle audit hook. Read the
+[PR-shape policy](../axstack/references/pr-shape.md) before sizing tasks. Read the
+[Orca runtime boundary](../axstack/references/orca-runtime.md) immediately before
+an actual checker dispatch, not for ordinary mapping or state reconciliation.
+
+## Procedure
+
+1. **Pin scope and storage.** Confirm the approved spec identity before mapping.
+   Hold on unapproved or materially changed scope; a still-valid approval is
+   never repeated. Use the explicitly selected Markdown or Linear store. Record
+   the exact approved spec revision and selected store.
+
+2. **Preflight the selected store.** Markdown mode works independently. In
+   Linear mode, check the actual session's required MCP tools and document
+   access. Missing access is an actionable setup gap: preserve the selected
+   store, record the gap, and stop affected work. Proceed only with verified
+   access; a recorded gap never switches stores.
+
+3. **Map capabilities to execution.** In Linear, issues represent user-visible
+   capabilities; one capability may span several tasks and PRs. Keep detailed
+   execution breakdowns in the repository. For every capability, derive
+   acceptance checks from the pinned spec and identify internal tasks,
+   dependencies, PR ownership, and worktrees. For each task the driver records
+   one theme and a coarse size estimate from the ownership, interface, and
+   dependency map. A task estimated in the exception band is assessed for a
+   split at mapping time and split where a green, atomic, reviewable split
+   exists. If the driver judges it inseparable, record the coarse planning
+   rationale with the task; actual measurement and exception evidence follow in
+   the implement receipt. Mapping time requires no actual SHAs or line counts.
+   Every capability ends with the fields below and an explicit dependency list.
+   These routine mapping and split choices are autonomous driver decisions
+   within the approved spec; size alone never requires user approval.
+
+   The driver performs every Linear mutation. Other roles return proposed
+   changes and evidence to the driver.
+
+## Template: capability to task map
+
+```text
+Spec: <approved revision>
+Capability: <Markdown ref or Linear issue URL> <title>
+Internal task: <task> -> <PR owner> -> <worktree>
+Theme: <one behavior or component>
+Size est: <coarse band estimate>
+Acceptance: <checks from approved spec rev>
+Depends: <task IDs or none>
+```
+
+4. **Reconcile lifecycle state.** Compare each run capability with its required
+   PR merge evidence and acceptance outputs. A reviewed but unmerged capability
+   stays **In Review**; mark Done only after all required PRs merge and the
+   capability's acceptance checks pass. Resolve each observed mismatch with
+   either a verified driver-owned update or a drift report.
+
+   The checker reports run-scoped discrepancies with evidence and never mutates
+   Linear. The driver independently verifies that evidence before applying an
+   update. Spec or acceptance changes and conflicting state are decisions, not
+   routine sync repairs. With no configured `axstack-checker` profile, hold
+   checker dispatch; the driver checks directly or records the gap. Never launch
+   a provider default.
+
+### Template: drift report
+
+```text
+Capability: <issue>
+Observed: <Linear state> vs <PR merge SHAs/URLs + acceptance outputs>
+Recommendation: <move to In Review | other> (driver verifies first)
+```
+
+5. **Return the mapping.** Report the pinned spec revision, selected store, map
+   references, mutations performed by the driver, recorded gaps, and unresolved
+   decisions. Stop with a map ready for lifecycle continuation; implementation
+   has not started.

package/skills/axstack-watch/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: axstack-watch
+description: When babysitting an existing PR, use axstack-watch to monitor or maintain it within bounded authority.
+---
+
+# Watch
+
+Leave each adopted PR with one accountable owner, current readiness evidence,
+and a bounded watch that ends cleanly or preserves enough state to resume.
+
+Before acting, load [Standing contracts](../axstack/references/contracts.md).
+Its required edge loads [Shared lifecycle](../axstack/references/lifecycle.md),
+including the end-of-run audit hook. Reach other references only at the steps
+that name them.
+
+Preserve any explicitly named PR, repository, or peer scope. For broad
+discovery of the user's own PRs (such as “my” or “our” PRs), run
+`gh api user --jq .login` on the execution host, then select open PRs authored
+by that login in the named or current repository. Never hardcode or guess the
+username; a missing or failed authenticated-login lookup is a concrete blocker.
+The authenticated human login selects PRs. Runtime session IDs coordinate work
+only and establish neither human identity nor write, reply, or merge authority.
+When the session is the Orca driver automation, also load
+[Automation sessions](../axstack/references/automations.md): it is the owner
+for every PR it handles, and its gate and allowlist bound every mutation.
+
+## 1. Adopt and reconcile
+
+Start from actual state. Reconcile the PR's remote head and base, ownership,
+existing Orca Tasks, Dispatches, sessions, private run record, and watch registrations. Reuse the
+live owner and watch; uncertain state holds new registrations until resolved.
+
+For an existing own PR, read the
+[proportional scope identities](../axstack/references/routing.md#proportional-scope-identity),
+verify writable ownership and user maintenance authority, then snapshot the
+accepted maintenance intent once: authorized scope, actual head and base,
+current owner, actual author provenance, and watch state. Check authoring
+session evidence; the orchestrator identity is not author evidence, and never
+assume an author for an imported own PR. It needs no new spec, ticket, or repeated
+approval. Monitoring-only adoption grants no repair or reply authority.
+
+Adoption is settled when the record names one persistent owner, one watch, the
+exact PR revision and base, and the applicable authority snapshot. If write
+authority is unverified, record the hold and continue read-only.
+
+## 2. Fix the operating mode
+
+Choose one mode from the user's authority and record it before dispatch:
+
+- **Observation-only:** reconcile and report CI, reviews, and PR state. It
+  dispatches no author and sends no reply. This restriction dominates every
+  repair path, including obvious fixes after changed heads or feedback.
+- **Peer:** observe and report a colleague's PR. Peer mode never repairs.
+- **Authorized maintenance:** repair an adopted own PR only within the accepted
+  maintenance snapshot and publication authority.
+
+Every later wake must be classifiable from this recorded mode without inferring
+new authority.
+
+## 3. Start the bounded watch
+
+Read-only checks and updates to the already-owned local record need no runtime
+load. When the watch needs a new owner or automated observation, first read
+[Watch runtime](references/watch-runtime.md) and then
+[Orca runtime](../axstack/references/orca-runtime.md). Reconcile before creating
+anything. The user lifted the native-watch hold by user decision: the 5 min driver
+automation is a mutating owner for the PRs it handles and the hourly watchdog
+stays independent and read-only. The driver is the automation session itself,
+with no `axstack-monitor` or `axstack-owner` role row; `axstack-monitor` stays
+an optional read-only observer that never sends. One read-only PR observation
+needs neither.
+
+For standalone adoption, materialize `axstack-owner` only when no live owner
+exists. Once it exists, the current chat is not a competing coordinator. Only
+the owner launches the writer, reviewers, monitor, and watchdog. Workers create
+no children or recursive teams, and the adoption watcher is never the writer.
+
+A live watch has verified role and timer receipts, handshakes, watched scope,
+wake ownership, and a common expiry. A missing runtime capability is a setup gap,
+not a reason to invent a call or create a duplicate registration. Wait through
+native wake-ups; no model remains active between events.
+
+## 4. Route each wake
+
+Re-read the remote head and base, then reconcile the event against acknowledged
+IDs and the recorded mode. A changed head, CI result, or review comment is an
+event, not repair authority. Stale or ambiguous observations authorize nothing.
+
+Observation-only and peer wakes produce a read-only report and stop. For an
+authorized maintenance wake that may require a repair or public reply, read and
+follow [Repair and publication](references/repair-publication.md). An
+automation session repairs in a per-PR child worktree created through
+`orca-cli`; its driver worktree never checks out a PR branch.
+
+### Feedback routing
+
+New work routes only under its confirmed scope identity: an approved spec and
+matching ticket map for substantial work, or a snapshotted **small-change
+intent** for small work. An adopted own PR instead uses its accepted maintenance
+snapshot. Missing, stale, or materially changed identity holds repair routing
+while monitoring continues. Accepted fixes return to the same original author
+session only when the run itself launched that session and evidence allows,
+then receive refreshed review under the authored mode rule before publication.
+For an adopted own PR under the automation, the original authoring session is
+not a run-launched session: the repair author is the automation session
+(Claude/Opus) or a dispatched `axstack-author` (Sol), and the authored-review
+pairing follows the recorded actual provenance of that repair, not the PR's
+historical author. Unknown, mixed, or unsupported author provenance
+that cannot establish the eligible configured reviewer is an exact gap to
+report to the user, not permission to invent a pairing or model fallback.
+
+A handled wake has an acknowledged event ID, an observation or action bound to
+the current revision, and a recorded hold or next owner where work remains.
+
+When a new actionable event is eligible under a recorded `Notification policy`,
+the owner may use the optional [axstack-relay](../axstack-relay/SKILL.md).
+The monitor never sends, and `axstack-watchdog` never mutates GitHub and
+performs exactly one kind of send, a gate-authorized automation-health
+escalation recorded in `watchdog.json`; absent policy or failed relay uses the
+current Orca conversation and leaves every existing hold open.
+
+## 5. State readiness precisely
+
+The owner checks current required checks, all feedback, approvals, mergeability,
+and exact-revision receipts before any merge-ready statement. API errors leave
+readiness `UNKNOWN`; review approval alone is not merge-ready. Merge-ready is an
+observed state distinct from merged, and the human merges by default.
+
+## 6. End and preserve continuity
+
+End early when all required PRs merge, or at cancel or the shared default 24h
+deadline. In every case, stop and verify all owned registrations. The deadline
+also stops timers for open PRs; never silently renew them.
+
+At every end condition, leave the compact state below in the private run record
+and report it in the current chat, even when work remains. Expiry grants neither
+silent renewal nor ownership-transfer authority. Under an automation, expiry
+marks the PR `expired` in the record and sidecar; an `expired` PR is never
+silently re-adopted and is skipped until the user re-arms it.
+
+Transfer ownership through the runtime-owned Orca handoff route only when the
+user explicitly requests it. Before transfer, follow the lifecycle-owned
+preflight for native capability availability, the configured role, and explicit
+recipient acceptance. A failed or incomplete preflight preserves the current
+owner and reports the gap; never invent a native command or infer acceptance.
+
+```text
+Record: <progress.md path>
+PR: <URL> rev <sha> base <sha>
+Owner: <profile + session> Worktree: <path>
+Scope: <approved rev, small-change intent, or maintenance snapshot>
+Capability: <issue + lifecycle state>
+CI/review: <current states + evidence refs>
+Watch: <automation ids or stopped registration receipts + expiry>
+Remaining: <next actions + owner>
+Resume: <known commands or verified refs needed to reconcile from this revision>
+```
+
+The watch ends only when registrations are stopped, receipts are recorded, and
+the PR is either merged or represented by this resumable state.

package/skills/axstack-watch/references/repair-publication.md

@@ -0,0 +1,69 @@
+# Repair and publication
+
+Read this only for authorized maintenance of an adopted own PR. Observation-only
+and peer modes stop with a report before this branch.
+
+## 1. Confirm the repair boundary
+
+Re-read the accepted maintenance snapshot, writable ownership, publication
+authority, remote head and base, and current feedback. Route an accepted fix to
+the original author session only when the run itself launched that session and
+evidence permits. For an adopted own PR under the automation, the repair
+author is the automation session (Claude/Opus) or a dispatched
+`axstack-author` (Sol); record that repair's actual provenance before
+selecting the reviewer, because the authored-review pairing follows the actual
+provenance of the repair, never the PR's historical author. A missing,
+stale, or materially changed boundary holds the repair while read-only
+monitoring continues.
+
+Record the exact defect, allowed files and actions, current revision, feedback
+IDs, and actual author without expanding scope. If actual author information is
+unknown, mixed, or unsupported and cannot establish an eligible configured
+reviewer, report that exact gap and ask the user; do not assume an author from
+the importing owner or orchestrator.
+
+## 2. Produce a reviewable candidate
+
+The author prepares the smallest in-scope repair and the exact public reply
+bodies, each keyed to its feedback ID and bound to the candidate revision. The
+candidate is committed locally in the per-PR child worktree and reviewed in
+authored mode at its local SHA; nothing is pushed for review. Both code and
+reply bodies receive the one complete eligible non-author/non-owner review
+required by the authored review rule in `axstack-review`.
+
+Publication stays held until the current authored review receipt covers the
+exact new revision and base, all six angles, applicable acceptance, the reply
+body identities, and every affected boundary, with no unresolved material
+finding or urgent hold. Under an automation the escalation gate of
+[Automation sessions](../../axstack/references/automations.md) also runs on
+the local SHA: publication additionally requires the gate to return `proceed`
+with no unresolved validated blocking finding, and a push before the gate
+settles is forbidden.
+
+## 3. Revalidate immediately before publication
+
+Confirm fresh remote head and base, feedback freshness, reply body identity,
+and the exact revision covered by the mode-required review receipt. Before a history
+rewrite, confirm the expected-old SHA; a mismatch holds publication.
+
+All publication inputs must still match their reviewed values at the final
+readback.
+
+## 4. Publish idempotently
+
+Use `gh stack` for the adopted PR only, preserving unrelated stack entries.
+Bind the operation to the exact reviewed revision, then verify the submission
+receipt and remote state.
+
+An automation session pushes fast-forward only: run the section 3 publication
+readback immediately before the push, then `git push` to the PR branch with no
+lease or force, and no `gh stack` sync or restack from an automation. A
+non-fast-forward remote is a recorded hold, never a rewrite.
+
+If the send outcome is unknown, inspect remote IDs, bodies, and actor before any
+retry. Remain blocked while the outcome is ambiguous; retry only after
+confirming the intended operation is absent.
+
+Publication ends with a remote receipt proving that the reviewed revision and
+exact replies landed once, or a recorded hold naming the unmatched input and
+next owner.

package/skills/axstack-watch/references/watch-runtime.md

@@ -0,0 +1,60 @@
+# Watch runtime
+
+Read this before starting, resuming, or stopping automated PR observation.
+
+## Accepted policy
+
+The PR owner remains accountable throughout one shared default 24-hour window.
+`axstack-monitor` and `axstack-watchdog` are independent, read-only roles, not
+authors, reviewers, repliers, or owners.
+
+- **Monitor:** `axstack-monitor` is an optional read-only observer that reads
+  GitHub, all PR feedback, and latest checks every five minutes, persists event
+  IDs, wakes the owner only for a new actionable event, and never sends.
+- **Watchdog:** `axstack-watchdog` reads only automation health, handshake
+  state, and snapshot freshness hourly and never mutates GitHub; it may perform
+  exactly one kind of send, a gate-authorized automation-health escalation
+  recorded in `watchdog.json`, and otherwise reports a verified health failure
+  to the owner.
+
+Healthy observations are snapshot-only and update quietly; they wake neither owner nor
+driver. Both roles deduplicate event IDs. Uncertain delivery is reconciled
+before retry. Restart reuses prior watch identity rather than registering a
+duplicate. The shared deadline ends earlier on completion or cancellation and
+is never silently renewed.
+
+## Native Orca automations
+
+Load the version-matched Orca automation guidance through the shared
+[runtime boundary](../../axstack/references/orca-runtime.md). The verified
+native automation schema supports provider selection, but model, effort, and
+permission pinning are unsupported, and its schedule parser cannot preserve
+the accepted bounded expiry by itself. Requested role values or a post-launch
+self-report are not effective launch evidence.
+
+The user lifted the native-watch hold by user decision on 2026-09-16. The accepted
+contract now has a new shape: the driver automation is a mutating owner for the
+PRs it handles, not an independent read-only monitor, and the watchdog keeps
+the independent read-only health contract. The driver is the automation
+session itself, with no `axstack-monitor` or `axstack-owner` role row
+materialized for it. The driver records its own model
+identity on every tick and the watchdog compares it with the expected model; a
+mismatch is a safety hold, never a silent substitution. The bounded expiry is
+enforced by the run record's watch deadline, not by the schedule parser. Still
+introduce no custom scheduler or polling loop and use no legacy runtime
+fallback. The session-level contract lives in
+[Automation sessions](../../axstack/references/automations.md).
+
+## Preserve the contract under automation
+
+An automation session preserves the roles, five-minute/hourly cadences, quiet
+healthy behavior, deduplication, handshake, watched scope, wake owner, and
+shared expiry. Test active expiry, missed final ticks, restart, duplicate
+ticks, cancellation, session-reuse fallback, and final cleanup before enabling.
+A firing timestamp proves neither delivery nor work advancement. An unrequested
+fallback session reconciles ownership and never becomes owner silently.
+
+At every end condition, stop all task-owned registrations, verify runtime
+cleanup receipts, and capture remaining work as resumable state. Removing watch
+coverage, weakening role discipline, or changing the deadline requires a
+material specification revision; it is not an implementation workaround.

package/src/capabilities.js

@@ -0,0 +1,138 @@
+// Host capability checks. `exec` is injected so tests never touch a live
+// runtime. Resolve Orca exactly once and reuse it: a failed choice never
+// triggers a fallback to another binary.
+export const BUN_FLOOR = '1.3.14';
+
+export const PROBE_LIMITATIONS = [
+  'A host binary probe cannot prove each agent session\'s Linear MCP access; skill prompts perform a session preflight instead.',
+  'A host binary probe cannot prove model availability or quotas; an unavailable or exhausted model pauses affected work until the user decides.',
+  'Stored role model, effort, and permission intent does not prove Orca launch parity or a successful agent execution.',
+];
+
+const CHECK_LABELS = {
+  bun: 'bun >= 1.3.14 runtime',
+  git: 'git CLI',
+  gh: 'gh CLI',
+  'gh-stack': 'gh stack extension',
+  'orca-binary': 'resolved Orca CLI',
+  'orca-runtime': 'Orca runtime connection',
+  'orca-orchestration-guide': 'Orca orchestration guide capability',
+  'orca-cli-guide': 'Orca CLI guide capability',
+};
+
+// The real commands behind each probe. gh-stack runs the actual
+// `gh stack --help`: a "stack" substring in `gh extension list` output is not
+// proof the extension command works.
+export const PROBE_COMMANDS = {
+  git: ['git', ['--version']],
+  gh: ['gh', ['--version']],
+  'gh-stack': ['gh', ['stack', '--help']],
+};
+
+export function resolveOrcaExecutable({ env = Bun.env, platform = process.platform } = {}) {
+  if (typeof env.ORCA_CLI_COMMAND === 'string' && env.ORCA_CLI_COMMAND.trim() !== '') {
+    return env.ORCA_CLI_COMMAND.trim();
+  }
+  if (typeof env.ORCA_DEV_REPO_ROOT === 'string' && env.ORCA_DEV_REPO_ROOT.trim() !== '') {
+    return 'orca-dev';
+  }
+  const managed = Boolean(env.ORCA_TERMINAL_HANDLE || env.ORCA_WORKTREE_ID);
+  if (platform === 'linux' && !managed) return 'orca-ide';
+  return 'orca';
+}
+
+function orcaCommand(name, executable) {
+  if (name === 'orca-binary') return [executable, ['--version']];
+  if (name === 'orca-runtime') return [executable, ['status', '--json']];
+  if (name === 'orca-orchestration-guide') {
+    return [executable, ['skills', 'get', 'orchestration', '--json']];
+  }
+  if (name === 'orca-cli-guide') return [executable, ['skills', 'get', 'orca-cli', '--json']];
+  return null;
+}
+
+function validateOrcaOutput(name, stdout) {
+  if (name === 'orca-binary') return { ok: true, stdout };
+  let parsed;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    return { ok: false, stdout: 'invalid JSON response' };
+  }
+  if (name === 'orca-runtime') {
+    const runtime = parsed?.result?.runtime;
+    const ready = parsed?.ok === true && runtime?.state === 'ready' &&
+      runtime?.reachable === true && runtime?.connectionState === 'connected';
+    return { ok: ready, stdout: ready ? 'ready and connected' : 'runtime is not ready and connected' };
+  }
+  const expected = name === 'orca-cli-guide' ? 'orca-cli' : 'orchestration';
+  const ready = parsed?.name === expected && typeof parsed?.markdown === 'string' && parsed.markdown.length > 0;
+  return { ok: ready, stdout: ready ? `${expected} guide available` : `${expected} guide unavailable` };
+}
+
+// Pure semver-floor comparison over numeric prefix segments ("1.3.14" style;
+// trailing build metadata is ignored).
+export function meetsFloor(version, floor = BUN_FLOOR) {
+  const nums = (s) => String(s).split('.').map((n) => Number.parseInt(n, 10));
+  const [v, f] = [nums(version), nums(floor)];
+  for (let i = 0; i < Math.max(v.length, f.length); i++) {
+    const a = Number.isInteger(v[i]) ? v[i] : 0;
+    const b = Number.isInteger(f[i]) ? f[i] : 0;
+    if (a !== b) return a > b;
+  }
+  return true;
+}
+
+export async function runRealCheck(name, { orcaExecutable = resolveOrcaExecutable() } = {}) {
+  if (name === 'bun') {
+    const version = Bun.version;
+    return { ok: meetsFloor(version), stdout: `v${version}` };
+  }
+  const [cmd, args] = orcaCommand(name, orcaExecutable) ?? PROBE_COMMANDS[name];
+  try {
+    const result = Bun.spawnSync([cmd, ...args], {
+      stdout: 'pipe',
+      stderr: 'pipe',
+      timeout: 10000,
+    });
+    if (result.exitCode === 0) {
+      const stdout = result.stdout.toString().trim();
+      return name.startsWith('orca-') ? validateOrcaOutput(name, stdout) : { ok: true, stdout };
+    }
+    const detail = (result.stderr.toString().trim() || result.stdout.toString().trim()).slice(0, 120);
+    return { ok: false, stdout: detail || `exit ${result.exitCode}` };
+  } catch (err) {
+    return { ok: false, stdout: err?.code ?? 'not found' };
+  }
+}
+
+export async function checkCapabilities(exec, resolution = {}) {
+  const orcaExecutable = resolveOrcaExecutable(resolution);
+  const names = [
+    'bun', 'git', 'gh', 'gh-stack', 'orca-binary', 'orca-runtime',
+    'orca-orchestration-guide', 'orca-cli-guide',
+  ];
+  const checks = [];
+  for (const name of names) {
+    let result;
+    try {
+      result = await exec(name, { orcaExecutable });
+    } catch (err) {
+      result = { ok: false, stdout: err?.message ?? 'error' };
+    }
+    const ok = !!result?.ok;
+    const baseLabel = CHECK_LABELS[name] ?? name;
+    checks.push({
+      name,
+      label: !ok && name.startsWith('orca-')
+        ? `${baseLabel} via ${orcaExecutable}`
+        : baseLabel,
+      ok,
+      detail: ok
+        ? String(result?.stdout ?? '').trim().slice(0, 120) || 'found'
+        : String(result?.stdout ?? result?.detail ?? '').trim().slice(0, 120) || 'not found',
+    });
+  }
+  const gaps = checks.filter((c) => !c.ok).map((c) => `missing ${c.label}`);
+  return { checks, gaps, limitations: [...PROBE_LIMITATIONS] };
+}