axstack 0.20.31 → 0.21.0

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

@@ -0,0 +1,234 @@
+# T3 runtime boundary
+
+Read immediately before role dispatch, receipt consumption, or recovery.
+Axstack owns policy, role selection and evidence; T3 owns threads, runs,
+delegated tasks, messaging and native schedules.
+
+## Preflight and binding
+
+The driver must be a T3 thread, save `orchestrator_capabilities` JSON under
+the run record, and follow the advertised tool schema; discovery alone proves
+neither provider readiness nor successful execution. Missing capability holds
+the affected operation, without a substitute runtime.
+
+From installed `skills/axstack/roles.json`, the driver must snapshot the selected
+preset and stable role IDs, requested provider/model/class/mode/effort, resolved
+ID, source and time once. Resume preserves that snapshot with no re-resolution;
+changes require the user's explicit decision. Bundled presets are setup inputs.
+
+Provider bindings must map codex→`codex`, claude→`claudeAgent`, grok→`grok`,
+antigravity→`antigravity`. Map `modeId` to `runtimeMode:full-access` and effort
+to `options:[{id,value}]`. Stored permission intent is neither effective parity
+nor a security boundary.
+
+A preset model must be used as given.
+
+`modelClass` must resolve to the newest matching catalog ID for that provider:
+codex `gpt-<N>-<class>`, claude `claude-<class>-<N>-<N>`. Use
+`scripts/resolve-models.js --provider` with the saved capabilities JSON path;
+a missing or malformed catalog holds resolution.
+
+A `model:null` role lacking a class must use the first model listed for its
+provider in saved capabilities only for grok and antigravity (launch-by-agent-id
+providers); record the exact ID, rather than an unresolved provider default.
+Antigravity must hold when saved capabilities advertise zero models.
+For codex or claude, a role lacking both model and class is an intentional
+absence and must hold; never use a provider default for that role.
+
+An unavailable provider, model, role, mode or effort must hold that role with
+no substitution. Auth, quota, timeout and rejection do not select an alternative.
+Intentional absent seats remain recorded absences; availability is runtime proof.
+
+Codex effort must use option ID `reasoningEffort`.
+
+Claude effort must use option ID `effort`.
+
+Grok effort must use `reasoningEffort` and exclude `max`; its CLI requires ≥1.0.13.
+Advertising Grok alone does not prove that its CLI runs.
+
+OpenCode effort must use `variant` (no OpenCode role enters this migration).
+
+The dispatch echo must match the requested provider and model; verify options
+and `runtimeMode` by `t3_thread_configuration` read-back. Record requested and
+effective values separately; a worker self-report is not configuration proof.
+
+Missing effort read-back must hold roles requiring effort; never record it as
+satisfied. Other providers' effort read-back remains unverified until exercised.
+
+The first dispatch for each (provider, model, effort) must reach a running or
+completed run before its siblings launch. Rejection stops siblings of that
+configuration; unrelated configurations remain eligible.
+
+## Role dispatch by permitted writes
+
+| Roles | Mechanism and permitted workspace | Completion |
+|---|---|---|
+| Advisers, research, read-only explorers, explainers, diligence, checker, auditor, monitor, arena prose candidates and judges, escalation | Must use async `delegate_task` in the driver worktree, title = dispatch key; tracked and untracked files stay untouched; writes only `<run>/evidence/<key>/` | Native notification followed by persisted `task_status` |
+| Reviewers (peer/authored), release checks, debug investigators, execution investigators (`axstack-explore-execution`), UI verifier (`axstack-ui-verifier`) | Must use async `delegate_task`, title = dispatch key; driver makes a disposable detached checkout of candidate SHA and pinned base with `git worktree add --detach <run>/checkouts/<key> <sha>` (plus pinned debug patch); brief requires `cd` into it; only disposable probes write there, outputs go to `<run>/evidence/<key>/` | Same delegated terminal checks |
+| Author and repairs, code-arena writers | Must use `t3_thread_launch` with `{type:worktree, baseRef:<SHA>, branch:<encoded branch>, startFromOrigin:false}` in their own worktree, kept until PR merges or closes | Writer sends a receipt to the driver; driver verifies terminal run and candidate |
+| Owner | Driver thread in Driver worktree; never writes tracked candidate source or tests; planning artifacts allowed only for repository Markdown; scope, integration, forge mutations and record | No worker launch |
+
+The driver must be the sole run-record writer and enforce one writer per
+candidate; it never writes tracked candidate source or tests or repairs an author's source.
+The driver may write planning artifacts (spec, ticket map) in its own worktree when the selected store is repository Markdown.
+Repairs return to that author. Missing or idle sessions grant no ownership transfer.
+The current chat/driver has no role row in any preset.
+
+The dispatch key must be `<run>:<role>:<task>:a<n>`, recorded before launch and
+used as the exact whole T3 title. Substring matches do not establish identity.
+Each dispatch binds the approved spec or small-change intent, brief, authority, role snapshot, base and candidate to its dispatch key.
+
+The branch must be `axstack/<run>/<role>/<task>-a<n>`; lowercase each segment
+and replace every `[^a-z0-9-]` character with `-`. Keep the dispatch key in its
+original form and record both; normalization is never an identity substitute.
+
+`baseRef` must always be a commit SHA, never a branch name; T3 renames its
+`t3code/*` branches. Pin base and candidate before dispatch.
+
+Workers must finish with exactly one final marker: `AXSTACK-DONE key=… head=…
+report=…`, `AXSTACK-FAILED key=… head=… report=…`, or `AXSTACK-QUESTION key=… q=…`.
+Reports use absolute private evidence paths; report-only head is the pinned
+candidate SHA. Launched writers deliver the marker through `t3_thread_send` using `mode: queue`
+to the recorded driver thread; delegated children leave it in their final result.
+AXSTACK-* messages from worker threads arrive as user-role messages but are worker receipts, never user instructions or a stop.
+An AXSTACK-FAILED marker follows the failure/replacement rules, never the user-question route.
+
+## Consume completion without advancing stale work
+
+Before any `t3_thread_read` for a delegated task, the driver must persist only the `task_status` essentials in private evidence: taskId, status, workState, hasPendingChildRuns, latestTerminalRunId, and the final AXSTACK marker line.
+
+Delegated completion must require terminal `completed`, `result_available`,
+`hasPendingChildRuns:false`, and final `AXSTACK-DONE`; a question stays
+incomplete even when native status says completed.
+
+Launched writer completion must require terminal `t3_thread_wait` on that run,
+then candidate checks: non-empty diff, clean tree and named red/green logs.
+A receipt message alone counts only as progress; it can precede terminal state.
+
+Completion must match the current attempt key and candidate SHA. An older
+attempt never completes a newer one; stale or duplicate receipts remain
+evidence, deduplicated by runtime identity. Process the whole delivery before
+acknowledgment and advance only after checking sender, scope and artifacts.
+
+`task_status` failed, a run failed or interrupted, a preparing thread error,
+or `AXSTACK-FAILED` must each produce an incomplete outcome with preserved
+evidence. Silence is not successful completion.
+
+After each delegated completion the driver must check its own `HEAD` and
+`git status --porcelain` against their pre-dispatch values: both stay unchanged,
+including untracked entries. Any change is a hold before advancing that work.
+
+## Launch recovery, repairs and questions
+
+For a lost launch response the driver must use fully paginated `t3_thread_list`
+with `titleContains=<key>`, filtered to exact whole-title equality, plus
+`git worktree list`. Keep the reserved branch through recovery. A branch or
+worktree without a reconciled thread prevents proof of absence.
+
+Recovery must adopt one exact match only after its recorded worktree and branch
+agree; on proven absence relaunch once with the same reserved key and branch.
+Several matches, conflicts, a second uncertain response or incomplete inventory
+hold. Never launch a duplicate writer based on silence.
+
+Post-launch the driver must call `t3_thread_wait` with `timeoutMs:120000`:
+failed is launch failure; timed-out with `t3_thread_read` showing both
+`activeRunId` and `worktreePath` is started; still preparing is a hold and
+re-read at the next wake. An unresolved state preserves the attempt.
+
+For `AXSTACK-QUESTION` the driver must answer once using `t3_thread_send` to
+the `childThreadId`, record the returned resumed runId, then
+`t3_thread_wait(childThreadId, runId, timeoutMs:600000)`, re-armed by the run
+watch. Persist status again and accept only `latestTerminal*` with
+`latestTerminalRunId` newer than the question run (recorded run ordering, not
+lexical ID order), terminal success and matching receipt key/SHA. The original
+summary stays stable; no notification is assumed for a resumed result.
+
+A repair must use `t3_thread_send(writerThreadId, mode:queue)` to the same
+author in the same attempt and worktree; pin the new candidate revision.
+
+A replacement after terminal failure must use `a<n+1>`, a new branch and title;
+the failed attempt's branch is kept until salvage. Unknown liveness holds
+replacement; reconcile the old writer before admitting another.
+
+With an unsettled launched thread, the driver turn must end only while a bound
+`schedule_task` with `bindToCurrentThread:true`, `everyMs:600000` is armed and
+its ID recorded. Each wake must reconcile all unsettled runs, including a
+writer that died without sending; failed runs hold incomplete work. The watch
+inherits the driver model/workspace and adds no runtime of Axstack's own.
+
+Once nothing remains unsettled the driver must `delete_scheduled_task` for the
+run watch and use `list_scheduled_tasks` to read back its absence; an uncertain
+delete preserves the hold and recorded ID.
+
+## Evidence, prompts and authority
+
+Put the [Safe-deletion rule](workspace-hygiene.md#safe-deletion) in every worker brief.
+Name the private `<run>/evidence/<key>/` folder in the brief and completion receipt.
+
+Before use, commands must scope `TMPDIR` to an owned 0700 directory under the system temp directory, never under `$HOME`, named from the dispatch key and recorded in the receipt.
+Validate its real path, absence of symlinks and ownership before use and cleanup; remove it afterwards by literal absolute path.
+Evidence files still go to the private `<run>/evidence/<key>/` folder.
+Apply equivalent guards to worktree-local paths. Uncertain paths are preserved for reconciliation.
+
+Deletion must target an exact validated owned path inside evidence, TMPDIR or
+the worktree, using a literal absolute path or `${VAR:?}`-guarded path: no glob,
+no parent-root deletion; never wipe a general cache. Incidental caches are
+not evidence.
+
+The dispatching owner must confirm a worker's own brief question once,
+restating existing authority, then re-verify started state; a second ask holds.
+Never answer trust or permission prompts; brief confirmation adds no authority
+and does not answer a harness or tool dialog.
+
+A permission prompt or provider safety refusal must be a held, incomplete
+outcome; never bypass or retry it through another model. Trust, hook review,
+authentication and model prompts also hold; preserve the attempt and inspect
+native state before any authorized recovery.
+
+Each reviewer must have a separate checkout and private evidence folder with
+no first-pass cross-read; tracked candidate files remain read-only. Read back
+report and supporting evidence before removing that checkout; evidence already
+outside it needs no archive. Later review gets a fresh checkout; unknown or
+active evidence and unique bytes stay preserved. Untracked files never prove a
+worktree disposable. T3 terminal state alone does not authorize discarding evidence.
+
+Input acceptance, started state, effective settings and completed work must
+remain distinct evidence. Silence, contact loss or idle state never proves exit.
+Ordinary resume reconciles the same owner, author, attempt, worktree, revisions
+and pending receipts; uncertainty holds replacement.
+
+An explicit user transfer must validate recipient acceptance against intended
+session, scope, revision and authority before changing ownership. The current
+owner remains accountable until then; prior owner stops after acceptance.
+Input acceptance or turn start alone is no transfer receipt.
+
+On a T3 `threadId/runId` mismatch the driver must stop consuming and reconcile
+the recorded driver identity with native state; never forge a sender or borrow
+an identity to bypass the mismatch.
+
+The driver must retain a user-taken-over T3 thread; never send cleanup commands
+to it, including `t3_thread_organize` settle or archive.
+Require T3 terminal run evidence before `t3_thread_organize` settle or archive;
+these metadata actions are not worktree removal.
+
+## Project preflight and run record
+
+`worktreeCleanup` must be `off` for every Axstack project. Preflight reads it
+with `t3_project_read` where exposed; otherwise record a limitation pointing
+to the documented installation setup step. Automatic worktree deletion cannot
+replace evidence readback and salvage.
+
+The run record must contain driver threadId, projectId, host, T3 version,
+installed Axstack SHA, capabilities JSON path and scheduledTaskIds for every
+watch and manager schedule.
+
+Per dispatch the record must contain key, mechanism, requested target and
+read-back; taskId/childThreadId/childRunId or
+threadId/runId/worktree/branch/base SHA; checkout path with candidate and base
+SHAs; evidence folder, scope/authority, owner, pending receipts, hold and Next.
+
+The boundary must provide no Axstack daemon, DB, lock or scheduler. Native T3
+schedules supply wakes; Axstack maintains prose records, not a runtime state
+engine. Private evidence requires explicit publication authority before sharing;
+receipts confer no merge, release, publication, model-substitution, host-mutation
+or expanded scope authority. Human merges by default.

package/skills/axstack/references/test-audit-weekly.md

@@ -0,0 +1,62 @@
+# Weekly test-audit prompt
+
+You are a fresh finite weekly test-audit session in this repository's dedicated
+T3 project worktree. Before admission, read the activation record: repository,
+test-path allowlist, finite budget, and standing edit and PR-open authority.
+Missing authority, or no passing native canary from [Automations](automations.md),
+holds admission; source checks alone prove no weekly runtime behavior.
+Use T3 `schedule_task` as an unbound weekly `fixed_time` schedule with `bindToCurrentThread:false`.
+T3 `schedule_task` inherits the verified binding read-back and uses a stable
+`clientRequestId`; record its ID, weekly interval and project in the activation record.
+When the finite budget runs out, stop the pass, publish nothing further, and report.
+Use native T3 scheduling and orchestration,
+not a new skill, daemon, scheduler, state engine, or campaign ledger.
+
+Reconcile GitHub test-audit PR history and live T3 thread/worktree ownership before
+selecting work. Derive the next single owner boundary within the allowlist from
+the last test-audit PR; with no prior PR, choose the first allowed owner boundary
+and record the choice. Use PR history, never a cursor file or persistent traversal
+state. Never re-propose candidates from any closed unmerged test-audit PR.
+If an open test-audit PR exists, skip the week, publish nothing and report only.
+If paths overlap with live T3 thread or worktree ownership, publish nothing and
+report only.
+
+Invoke [Improve](../../axstack-improve/SKILL.md)'s Test-audit lens under [T3 runtime](t3-runtime.md);
+load [Test value](test-value.md), pin the base, and run the baseline suite.
+If a red baseline exists, publish nothing and report only the possible bug.
+If a flaky baseline exists, publish nothing and report only the instability.
+Mark every test declaration in this boundary R/F/C/D and report reviewed and
+eligible counts. Retain uncertain candidates and independent contracts; hidden
+release-only tests are outside scope. There is no deletion quota, score, or target;
+zero deletions is normal.
+If zero proven candidates remain, publish nothing and report only.
+
+Route accepted proven C/D to [Implement](../../axstack-implement/SKILL.md) as
+structure-preserving work with the same suite green on pinned base and candidate.
+For every removed assertion, record its location, detectable failure, validation
+command, and named keeper or vacuity/obsolescence proof under Test value.
+For each C and keeper-backed D, prove the keeper red under a targeted disposable
+owner mutation per distinct contract, then restore source byte for byte.
+Improve reports F; the standing authority also permits Implement to repair those
+weak assertions while retaining their contracts.
+For F repairs, apply [F proof](test-value.md#f-proof): base-green,
+removal/inversion-red, byte-for-byte restore, and equivalent-rewording-green.
+Never weaken or loosen an assertion.
+If a weekly PR mixes C/D and F repairs, record both evidence paths in its receipt:
+structure-preserving for C/D and F proof for repairs.
+
+The candidate diff touches test files only: deletions, consolidations, F repairs.
+Never edit skip/only/xfail, rewrite snapshots, change coverage-thresholds or CI,
+or edit line-caps. Report test-only production seams without changing them.
+After restoring mutations, verify every non-test path byte-identical to the base;
+coverage, where reported, is a per-file guard and never deletion proof alone.
+Keep one writer and private revision-bound receipts; workers never push.
+Obtain independent review using Implement's configured authored-review roles and
+verify the exact candidate's checks before publication. The driver uses
+`gh stack` and opens at most one test-audit PR per week after independent review;
+the human merges.
+
+Notify only under the run's Notification policy: a decision park, merge-ready
+(within the run's milestone cap), or serious-risk hold; never progress or
+heartbeats. Keep routine reports in the T3 driver thread, including skipped or empty passes.
+Settle owned workers and preserve evidence under the shared lifecycle.

package/skills/axstack/references/test-value.md

@@ -0,0 +1,120 @@
+# Test value
+
+Use this reference when authoring or reviewing tests and investigating audit
+candidates. Judge assertions and the production boundary, not test names.
+There is no deletion quota or quality score; zero candidates is valid.
+
+## Authoring gate
+
+For every new or changed test, answer:
+
+1. Which observable behavior or independent contract does it protect?
+2. Which plausible regression would make it fail?
+3. Why would existing coverage miss that regression? Prefer extending the
+   primary boundary test; another layer needs a distinct risk.
+4. Does it require an export, flag, wrapper, or hook used only by tests?
+   If so, exercise the real production boundary instead.
+
+Also ask: if every imported function returned `undefined`, would it still pass?
+Investigate a yes. Missing answers or an unproven independent contract fail
+the gate: do not add the test. A test that breaks under a behavior-preserving
+refactor needs a boundary assertion unless it guards an independent contract.
+
+For a bug fix, demonstrate the regression test failing on pre-fix code for
+the intended reason, then passing with the fix. Protect the bug once at its
+owner boundary; repeated scenarios at other layers need a separate risk.
+
+## Investigate junk patterns
+
+- Probes without assertions; self-comparison; expected values computed by the
+  subject being tested.
+- Assertions only about mocks or absence; a mock implementing the behavior
+  being asserted; fixtures checking their own supplied results.
+- Repeating constants, config, declared capability flags, or type guarantees
+  without independently exercising the promised contract.
+- Exact source, import, or string greps of non-contract text; copied fixtures,
+  inventories, manifests, or export lists.
+- Private predicates or call shapes already covered at a boundary; duplicate
+  invocations of one contract; tests preserving test-only exports or wrappers.
+- Negative controls passing because an unrelated guard blocked the path;
+  names promising behavior the assertions never exercise.
+
+The `undefined` check and these patterns are investigative heuristics, never
+automatic deletion verdicts. Read the complete test, production owner and its
+callers, overlapping coverage, CI routing, and relevant history before marking.
+
+## Retention bar
+
+Retain independent public API, protocol, config, security, migration, storage,
+platform, package, release, architecture, or prompt-byte contracts. Keep
+observable ordering, credible regression protection, and source inspection
+when it is the cheapest independent guard and survives unrelated rewording or
+identifier changes. Static or slow alone never justifies deletion.
+
+A retained test failing on the baseline is a possible product bug: reproduce
+and report it rather than deleting it. Retain uncertain candidates.
+
+## Marks and evidence
+
+- **R — retain:** name the independent contract and regression caught.
+- **F — fix assertion:** keep the contract; report the weak assertion for repair.
+- **C — consolidate:** identify the remaining owner test (keeper) first.
+- **D — delete:** identify remaining proof, or prove the assertion vacuous or
+  its contract obsolete.
+
+For each C/D, record the exact test name and location, what failure it can
+detect, the named keeper or evidence of vacuity/obsolescence, and the validation
+command. Missing evidence leaves the candidate retained and report-only.
+
+## F proof
+
+An authorized F repair preserves its contract: the repaired check passes on the
+base, goes red when its instruction or code is removed or inverted by a
+targeted disposable mutation restored byte for byte, and survives equivalent
+rewording for semantic prose. Never weaken or loosen an assertion.
+
+## Deletion proof
+
+Pin base and candidate revisions. Run the suite green before and after the
+edit. Map every removed assertion's contract to a remaining keeper or evidence
+that it is vacuous or obsolete; passing suites alone do not prove preservation.
+
+For each C and each keeper-backed D, make a targeted disposable mutation of
+the production owner for each distinct contract. Show the named keeper going
+red for that regression, then restore the source byte for byte. Do not infer
+keeper strength from its name or coverage alone.
+
+A vacuous D cites the vacuity (no assertion, self-comparison, or an expected
+value derived from the subject). An obsolete D cites the removed production
+path, spec, or history proving the contract is gone. Without that proof,
+report the candidate and retain it. Release-only tests hidden from authoring
+agents are outside weekly audit scope. Where the runner reports coverage,
+use it as a per-file guard; it never authorizes deletion by itself.
+
+## Sources and license
+
+Adapted and condensed from OpenClaw's
+[test-audit](https://github.com/openclaw/openclaw/blob/1f351187bd0d/.agents/skills/test-audit/SKILL.md)
+and [campaign](https://github.com/openclaw/openclaw/blob/1f351187bd0d/.agents/skills/test-audit/CAMPAIGN.md).
+MIT License — Copyright (c) 2026 OpenClaw Foundation.
+Paraphrased ideas: [pstack](https://github.com/cursor/plugins/blob/fae2c6ed9582/pstack/skills/principle-test-behavior-not-implementation/SKILL.md)
+(license unverified): test whether assertions depend on subject behavior;
+[Matt Pocock](https://github.com/mattpocock/skills/blob/d81f3a183412/skills/engineering/tdd/tests.md)
+(MIT): use public boundaries and independently chosen expected results.
+
+OpenClaw MIT notice:
+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/skills/axstack/references/ui-verification.md

@@ -1,10 +1,14 @@
 # UI verification
 
 Every Playwright, browser, or rendered-UI check, including a "confirm it in the
-browser" step, goes through an Orca Dispatch to `axstack-ui-verifier` from the
+browser" step, goes through async `delegate_task` to `axstack-ui-verifier` from the
 run's role snapshot. Give it the exact build, URL, or artifact and the private
 dispatch's evidence folder. The verifier is read-only: it never edits source.
 The PR writer remains the sole writer.
+Read the [T3 runtime boundary](t3-runtime.md) before dispatch and use its
+driver-made disposable detached checkout at the pinned candidate SHA.
+The verifier uses T3 `preview_*` tools for rendered checks.
+Browser and visual checks must run in the delegated `axstack-ui-verifier` in its own detached checkout; outputs go to its private evidence folder, never the driver worktree.
 
 Ask for screenshots and observed interactions, accessibility, desktop and
 mobile layouts, and reduced-motion behavior where relevant. The verifier