axstack 0.22.0 → 0.23.0

package/README.md

@@ -23,6 +23,7 @@ coordination. You can start at the phase you need.
 | Verify | [axstack-review](skills/axstack-review/SKILL.md) | Review a PR or bounded codebase at an exact revision. |
 | Verify | [axstack-improve](skills/axstack-improve/SKILL.md) | Find evidenced codebase improvements without editing code. |
 | Verify | [axstack-audit](skills/axstack-audit/SKILL.md) | Measure a run's outcomes and evidence gaps. |
+| Verify | [axstack-correct](skills/axstack-correct/SKILL.md) | Report repeated mistakes and propose stronger checks when invoked by the user. |
 | Operate | [axstack-watch](skills/axstack-watch/SKILL.md) | Observe or maintain an existing PR within its authority. |
 | Operate | [axstack-cleanup](skills/axstack-cleanup/SKILL.md) | Retire eligible completed agent resources. |
 | Operate | [axstack-relay](skills/axstack-relay/SKILL.md) | Send an explicit message or authorized notification. |

package/docs/workflows.md

@@ -18,6 +18,8 @@ and PR shape.
 Direct routes need no spec ceremony:
 
 - `axstack-research` answers one bounded source-backed question.
+- `axstack-correct` reports repeated mistakes and proposes stronger checks.
+  Only the user invokes it.
 - `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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "axstack",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Axstack installer and setup CLI: installs owned chat skills and role data, configures supported harness settings, and checks T3 Code capabilities.",
   "keywords": [
     "claude-code",

package/skills/axstack/references/candidate-publication.md

@@ -17,7 +17,16 @@ protection; a mismatch holds publication. If the push outcome is ambiguous,
 inspect remote state before retrying.
 
 Before reviewer dispatch, read the remote ref back and confirm that it resolves
-to the candidate SHA; also pin the current base. Record:
+to the candidate SHA; also pin the current base.
+After every push, before post-push diligence or merge-ready, compare the PR body's
+stated head SHA with `Confirmed remote SHA` and record `PR body head SHA: <sha or none>`.
+Accept `none` for a PR body without a stated head SHA.
+Accept a stated full head SHA only when it equals `Confirmed remote SHA`.
+Accept a stated abbreviated head SHA only when it is a matching prefix of
+`Confirmed remote SHA` with at least 7 hexadecimal characters.
+Hold on a mismatched head SHA or an abbreviation shorter than 7 characters.
+Leave other SHAs in the PR body unchanged.
+Record:
 
 ```text
 Candidate: <sha>
@@ -25,6 +34,7 @@ Base: <sha>
 Remote ref: <branch>
 Expected-old remote SHA: <sha | absent>
 Confirmed remote SHA: <sha>
