axstack 0.22.0 → 0.24.0

package/README.md

@@ -23,11 +23,15 @@ 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. |
 | Understand | [axstack-research](skills/axstack-research/SKILL.md) | Answer one bounded question with sources. |
 | Understand | [axstack-explain](skills/axstack-explain/SKILL.md) | Explain a system and separate known behavior from gaps. |
+| Understand | [axstack-diagram](skills/axstack-diagram/SKILL.md) | Draw Mermaid diagrams or verified interactive archify viewers. |
+
+Interactive viewers use [archify](https://github.com/tt-a1i/archify) (MIT).
 
 Small, bounded changes can begin with your request or an existing issue;
 substantial work needs an approved spec and matching tickets before

package/bin/axstack.js

@@ -13,7 +13,7 @@ import {
   uninstallBundle,
   validateBundle,
 } from '../src/installer.js';
-import { BUN_FLOOR, checkCapabilities, meetsFloor, runRealCheck } from '../src/capabilities.js';
+import { BUN_FLOOR, checkArchify, checkCapabilities, meetsFloor, runRealCheck } from '../src/capabilities.js';
 import { findLegacyRoutingLines } from '../src/instructions.js';
 import { harnessLocations } from '../src/locations.js';
 
@@ -43,7 +43,7 @@ function packageVersion() {
 const HELP = `axstack — Axstack setup CLI (installation bookkeeping only)
 
 Usage:
-  axstack install --preset <mixed|codex-only|claude-only> --bundle <dir> --skills-dir <dir> [--instructions <file>] [--claude-settings <file>|--no-claude-settings] [--harness <name>] [--force] [--yes]
+  axstack install --preset <mixed|codex-only|claude-only> --bundle <dir> --skills-dir <dir> [--tools-dir <dir>] [--instructions <file>] [--claude-settings <file>|--no-claude-settings] [--harness <name>] [--force] [--yes]
   axstack check [--bundle <dir>] [--instructions <file>] [--skills-dir <dir>|--harness <name>]
   axstack uninstall --skills-dir <dir> [--instructions <file>] [--claude-settings <file>|--no-claude-settings] [--harness <name>] [--force] [--yes]
   axstack --help | --version
@@ -62,6 +62,8 @@ Flags:
                       Aliases: codex = codex-only; claude = claude-only.
   --skills-dir <dir>  Explicit install target. Overrides harness skill defaults
                       and automatic legacy Codex skill retirement.
+  --tools-dir <dir>   Pinned archify copies. Defaults to ~/.axstack/tools.
+                      Must be outside skills roots and contain no symlink path.
   --instructions <file>
                       Instruction file to receive the owned routing block.
                       Harness defaults: ~/.claude/CLAUDE.md for Claude,
@@ -105,7 +107,7 @@ function parseArgs(argv) {
   }
   out.command = rest.shift();
   const wantsValue = new Set([
-    '--bundle', '--skills-dir', '--instructions', '--harness', '--preset', '--claude-settings',
+    '--bundle', '--skills-dir', '--tools-dir', '--instructions', '--harness', '--preset', '--claude-settings',
   ]);
   while (rest.length > 0) {
     const tok = rest.shift();
@@ -300,6 +302,7 @@ async function main() {
         bundleDir: flags.bundle ? resolve(flags.bundle) : PACKAGE_ROOT,
         skillsDir,
         preset: flags.preset,
+        toolsDir: flags['tools-dir'] ? expandHome(flags['tools-dir']) : undefined,
         instructionsPath,
         inheritedInstructions: legacyCodexManifest?.instructions,
         force: !!flags.force,
@@ -399,6 +402,18 @@ async function main() {
     }
     if (command === 'check') {
       const report = await checkCapabilities(runRealCheck);
+      const toolSkillsDir = flags['skills-dir'] ? expandHome(flags['skills-dir']) :
+        flags.harness ? resolveHarnessTarget(flags.harness) : null;
+      if (toolSkillsDir) {
+        const tool = await checkArchify(toolSkillsDir);
+        console.log(`archify record: ${tool.recordFile}`);
+        if (tool.record) console.log(`archify copy: ${tool.record.path}; recorded SHA: ${tool.record.sha}; checked-out SHA: ${tool.actual ?? 'unavailable'}`);
+        if (tool.reason) {
+          console.log(`archify: ${tool.reason}`);
+          report.gaps.push(`archify: ${tool.reason}`);
+        }
+        console.log(tool.chrome ? `Chrome: ${tool.chrome}` : 'WARN Chrome: unavailable (viewer verification needs Chrome)');
+      }
       if (flags.bundle) {
         const bundle = await validateBundle(resolve(flags.bundle));
         const presetNames = Object.keys(bundle.presets);

package/docs/installation.md

@@ -8,8 +8,10 @@ workflow database.
 Requirements: Bun >=1.3.14, Git, `gh`, the `gh stack` extension, and a running
 T3 Code `0.0.46-nightly.20261003.2610` or newer. The driver is a T3 thread
 with the `t3-code` MCP. See the [T3 runtime boundary](../skills/axstack/references/t3-runtime.md).
-There are no runtime dependencies. Filesystem access uses Bun-backed `node:fs`
-and `node:fs/promises`; no other Node runtime contract is introduced.
+Axstack has no runtime package dependencies. Filesystem access uses Bun-backed
+`node:fs` and `node:fs/promises`. The pinned archify tool is the sole external-tool
+exception: installation uses Git and the network, and Bun runs its Node-oriented
+code. This exception introduces no Node.js runtime requirement.
 
 ## T3 setup
 
@@ -45,7 +47,7 @@ and its configured home channel under recorded notification authority.
 ### 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]
+axstack install --preset <mixed|codex-only|claude-only> --bundle <dir> --skills-dir <dir> [--tools-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
@@ -56,6 +58,9 @@ axstack install --preset <mixed|codex-only|claude-only> --bundle <dir> --skills-
 - `--skills-dir` is required unless a verified harness default resolves it.
   Codex defaults to the shared `~/.agents/skills` root; an explicit override
   remains authoritative and disables automatic legacy Codex-root retirement.
+- `--tools-dir` defaults to `~/.axstack/tools`. It must not overlap a skills
+  root or pass through a symlink. Home writes require `--yes`, including the
+  default tools directory.
 - `--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`;
@@ -90,6 +95,16 @@ the settings sidecar preserves the value while any other install still owns it.
 - `--yes` confirms writes under the user's home directory. Tests use temporary
   homes and fixtures only.
 
+Installation sparse-clones archify at the reviewed full SHA in `src/archify-pin.js`
+into `<tools-dir>/archify-<sha>`. It verifies HEAD before use and keeps the
+payload's licence and third-party notices. The manifest owns
+`<skills-dir>/axstack-diagram/archify.json`, which records `{path, sha}`.
+The adjacent `<tools-dir>/archify-<sha>.owners.json` lists its skills-root owners.
+Multiple roots share one copy. Repeat installs leave unchanged files untouched.
+An offline, Git-less, or failed clone still installs the skills, reports
+`archify: unavailable (<reason>)`, and exits 0. An existing SHA mismatch fails.
+Tests use a local repository through `AXSTACK_ARCHIFY_REPO` and never use the network.
+
 ## Role presets
 
 The selected bundle input is one of:
@@ -121,6 +136,13 @@ owned, missing, unowned, edited, or bound to a different path. Hand-written
 legacy routing outside the owned block is reported for manual migration and
 preserved byte for byte.
 
+With `--skills-dir` or `--harness`, check reports the archify record path, copy
+path, recorded SHA, and checked-out SHA. A missing record, missing copy, or SHA
+mismatch fails the check. Chrome absence prints a warning and does not fail it.
+`ARCHIFY_CHROME` selects the Chrome executable. Without it, check looks for
+common Chrome and Chromium executables on PATH. A check without a skills target
+probes host capabilities only.
+
 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.
@@ -135,6 +157,15 @@ 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.
 
+Uninstall drops that skills root from archify's owners file. It removes the copy
+only when no owners remain, HEAD matches the recorded SHA, and
+`git status --porcelain --ignored` is empty. Otherwise it keeps the copy and
+reports why, even with `--force`. A pin bump or a changed `--tools-dir` releases
+the old copy through the same guard. Installation clones into a temporary sibling
+and renames it into place. A later owner or manifest write failure restores
+ownership and removes only a copy created by that installation. Older manifests
+without an archify record still load.
+
 ## Owned instruction block
 
 The deterministic `<!-- axstack:begin v1 -->` / `<!-- axstack:end -->` block
@@ -323,8 +354,8 @@ 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 install --preset mixed --bundle ./bundle --skills-dir /tmp/ax-skills --tools-dir /tmp/ax-tools --instructions /tmp/AGENTS.md
+axstack install --preset mixed --bundle ./bundle --skills-dir /tmp/ax-skills --tools-dir /tmp/ax-tools --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
 ```

package/docs/workflows.md

@@ -18,8 +18,15 @@ 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-diagram](../skills/axstack-diagram/SKILL.md) selects Mermaid for chat,
+  GitHub, and docs, or an interactive viewer for required complex visuals.
+  Explain loads it for every diagram. Viewers use
+  [archify](https://github.com/tt-a1i/archify) (MIT) with a pinned tool,
+  a passing finalize receipt, rendered QA, and node-and-edge source review.
 - `axstack-improve` returns a small ranked set of evidenced improvement
   candidates without editing code. Its test-audit lens marks every declaration
   in one owner boundary R/F/C/D, reports reviewed and eligible counts, and routes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "axstack",
-  "version": "0.22.0",
+  "version": "0.24.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/ui-verification.md

@@ -5,6 +5,12 @@ browser" step, goes through async `delegate_task` to `axstack-ui-verifier` from
 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.
+
+The sole author browser exception is archify `finalize` as a headless build gate.
+Keep finalize outputs only in the private evidence folder.
+Never replace the verifier's rendered pass with finalize.
+All other browser checks remain delegated to `axstack-ui-verifier`.
+
 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.

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-diagram/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: axstack-diagram
+description: When an explanation needs a diagram, use axstack-diagram to choose Mermaid or a pinned archify viewer with source fidelity and rendered QA.
+---
+
+# Diagram
+
+Usage: `/axstack-diagram <question + destination>` or load this skill from explain.
+Load [Standing contracts](../axstack/references/contracts.md) before acting.
+Follow [Fidelity](references/fidelity.md) for every format.
+
+Use archify HTML for an explicit viewer request or explain's complex-visual path.
+For the viewer, follow [Archify](references/archify.md).
+Otherwise use Mermaid for chat, GitHub, or docs.
+Include `accTitle` and `accDescr` in each Mermaid view.
+Never use theme init in Mermaid.
+Split large Mermaid diagrams into views.
+T3 chat renders the Mermaid fence once the reply settles.
+
+Explain owns evidence, claim labels, the word cap, dispatch, and delivery.
+Diagram owns format and visual rules.
+Never call explain.
+For direct use, keep fidelity and rendered QA.
+
+Ideas: [archify](https://github.com/tt-a1i/archify), [diagram-design](https://github.com/cathrynlavery/diagram-design), [visual-explainer](https://github.com/nicobailon/visual-explainer), [Matt Pocock](https://github.com/mattpocock/skills), and [poteto](https://github.com/poteto/how); guidance uses Axstack's own words.

package/skills/axstack-diagram/references/archify.md

@@ -0,0 +1,76 @@
+# Archify
+
+Archify turns a typed JSON intermediate representation (IR) into an HTML viewer.
+Follow [Fidelity](fidelity.md) before authoring.
+
+## Bind the tool
+
+Read `archify.json` beside the skill entrypoint for its `{path, sha}` record.
+Verify that `git -C <path> rev-parse HEAD` equals the recorded SHA.
+If the record or copy is missing, HEAD mismatches the recorded SHA, or Chrome is missing, hold and ask the user.
+Honor `ARCHIFY_CHROME` when set.
+Otherwise find Chrome or Chromium on `PATH`.
+Set `ARCHIFY_UPDATE_CHECK_DISABLED=1` on every archify call.
+Never substitute Mermaid or unverified HTML when the viewer is required.
+
+## Author the IR
+
+If the pinned archify procedure conflicts with this file, this file takes precedence.
+Read `<path>/archify/SKILL.md` and follow its named references for IR authoring and repair.
+Run the referenced archify commands with Bun.
+
+Set `meta.title` and a portable relative HTML filename in `meta.output`.
+Use `meta.quality_profile: "showcase"`.
+Set `meta.animation: "none"`.
+Keep trace motion, exports, share cards, and brand marks off unless the user asks.
+Deliver the viewer with `?theme=dark` unless the user names a theme.
+Theme is viewer state rather than an IR field; without the query, localStorage and `prefers-color-scheme` determine it.
+Preserve explain's claim labels in `meta.subtitle` or the companion explanation.
+Set `meta.repository` to the inspected repository URL and full `revision`.
+Keep per-node source pins in each node's `sources` entries for inspected paths and line ranges.
+Keep the private source map for relationships that have no source field.
+Keep proposed sources distinct from factual pins.
+Use [Fidelity](fidelity.md) for visible planned and unknown markers.
+For a separate check, run `bun <path>/archify/bin/archify.mjs validate <type> <ir.json> --json --repo-root <repo>`.
+When sources are declared, require `--repo-root <repo>` on both `validate` and `finalize`.
+For sequence and dataflow, a schema-valid legend cue is `meta.legend.entries.dashed: {"label":"Planned or unknown"}`.
+
+Use one top-level `cards[]` entry with `{dot, title, items[]}` per key node as its node detail card.
+Each node detail card has at most 40 words and cites its source.
+Count the title plus all items toward each card's 40-word cap.
+Cite each card's source inline as `file:lines` in its `items[]`.
+Node detail cards are exempt from explain's 700-word cap.
+Count node labels, headings, captions, and all non-card text.
+
+## Build and hold
+
+Write the IR, HTML, and receipt only inside the private evidence folder.
+For direct invocation, create a private run evidence folder first.
+Override archify's default `.archify/` folder with an evidence output path and `--out-dir <evidence dir>`.
+Run `bun <path>/archify/bin/archify.mjs finalize <type> <ir.json> <out.html> --quality showcase --json --out-dir <evidence dir> --repo-root <repo>`.
+This is the author's headless build gate.
+Read the saved receipt named by the JSON result's `evidence.receipt`.
+Accept only receipt `status: "pass"` as success.
+Never trust exit codes as proof of a pass.
+When a receipt is missing or remains non-pass after two repair rounds, hold delivery and ask the user.
+If Chrome is missing, report "viewer not verified: Chrome missing".
+Chrome absence yields `status: "skipped"` and exit 2.
+Follow archify's receipt fixes and references for layout and composition repairs.
+After every repair edit, rerun the complete `finalize` command.
+Count one repair round as one complete `finalize` rerun after an edit.
+Validate runs never count as repair rounds.
+Do not require validate before finalize.
+Run at most two repair rounds, then hold with remaining defects for the user's decision.
+Never use archify's extra evidence-based retry.
+
+## Rendered and source checks
+
+Follow [UI verification](../../axstack/references/ui-verification.md) for dispatch.
+Keep `finalize` as the only author browser check.
+Delegate `visual-check`, browser opening, preview, and first-screen inspection to `axstack-ui-verifier`.
+Require `axstack-ui-verifier` checks of the receipt's `artifact.sha256` bytes on desktop, 390px mobile, keyboard, reduced motion, and the text alternative.
+Include theme, search or focus, and directional reach interactions.
+Require `axstack-ui-verifier` checks with the theme set explicitly.
+Require `explainer-review` of every node and edge against source for archify output.
+Every byte change requires fresh checks.
+Keep these independent verdicts with the build receipt before delivery.

package/skills/axstack-diagram/references/fidelity.md

@@ -0,0 +1,25 @@
+# Fidelity
+
+Map factual nodes and edges to an inspected source path at a recorded full revision.
+Drop unsupported factual elements.
+For uncommitted sources, use the content hash and mark their pins unknown.
+Keep the source map outside the reader view.
+Display the short SHA.
+
+Give planned and unknown nodes a visible marker in the node label and their card, if any.
+Use the literal marker `planned` or `unknown` for all five types.
+Give planned and unknown edges a visible `planned` or `unknown` marker in the edge label.
+For dashed styling, use only properties the pinned schema accepts and verify with `validate`.
+This is an extra cue, such as a dashed relationship where supported.
+The pinned node collections reject `variant`.
+Add a planned or unknown legend entry only for sequence and dataflow.
+Architecture, workflow, and lifecycle reject a `dashed` legend entry.
+In Mermaid, use the same visible markers and a dashed cue where its syntax permits.
+
+Treat about 9 core nodes as a signal to split.
+This is a design signal rather than a hard gate.
+Use 1–2 accent nodes.
+Keep labels short and name each relationship's direction and meaning.
+Provide a text alternative that describes nodes and edges.
+Never load network assets in the HTML.
+Write diagrams into repo docs only when the user asks.

package/skills/axstack-explain/SKILL.md

@@ -51,6 +51,10 @@ immediately before an actual profile dispatch.
 
 ## 2. Choose proportional output
 
+Load [Diagram](../axstack-diagram/SKILL.md) for every diagram.
+Explain owns evidence gathering, claim labels, the 700-word cap, dispatch, and delivery.
+Diagram never calls explain.
+
 1. Keep the primary reader-facing explanation to a maximum of 700 words in
    chat, HTML, and every other requested format. Preserve in that primary view
    the answer or purpose, key rationale, meaningful alternatives, main data or
@@ -63,11 +67,17 @@ immediately before an actual profile dispatch.
    maximum. If the draft is longer, compress repetition first and move only
    supporting detail to a separate linked ticket or appendix. Essential answers
    must not be hidden behind links, and evidence must not be silently discarded.
+   Only archify node detail cards are exempt from the 700-word cap.
+   Each card has at most 40 words and cites its source, as defined in
+   [Archify](../axstack-diagram/references/archify.md).
+   Count node labels, headings, captions, and all non-card text.
 2. For a simple request, answer concisely in the current chat. Use a compact
    diagram when useful. This needs no mandatory agent or intermediate artifact.
+   For simple chat answers, never dispatch an agent when applying its Mermaid rules inline.
 3. For a complex visual, use the configured `axstack-explainer` role to create
-   self-contained HTML, or use the requested artifact format. An explicit user
-   theme wins; otherwise use the dark default.
+   self-contained HTML through the archify path by default.
+   For a complex visual, honor an explicitly requested artifact format.
+   An explicit user theme wins; otherwise use the dark default.
 4. Profile IDs are presets, not availability proof. Before dispatch, follow the
    launch sequence and preserve the configured model, mode, and effort. Report
    an unavailable route; never substitute a model.
@@ -77,8 +87,9 @@ immediately before an actual profile dispatch.
 1. Any HTML explanation requires the full [visual QA
    checklist](references/visual-qa.md): actual desktop and mobile rendering,
    interaction, accessibility, and reduced-motion checks where relevant.
-2. Use the configured independent `axstack-explainer-review` role when
-   warranted, bound to the exact artifact identity. Any byte change invalidates
+2. For archify output, require the configured independent `axstack-explainer-review`;
+   for other artifacts, use it when warranted. Bind it to the exact artifact identity.
+   Any byte change invalidates
    that review and requires a fresh check. In `claude-only`, separate Sonnet
    author xhigh and reviewer high sessions are allowed for explanations as
    session independence only. This exception never permits same-model code

package/skills/axstack-explain/references/visual-qa.md

@@ -7,6 +7,8 @@ Browser and visual checks must run in the delegated `axstack-ui-verifier` in its
 
 1. Identify the final artifact bytes and theme. The explicit user theme wins;
    otherwise use the dark default.
+   For archify output, bind the `axstack-ui-verifier` pass to the finalize receipt's `artifact.sha256`.
+   For archify output, bind `axstack-explainer-review` to the same finalize receipt's `artifact.sha256`.
 2. Delegate the rendered pass through [UI verification](../../axstack/references/ui-verification.md).
    Record actual desktop and mobile observations, or name the missing layout
    check.
@@ -16,5 +18,6 @@ Browser and visual checks must run in the delegated `axstack-ui-verifier` in its
 4. The explainer reviewer checks text and source fidelity. Keep source
    correctness, tests, rendered behavior, independent review, and publication
    evidence separate.
+   For archify output, require `axstack-explainer-review` of every node and edge against source.
 5. Bind review to the exact artifact identity. Any byte change invalidates the
    affected approval and requires fresh QA and review.

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.

package/src/archify-pin.js

@@ -0,0 +1,5 @@
+// Pin changes require a reviewed chore PR and an upstream smoke run.
+export const ARCHIFY_PIN = Object.freeze({
+  repo: 'https://github.com/tt-a1i/archify',
+  sha: '594f6087358610bd16e64e5602976020871b6bff',
+});

package/src/archify.js

@@ -0,0 +1,149 @@
+import { lstat, mkdir, mkdtemp, readFile, rename, rm } from 'node:fs/promises';
+import { join } from './posixpath.js';
+import { ARCHIFY_PIN } from './archify-pin.js';
+
+export const ARCHIFY_RECORD = 'axstack-diagram/archify.json';
+
+export function archifyGit(path, ...args) {
+  try {
+    const result = Bun.spawnSync(['git', ...(path ? ['-C', path] : []), ...args], {
+      stdout: 'pipe', stderr: 'pipe', timeout: 60000,
+      env: { ...Bun.env, GIT_TERMINAL_PROMPT: '0' },
+    });
+    if (result.exitCode !== 0) throw new Error(result.stderr.toString().trim() || `git exit ${result.exitCode}`);
+    return result.stdout.toString().trim();
+  } catch (err) {
+    throw new Error(`git: ${err.message}`);
+  }
+}
+
+function verifySha(record, actual) {
+  if (actual === record.sha) return;
+  const error = new Error(`archify SHA mismatch: expected ${record.sha}, got ${actual}`);
+  error.code = 'ARCHIFY_SHA_MISMATCH';
+  throw error;
+}
+
+async function ownersSnapshot(path) {
+  const st = await lstat(path).catch((err) => {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  });
+  if (st && (!st.isFile() || st.isSymbolicLink())) throw new Error(`unsafe archify owners file: ${path}`);
+  const bytes = st ? await readFile(path) : null;
+  const owners = bytes ? JSON.parse(bytes) : [];
+  if (!Array.isArray(owners) || owners.some((owner) => typeof owner !== 'string' || !owner.startsWith('/'))) {
+    throw new Error(`invalid archify owners file: ${path}`);
+  }
+  return { bytes, owners, mode: st ? st.mode & 0o777 : null };
+}
+
+// Drop ownership transactionally; defer destructive cleanup until the skills
+// manifest commits. A failed manifest write can then restore the owner list.
+export async function planArchifyRelease({ record, skillsRoot, writeAtomic, log }) {
+  const ownersFile = `${record.path}.owners.json`;
+  const before = await ownersSnapshot(ownersFile);
+  const remaining = before.owners.filter((owner) => owner !== skillsRoot);
+  if (!before.owners.includes(skillsRoot)) {
+    return { rollback: async () => {}, finish: async () => log(`archify: kept ${record.path} (owner is absent)`) };
+  }
+  try {
+    await writeAtomic(ownersFile, JSON.stringify(remaining) + '\n', { mode: 0o600 });
+  } catch (err) {
+    const current = await readFile(ownersFile);
+    if (!current.equals(before.bytes)) {
+      try { await writeAtomic(ownersFile, before.bytes, { mode: before.mode }); }
+      catch (restoreErr) { err.message += ` (archify owner restore failed: ${restoreErr.message})`; }
+    }
+    throw err;
+  }
+  return {
+    rollback: () => writeAtomic(ownersFile, before.bytes, { mode: before.mode }),
+    finish: async () => {
+      try {
+        if (remaining.length) throw new Error('other skills roots still own this copy');
+        const st = await lstat(record.path);
+        if (!st.isDirectory() || st.isSymbolicLink()) throw new Error('copy is not a real directory');
+        if (archifyGit(record.path, 'rev-parse', 'HEAD') !== record.sha) throw new Error('HEAD differs from the recorded SHA');
+        if (archifyGit(record.path, 'status', '--porcelain', '--ignored')) throw new Error('copy has tracked, untracked, or ignored changes');
+        await rm(record.path, { recursive: true });
+        await rm(ownersFile);
+        log(`archify: removed ${record.path}`);
+      } catch (err) {
+        log(`archify: kept ${record.path} (${err.message})`);
+      }
+    },
+  };
+}
+
+// The caller includes this transaction in the skills/manifest rollback.
+export async function provisionArchify({ toolsRoot, skillsRoot, writeAtomic, log }) {
+  if (!Bun.which('git')) {
+    log('archify: unavailable (git is not on PATH)');
+    return { record: null, rollback: async () => {} };
+  }
+  const record = { path: join(toolsRoot, `archify-${ARCHIFY_PIN.sha}`), sha: ARCHIFY_PIN.sha };
+  const ownersFile = `${record.path}.owners.json`;
+  const before = await ownersSnapshot(ownersFile);
+  let created = false;
+  let ownersWritten = false;
+  const rollback = async () => {
+    const errors = [];
+    if (ownersWritten) {
+      try {
+        if (before.bytes === null) await rm(ownersFile);
+        else await writeAtomic(ownersFile, before.bytes, { mode: before.mode });
+      } catch (err) { errors.push(`${ownersFile}: ${err.message}`); }
+    }
+    if (created) {
+      try { await rm(record.path, { recursive: true }); }
+      catch (err) { errors.push(`${record.path}: ${err.message}`); }
+    }
+    if (errors.length) throw new Error(`incomplete archify rollback: ${errors.join('; ')}`);
+  };
+  const existing = await lstat(record.path).catch((err) => {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  });
+  if (existing && (!existing.isDirectory() || existing.isSymbolicLink())) {
+    throw new Error(`unsafe archify copy: ${record.path}`);
+  }
+  if (existing) {
+    const actual = archifyGit(record.path, 'rev-parse', 'HEAD');
+    verifySha(record, actual);
+  } else {
+    let temp = null;
+    try {
+      await mkdir(toolsRoot, { recursive: true });
+      temp = await mkdtemp(join(toolsRoot, '.archify-'));
+      archifyGit(null, 'clone', '--filter=blob:none', '--no-checkout', '--', Bun.env.AXSTACK_ARCHIFY_REPO || ARCHIFY_PIN.repo, temp);
+      archifyGit(temp, 'sparse-checkout', 'set', '--no-cone', '/archify/');
+      archifyGit(temp, 'checkout', '--detach', record.sha);
+      const actual = archifyGit(temp, 'rev-parse', 'HEAD');
+      verifySha(record, actual);
+      await rename(temp, record.path);
+      temp = null;
+      created = true;
+    } catch (err) {
+      if (err.code === 'ARCHIFY_SHA_MISMATCH') throw err;
+      log(`archify: unavailable (${err.message.replace(/\s+/g, ' ').slice(0, 180)})`);
+      return { record: null, rollback: async () => {} };
+    } finally {
+      if (temp) await rm(temp, { recursive: true });
+    }
+  }
+  try {
+    if (!before.owners.includes(skillsRoot)) {
+      ownersWritten = true;
+      await writeAtomic(ownersFile, JSON.stringify([...before.owners, skillsRoot].sort()) + '\n', { mode: 0o600 });
+    }
+  } catch (err) {
+    const current = await readFile(ownersFile).catch(() => null);
+    ownersWritten = before.bytes === null ? current !== null : current?.equals(before.bytes) !== true;
+    try { await rollback(); }
+    catch (restoreErr) { err.message += ` (${restoreErr.message})`; }
+    throw err;
+  }
+  log(`archify: ${record.path} (${record.sha})`);
+  return { record, rollback };
+}

package/src/capabilities.js

@@ -1,4 +1,8 @@
 // Host capability checks. Injected execution keeps tests off live runtimes.
+import { lstat, readFile } from 'node:fs/promises';
+import { join } from './posixpath.js';
+import { ARCHIFY_RECORD, archifyGit } from './archify.js';
+import { ARCHIFY_PIN } from './archify-pin.js';
 export const BUN_FLOOR = '1.3.14';
 export const T3_FLOOR = '0.0.46-nightly.20261003.2610';
 
@@ -106,3 +110,29 @@ export async function checkCapabilities(exec) {
   const gaps = checks.filter((c) => !c.ok).map((c) => `missing ${c.label}`);
   return { checks, gaps, limitations: [...PROBE_LIMITATIONS] };
 }
+
+export async function checkArchify(skillsDir) {
+  const recordFile = join(skillsDir, ARCHIFY_RECORD);
+  const override = Bun.env.ARCHIFY_CHROME;
+  const chrome = override ? Bun.which(override) :
+    ['google-chrome', 'google-chrome-stable', 'chromium', 'chromium-browser', 'chrome']
+      .map((name) => Bun.which(name)).find(Boolean);
+  let record = null;
+  let actual = null;
+  let reason = null;
+  try {
+    if ((await lstat(recordFile)).isSymbolicLink()) throw new Error('record is a symlink');
+    record = JSON.parse(await readFile(recordFile, 'utf8'));
+    if (!record || typeof record.path !== 'string' || !record.path.startsWith('/') ||
+        !/^[a-f0-9]{40}$/.test(record.sha)) throw new Error('invalid record');
+    const copy = await lstat(record.path);
+    if (!copy.isDirectory() || copy.isSymbolicLink()) throw new Error('copy is not a real directory');
+    actual = archifyGit(record.path, 'rev-parse', 'HEAD');
+    if (actual !== record.sha || record.sha !== ARCHIFY_PIN.sha) {
+      throw new Error(`SHA mismatch: recorded ${record.sha}, checked-out ${actual}, expected ${ARCHIFY_PIN.sha}`);
+    }
+  } catch (err) {
+    reason = err.code === 'ENOENT' ? 'missing record or copy' : err.message;
+  }
+  return { recordFile, record, actual, chrome: chrome ?? null, reason };
+}

package/src/installer.js

@@ -38,6 +38,7 @@ import {
   writeManifest,
 } from './manifest.js';
 import { planInstallClaudeSettings, planUninstallClaudeSettings } from './claude-settings.js';
+import { ARCHIFY_RECORD, planArchifyRelease, provisionArchify } from './archify.js';
 import {
   applyInstructionPlan,
   findLegacyRoutingLines,
@@ -205,6 +206,15 @@ export function assertOutsideHome(target, { yes = false, kind = 'target' } = {})
   }
 }
 
+async function guardArchifyRecord(record, skillsRoot, yes) {
+  if (!record) return;
+  await assertNoSymlinksBelow('/', record.path);
+  if (withinRoot(record.path, skillsRoot) || withinRoot(skillsRoot, dirname(record.path))) {
+    throw new Error('recorded archify tools directory overlaps the skills root; refusing');
+  }
+  assertOutsideHome(record.path, { yes, kind: 'archify copy' });
+}
+
 // Validate the bundle directory and return its payload. Throws before any
 // target mutation on any problem.
 export async function validateBundle(bundleDir, selectedPreset = null) {
@@ -461,6 +471,7 @@ export async function installBundle({
   bundleDir,
   skillsDir,
   preset,
+  toolsDir = null,
   instructionsPath = null,
   inheritedInstructions = null,
   force = false,
@@ -479,6 +490,14 @@ export async function installBundle({
     ? await canonicalInstructionFile(instructionsPath)
     : null;
   assertOutsideHome(skillsRoot, { yes, kind: 'skills directory' });
+  const toolsPath = toolsDir ?? (homeDir() ? join(homeDir(), '.axstack', 'tools') : null);
+  if (!toolsPath) throw new Error('HOME is unavailable; pass --tools-dir explicitly');
+  await assertNoSymlinksBelow('/', resolve(toolsPath));
+  const toolsRoot = await canonicalTargetDir(toolsPath);
+  if (withinRoot(toolsRoot, skillsRoot) || withinRoot(skillsRoot, toolsRoot)) {
+    throw new Error('tools directory overlaps the skills root; refusing');
+  }
+  assertOutsideHome(toolsRoot, { yes, kind: 'tools directory' });
   if (instructionsFile) assertOutsideHome(instructionsFile, { yes, kind: 'instruction file' });
   const claudePlan = await planInstallClaudeSettings({ claude, skillsRoot });
   if (claudePlan.report.path) {
@@ -503,6 +522,7 @@ export async function installBundle({
     );
   }
   const ownedFiles = prevManifest.files ?? {};
+  await guardArchifyRecord(prevManifest.archify, skillsRoot, yes);
   const legacyProfiles = prevManifest.profiles;
   const legacyProfileNote = Object.keys(legacyProfiles?.entries ?? {}).length > 0
     ? 'legacy Paseo profile provenance retained inert; see legacy cleanup guidance in docs/installation.md'
@@ -545,6 +565,11 @@ export async function installBundle({
   // manifest entry resolves its destination, current bytes, and pristine
   // flag through the same guard before Phase 2 mutates anything.
   const desired = [];
+  const archifyTarget = await readOwnedTarget(skillsRoot, ARCHIFY_RECORD);
+  if (archifyTarget.current !== null &&
+      hashContent(archifyTarget.current) !== ownedFiles[ARCHIFY_RECORD]) {
+    throw new Error('archify record is edited or unowned; refusing to replace it');
+  }
   for (const { rel, abs, content: inlineContent } of bundle.files) {
     const { dest, current, mode } = await readOwnedTarget(skillsRoot, rel);
     const content = inlineContent ?? await readFile(abs);
@@ -562,6 +587,7 @@ export async function installBundle({
   }
 
   const bundleRels = new Set(bundle.files.map((file) => file.rel));
+  bundleRels.add(ARCHIFY_RECORD);
   const stalePlan = [];
   for (const rel of Object.keys(ownedFiles)) {
     if (bundleRels.has(rel)) continue;
@@ -591,8 +617,23 @@ export async function installBundle({
   const installedHashes = {};
   const claudeWritten = [];
   let instructionWritten = false;
+  let archify = null;
+  let archifyRelease = null;
+  const manifestFile = join(skillsRoot, '.axstack-manifest.json');
+  const manifestBefore = await readFile(manifestFile).catch((err) => {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  });
+  const manifestMode = manifestBefore === null ? null : (await stat(manifestFile)).mode & 0o777;
+  let manifestAttempted = false;
   log('plan complete');
   try {
+    archify = await provisionArchify({ toolsRoot, skillsRoot, writeAtomic, log });
+    const archifyRecord = archify.record ?? prevManifest.archify ?? null;
+    if (archifyRecord) {
+      desired.push({ rel: ARCHIFY_RECORD, ...archifyTarget,
+        content: Buffer.from(JSON.stringify(archifyRecord, null, 2) + '\n') });
+    }
     if (instructionsFile) {
       await assertFileSnapshot(instructionsFile, existingInstructionsRaw);
     }
@@ -709,6 +750,12 @@ export async function installBundle({
       )
       : null;
 
+    if (prevManifest.archify && archifyRecord?.path !== prevManifest.archify.path) {
+      archifyRelease = await planArchifyRelease({
+        record: prevManifest.archify, skillsRoot, writeAtomic, log,
+      });
+    }
+    manifestAttempted = true;
     await writeManifest(skillsRoot, {
       version: MANIFEST_VERSION,
       files: installedHashes,
@@ -717,7 +764,9 @@ export async function installBundle({
         path: claudePlan.settingsPath ?? boundClaudeSettingsPath,
       },
       instructions: nextInstructions,
+      archify: archifyRecord,
     });
+    if (archifyRelease) await archifyRelease.finish();
     if (legacyProfileNote || legacyInstructionNote) {
       summary.notes = [
         ...(summary.notes ?? []),
@@ -751,6 +800,26 @@ export async function installBundle({
     // Restore failures are collected and reported: a swallowed restore would
     // leave ownership claims describing bytes that are not on disk.
     const rollbackErrors = [];
+    if (manifestAttempted) {
+      try {
+        const current = await readFile(manifestFile).catch((readErr) => {
+          if (readErr.code === 'ENOENT') return null;
+          throw readErr;
+        });
+        if (manifestBefore === null && current !== null) await rm(manifestFile);
+        else if (manifestBefore !== null && current?.equals(manifestBefore) !== true) {
+          await writeAtomic(manifestFile, manifestBefore, { mode: manifestMode });
+        }
+      } catch (restoreErr) { rollbackErrors.push(`manifest: ${restoreErr.message}`); }
+    }
+    if (archifyRelease) {
+      try { await archifyRelease.rollback(); }
+      catch (restoreErr) { rollbackErrors.push(`old archify owner: ${restoreErr.message}`); }
+    }
+    if (archify) {
+      try { await archify.rollback(); }
+      catch (restoreErr) { rollbackErrors.push(`archify: ${restoreErr.message}`); }
+    }
     for (const write of claudeWritten.reverse()) {
       try {
         if (write.before === null) await rm(write.path);
@@ -812,6 +881,7 @@ export async function uninstallBundle({
     instructions: { path: null, hash: null },
   };
   const boundClaudeSettingsPath = manifest.claudeSettings?.path ?? null;
+  await guardArchifyRecord(manifest.archify, skillsRoot, yes);
   const claudePlan = await planUninstallClaudeSettings({
     claude,
     skillsRoot,
@@ -920,6 +990,7 @@ export async function uninstallBundle({
   const deletedFiles = [];
   const claudeWritten = [];
   let instructionWritten = false;
+  let archifyRelease = null;
   try {
     for (const rel of uninstallPlan) {
       const { dest, current, mode } = await readOwnedTarget(skillsRoot, rel);
@@ -958,6 +1029,11 @@ export async function uninstallBundle({
     }
     summary.claudeSettings = claudePlan.report;
 
+    const remainingArchify = ARCHIFY_RECORD in remainingFiles ? manifest.archify : null;
+    if (manifest.archify && !remainingArchify) {
+      archifyRelease = await planArchifyRelease({ record: manifest.archify, skillsRoot, writeAtomic, log });
+    }
+
     if (
       Object.keys(remainingFiles).length === 0 &&
       !hasLegacyProfiles &&
@@ -975,11 +1051,17 @@ export async function uninstallBundle({
         profiles: legacyProfiles,
         claudeSettings: { path: remainingClaudeSettingsPath },
         instructions: remainingInstructions,
+        archify: remainingArchify,
       });
     }
+    if (archifyRelease) await archifyRelease.finish();
     return summary;
   } catch (err) {
     const rollbackErrors = [];
+    if (archifyRelease) {
+      try { await archifyRelease.rollback(); }
+      catch (restoreErr) { rollbackErrors.push(`archify owner: ${restoreErr.message}`); }
+    }
     for (const write of claudeWritten.reverse()) {
       try {
         if (write.before === null) await rm(write.path);

package/src/manifest.js

@@ -80,6 +80,13 @@ function normalizeManifest(parsed) {
     throw new Error('invalid ownership manifest: files must be an object of path hashes');
   }
   const rawClaudeSettings = parsed.claudeSettings ?? { path: null };
+  const archify = parsed.archify ?? null;
+  if (archify !== null && (typeof archify !== 'object' ||
+      typeof archify.path !== 'string' || !isAbsolute(archify.path) ||
+      !/^[a-f0-9]{40}$/.test(archify.sha) ||
+      !archify.path.endsWith(`/archify-${archify.sha}`))) {
+    throw new Error('invalid ownership manifest: archify must bind an absolute pinned copy');
+  }
   if (
     typeof rawClaudeSettings !== 'object' || rawClaudeSettings === null ||
     Array.isArray(rawClaudeSettings) ||
@@ -118,6 +125,7 @@ function normalizeManifest(parsed) {
       profiles: { path: null, preset: null, entries: { ...rawProfiles } },
       claudeSettings: { path: rawClaudeSettings.path },
       instructions,
+      ...(archify ? { archify } : {}),
     };
   }
   if (
@@ -137,6 +145,7 @@ function normalizeManifest(parsed) {
       },
       claudeSettings: { path: rawClaudeSettings.path },
       instructions,
+      ...(archify ? { archify } : {}),
     };
   }
   throw new Error('invalid ownership manifest: profiles must bind a config path to id hashes');