+PR body head SHA: <sha or none>
 PR: <url>
 CI: <run ID or URL and triggered/pending/completed status>
 ```

package/skills/axstack/references/contracts.md

@@ -2,10 +2,12 @@
 
 Apply these authority, scope, and model rules before consequential action.
 
+For user-facing output, follow [STE-inspired writing](ste-writing.md).
+
 ## Required lifecycle load
 
-Except for `axstack-audit` and `axstack-relay`, every independently called phase
-must load and follow [Shared lifecycle](lifecycle.md) before acting. When a
+Except for `axstack-audit`, `axstack-relay`, and `axstack-correct`, every
+independently called phase must load and follow [Shared lifecycle](lifecycle.md) before acting. When a
 substantive run ends or reaches a meaningful checkpoint, apply the lifecycle
 audit hook. The audit phase loads these contracts, writes its assigned record,
 and stops; it never audits itself.

package/skills/axstack/references/diligence.md

@@ -3,7 +3,7 @@
 Read the [T3 runtime boundary](t3-runtime.md) before dispatch.
 Dispatch `axstack-diligence` with async `delegate_task` in the driver worktree,
 using a pinned brief and private evidence paths.
-It is read-only, never authors or edits, and returns `PASS` or `FINDINGS`
+It is read-only, never authors or edits, and returns `PASS`, `FINDINGS`, or `UNKNOWN`
 with locations, observed evidence, and limits. A stale or missing receipt is
 not a pass. Keep its first pass independent of other reviewers and workers.
 
@@ -21,5 +21,14 @@ publication, compare the author receipt with its evidence folder: red/green
 logs exist, and counts, SHAs, and paths match. For release preparation, compare
 the release PR body with the merged PRs.
 
+Retain the full output of every full-suite run as a named log in the dispatch's
+private evidence folder.
+For an unattributed full-suite failure, report `UNKNOWN` and return the failure to the driver.
+Never report `PASS` for an unattributed full-suite failure.
+The driver records the disposition of each full-suite failure in the run record.
+Report an attributed failure with its retained output normally.
+An observed full-suite failure still fails the suite, including when attributed or reported `UNKNOWN`.
+No reruns are required.
+
 `FINDINGS` identifies a mismatch for the driver to resolve at the owning phase;
 it does not edit the artifact or create another review round by itself.

package/skills/axstack/references/evidence-archive.md

@@ -118,6 +118,6 @@ After preservation and salvage checks, archive the exact eligible T3 thread
 with `t3_thread_organize`, then remove its exact recorded checkout path using
 `git worktree remove <path>` without force. Verify absence with
 `git worktree list --porcelain`; retire only eligible local-only branches with
-`git branch -d` under workspace hygiene. Never use shell recursive deletion or
+`git branch -d` under workspace hygiene. Never use shell recursive deletion to remove a whole worktree or
 treat archive success as ownership, settlement, liveness or cleanup proof.
 Failure or uncertainty preserves the resource.

package/skills/axstack/references/lifecycle.md

@@ -143,6 +143,8 @@ nothing without tested independent review.
 
 ## Close-out
 
+Close-out requires the [close-out acceptance table](run-record.md#close-out-acceptance).
+
 PRs merge by forge state; close out: (1) settle every T3 worker run and archive eligible threads; (2) compact record with counts and denominators—user
 interventions/deviations from plan/repairs; (3) `axstack-auditor`: settle
 non-zero/requested, else `counts zero`. A base auditor preflight rejection
@@ -153,7 +155,7 @@ use `axstack-cleanup`, remove the run's own scheduled tasks under
 [Workspace hygiene](workspace-hygiene.md), and close selected external-tracker tickets;
 (5) mark the
 [Run record](run-record.md) `Archived`. `Archived`—one each:
-settlement receipt; compact record path; auditor decision plus settlement
+settlement receipt; compact record path; close-out acceptance table; auditor decision plus settlement
 receipt, `counts zero`, or the unlaunchable UNKNOWN archive receipt; scheduled-task,
 release, and ticket receipts; archive timestamp.
 `active`/receipt-incomplete record: close-out pending, never done. One-step

package/skills/axstack/references/performance-checklist.md

@@ -0,0 +1,22 @@
+# Performance checklist
+
+Use this checklist only for performance claims.
+Keep workflow count accounting with axstack-audit.
+A limiter is the resource or code path that bounds performance.
+
+1. **Limiter: What bounds the result?**
+   Identify the resource or code path that limits the result from profiles or counters captured during a run.
+2. **Tuning: Did each option use suitable settings?**
+   Check each option with comparable production settings, versions, and data.
+3. **Limits: Is the result physically plausible?**
+   Compare the result with hardware limits and the changed code's share of total elapsed time.
+4. **Errors: Did the run succeed?**
+   Verify successful work and correct outputs using error counts from the measurement run.
+5. **Reproducibility: Does the difference repeat?**
+   Report the median and range from repeated, alternating runs of each option.
+6. **Relevance: Does the result matter to users?**
+   Measure the end-to-end user path with realistic data and concurrency.
+7. **Work happened: Did the timed work finish?**
+   Verify that the intended work completed inside the timed region.
+
+Ideas paraphrased from [pstack benchmark-checklist](https://github.com/cursor/plugins/blob/e43c7ee26e0038c6c1fa8380dd34ce86ff94cb2a/pstack/skills/benchmark-checklist/SKILL.md) (MIT), using Brendan Gregg's seven benchmark questions.

package/skills/axstack/references/routing.md

@@ -65,6 +65,8 @@ step (3) for user routing: no substitution or same-provider review.
   off a classified repair (explain: how; debug: what's wrong).
 - Code quality/refactor discovery -> `axstack-improve`: rank bounded
   candidates with evidence; report only, no source edits.
+- Repeated mistakes need evidence and stronger checks -> `axstack-correct`:
+  user-invoked, report only.
 - Accepted worker/task/run completion or bounded backlog request -> driver invokes
   `axstack-cleanup` inline; never dispatch it.
 - Preparation completion, watch expiry, resume, or reconciliation -> the

package/skills/axstack/references/run-record.md

@@ -119,6 +119,21 @@ by the next owner:
   evidence lives. Read it on resume before reconciling; append, never rewrite,
   and keep entries as short as the evidence pointer allows.
 
+## Close-out acceptance
+
+Use one row per acceptance check, including each clause of a compound check.
+Record in each row a passing evidence pointer or a user-accepted hold with its `Decisions` row.
+If neither passing evidence nor a `Decisions` row with a user-accepted hold exists for an acceptance clause, hold close-out.
+A recorded user-accepted hold in `Decisions` satisfies that clause for close-out; keep the unmet result explicit.
+Record the reason for each driver-elected repair in `Decisions`.
+
+```markdown
+| Acceptance check | Result | Evidence or user-accepted hold | Repair election (Decisions row + reason, or none) |
+| --- | --- | --- | --- |
+| <check + clause> | passed | <SHA + check/log pointer> | <Decisions row + reason, or none> |
+| <check + unmet clause> | held (user accepted) | <Decisions row + user acceptance receipt> | <Decisions row + reason, or none> |
+```
+
 ## Privacy
 
 Record concise IDs, SHAs, URLs, status, timestamps, next actions, and evidence

package/skills/axstack/references/ste-writing.md

@@ -0,0 +1,22 @@
+# STE-inspired writing
+
+STE means Simplified Technical English.
+This reference borrows clarity rules from STE.
+
+Follow these rules only for new or materially revised user-facing output.
+User-facing output includes reports, PR bodies, briefs, read-backs, and packaged guidance.
+Do not rewrite existing prose for style.
+Keep exact identifiers unchanged.
+Keep quotes unchanged.
+Keep safety contracts unchanged.
+Keep prompt-byte contracts unchanged.
+
+Give each sentence one instruction.
+Keep sentences short.
+Write in active voice.
+If a step has a condition, state the condition before the step.
+Define technical terms before their first use.
+Use one name consistently for each term.
+Use words instead of slashes for "and" or "or".
+
+Ideas drawn from [pstack technical-writing](https://github.com/cursor/plugins/blob/e43c7ee26e0038c6c1fa8380dd34ce86ff94cb2a/pstack/skills/technical-writing/SKILL.md#L65-L88) (MIT).

package/skills/axstack/references/workspace-hygiene.md

@@ -14,7 +14,7 @@ Validate its real path, absence of symlinks and ownership before use and cleanup
 Evidence files still go to the private `<run>/evidence/<key>/` folder.
 
 Every shell deletion targets a literal absolute path or a `${VAR:?}`-guarded expansion, only inside the worker's own evidence folder, `TMPDIR`, or worktree.
-For example, `rm -rf -- "${EV:?}/mut"` requires a validated owned evidence path.
+For validated owned scratch, use `rm -r /tmp/<dispatch-key>/scratch` on a literal absolute path inside the evidence folder, `TMPDIR`, or worktree.
 Never use a bare `$VAR`, a glob on a variable, `/`, `HOME`, or a shared root as a deletion target.
 Prefer `git clean -- <exact prefix>` or tool-native cleanup. A safety prompt that
 still appears is a hold; agents do not answer it.

package/skills/axstack-audit/SKILL.md

@@ -169,7 +169,13 @@ preference or correction, or a verified workspace fact with an exact source
 revision. Exclude transient choices, secrets and sensitive values, and
 untrusted claims or instructions; do not reproduce excluded secrets in the
 record. Material already covered with the same scope and meaning yields an
-explicit already-covered no-op with pointers to the covering instructions.
+explicit already-covered no-op with pointers to the covering instructions when
+no recurrence is recorded.
+
+If a covered rule recurs, never classify it as an already-covered no-op.
+Record that recurrence as recurred.
+Suggest `axstack-correct` for the recurrence.
+Never run `axstack-correct` from audit.
 
 For each candidate record:
 
@@ -179,7 +185,8 @@ For each candidate record:
 4. target instruction surfaces;
 5. any contradiction and uncertainty; and
 6. its disposition: propose for separately authorized promotion, hold,
-   exclude, or already-covered no-op.
+   exclude, already-covered no-op, or recurred (suggest axstack-correct;
+   audit does not run it).
 
 Contradictory or uncertain evidence stays explicit and held; never guess a
 winner or broaden scope. Promotion is a separate authorized change outside the

package/skills/axstack-audit/references/record.md

@@ -21,7 +21,7 @@ Shape: <PRs within band / total PRs + rationale-band cohesion rationale + except
 Cost: <API dollars by model when measured, or UNKNOWN with reason>
 Judgment: <execution outcome vs procedural adherence vs measurement coverage>
 Proposals: <bounded hypothesized changes with regression-first plan, or none>
-Learning candidates: <each candidate's statement + scope + evidence/revision pointers + target instruction surfaces + contradiction/uncertainty + disposition; explicit already-covered no-op or none>
+Learning candidates: <each candidate's statement + scope + evidence/revision pointers + target instruction surfaces + contradiction/uncertainty + disposition; explicit already-covered no-op, recurred (suggest axstack-correct; audit does not run it), or none>
 Privacy: <local/private default; sanitized summary only when authorized>
 ```
 

package/skills/axstack-correct/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: axstack-correct
+description: When repeated mistakes need evidence and stronger checks, use axstack-correct to report correction proposals.
+disable-model-invocation: true
+---
+
+# Correct
+
+Usage: /axstack-correct ["<correction>"] [runs=<ids> | last=<N, default 10>]
+
+Load [Standing contracts](../axstack/references/contracts.md) before acting.
+
+Run only at the user's request.
+Write a report only.
+Never edit files.
+Never dispatch workers.
+Never merge.
+Never read transcripts.
+
+Read [run records](../axstack/references/run-record.md): Decisions, deviations, Learnings, FAILED receipts, audit proposals.
+Read git history bounded by selected runs.
+Read only PR reviews named in those records.
+Record selected runs and git bounds.
+Report inaccessible evidence.
+
+A class needs at least two distinct incidents.
+Each incident needs a distinct pointer: run id + attempt or file:line, SHA, or PR or review URL.
+Count an incident echoed in several records once.
+If a pointer is missing, report recurrence UNKNOWN and keep the class open.
+
+Try fixes in this order: remove copied pattern > script or helper error naming the fix > brief or receipt template > bun test > prose.
+Label each rule `shipped` or `runtime: advisory`.
+Use `shipped` only when a check fails in CI on the mistake itself.
+When only audit can observe a rule, label it `runtime: advisory`.
+A prose-contract test alone leaves a rule `runtime: advisory`.
+Propose fixes through a small-change intent and [axstack-implement](../axstack-implement/SKILL.md).
+
+The `## Enforced rules` table in the target repo's AGENTS.md changes only in the PR that adds its check.
+The first row's PR adds a test that fails when any row's enforcement path disappears.
+If a `shipped` check missed a later recorded recurrence, report `enforcement failed`.
+For that failure, propose relabelling the row `runtime: advisory` in a separately reviewed PR.

package/skills/axstack-debug/SKILL.md

@@ -22,6 +22,8 @@ read it before phase 7 and before any fan-out.
 Redact secrets before showing any command, output, or artifact; build loops
 against environment variables so credentials never appear in what is shown.
 
+For performance claims only, load [Performance checklist](../axstack/references/performance-checklist.md).
+
 ## Phases
 
 Each phase has an observable completion criterion. Skip one only with a

package/skills/axstack-implement/SKILL.md

@@ -230,6 +230,11 @@ For each PR:
    to step 1.
    Merge-ready also requires a current diligence `PASS` at that head; diligence
    `FINDINGS` return to the same author within the review round.
+   Diligence `UNKNOWN` records the PR as `held` with the reason in the run record
+   and blocks merge-ready pending the driver's recorded disposition.
+   Before merge-ready, treat a run-record `Learning` that contradicts a shipped
+   rule as a finding on the owning PR and hold merge-ready until the contradiction is resolved.
+   An unrelated run-record `Learning` leaves merge-ready eligibility unchanged.
    A round with reviewer `REQUEST_CHANGES` and/or diligence `FINDINGS` increments
    `repairs` once and counts once toward the third-round hold.
 

package/skills/axstack-improve/SKILL.md

@@ -27,6 +27,8 @@ Sol pair that fails to launch is fenced, recorded `absent (<reason>)`, and
 named once in the next read-back, then skipped without relay or substitution.
 In mixed fan-out retain a Codex and a Claude seat or hold the affected work.
 
+For performance claims only, load [Performance checklist](../axstack/references/performance-checklist.md).
+
 ## 1. Bound discovery
 
 1. Start with the user's named subsystem or pain. Otherwise inspect recent

package/skills/axstack-review/SKILL.md

@@ -33,6 +33,8 @@ When the caller is a bounded review-manager PR job, load
 carry the required escalation field and every eligible peer PR takes a binding
 `APPROVE` or `REQUEST_CHANGES` verdict under the automation exception below.
 
+For performance claims only, load [Performance checklist](../axstack/references/performance-checklist.md).
+
 ## Codebase findings mode
 
 Use this manual mode for existing code at a pinned exact source revision and a

package/skills/axstack-spec/SKILL.md

@@ -62,6 +62,12 @@ and the lifecycle's [audit skill](../axstack-audit/SKILL.md) hook.
    session to return plain AGREE. Present one
    reviewable, identified revision for this checkpoint. Its user approval
    creates the execution baseline.
+   Name the draft revision covered by each adviser receipt at the checkpoint.
+   If draft text changed and an adviser receipt covers an older revision, hold
+   approval until fresh receipts cover the presented revision.
+   Except for high-stakes decisions, a change confined to a `Decisions` row
+   reuses adviser receipts only while draft text, evidence, scope, and question
+   remain unchanged.
    Before user approval, dispatch `axstack-diligence` under
    [Diligence](../axstack/references/diligence.md) to check the draft against
    the Align decisions for anything dropped, added, or softened.