axstack 0.20.20 → 0.20.22

package/package.json

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

package/skills/axstack/references/design-lens.md

@@ -0,0 +1,81 @@
+# Design lens
+
+In Align, set the rung from researched facts, not a user choice. Carry the
+sketch through the scope identity.
+
+## Ladder
+
+- **Rung 0 — skip.** The change stays inside one module's existing interface,
+  ownership, data flow, and failure guarantees. Ask no design questions and
+  carry no sketch. “Might be small” is not a reason to skip.
+- **Rung 1 — design questions.** Any change that fails Rung 0. Typical triggers:
+  crossing a module boundary; adding a module, service, interface, or external
+  dependency; changing an interface or failure guarantee; changing data
+  ownership, schema, wire format, or persisted format. A design question does
+  not reclassify work: Rung 1 can stay small. An unsettled material design
+  question still makes routing reassess size.
+- **Rung 2 — arena.** A Rung 1 design that also meets the existing ADR test:
+  a meaningful, hard-to-reverse, non-obvious trade-off. Use Align's existing
+  arena for that question.
+
+There is no numeric threshold, file-count gate, or class-count gate.
+
+## Questions in order
+
+Ask only unresolved areas in numbered `Qn` rounds of one to three. Give each a
+recommendation, reason, and trade-off; use Align's adviser critique. Design and
+arena questions share its unchanged budget: 20 normally, a justified extension
+to 35, then opted-in refinement of at most five.
+
+1. **Scope:** What exists, the minimum change, and what is explicitly excluded?
+2. **Caller first:** Write realistic usage before drawing the shape.
+3. **Shape:** Which boundaries, module depth, ownership, invariants, seams,
+   and adapters serve that usage?
+4. **Flow and failure:** Trace the data flow. For each materially new path,
+   name one realistic production failure and its observable behavior.
+5. **Reversibility:** Name compatibility, migration, rejected alternatives, and
+   what we accept for what benefit.
+
+## Vocabulary and red flags
+
+A **deep module** hides substantial behavior behind a small interface. A
+**shallow module** exposes most of its machinery. Treat an **interface as test
+surface**: test caller behavior and observable failures. A **seam** permits a
+second implementation; one adapter is hypothetical, two make it real. Prefer
+**locality** and explicit **ownership** of state and invariants. The **deletion
+test** asks what contract would be lost if a layer vanished. Choose **boring by
+default** and **reversible over clever**.
+
+Red flags—shallow module, information leakage, temporal decomposition, and
+pass-through layers—are prompts for evidence, not automatic defects. Ask what
+crosses each boundary and whether a layer can be removed.
+
+## Sketch
+
+For Rung 1 or 2, put this block in the spec's `Design` section or the returned
+small-change intent. `Binding` names commitments; other lines may illustrate.
+
+```text
+Usage: <call site or command as the caller writes it>
+Shape: <signatures or a <=10-line ASCII/Mermaid diagram>
+Binding: <which lines are committed; the rest is illustrative>
+Flow + failure: <path -> one realistic failure -> observable behavior>
+We accept: <X> for <Y>
+Rejected: <alternative -> why>
+Open: <question?>
+```
+
+Keep settled choices in `Decisions` rows. `CONTEXT.md` stays a glossary; ADRs
+keep their existing test. Add no design document or phase.
+
+## Arena rubric candidates
+
+For each arena, the driver selects three to six and tailors the rubric criteria
+to the question. Score candidate designs on evidence, not a generic checklist:
+
+- Is `Usage` realistic and simple for the caller?
+- Are module boundaries deep enough and ownership unambiguous?
+- Is behavior local with a useful test surface?
+- Are materially new failure paths observable and recoverable?
+- Are compatibility, migration, and deletion costs explicit?
+- Does the trade-off justify complexity against rejected options?

package/skills/axstack/references/lifecycle.md

@@ -56,7 +56,7 @@ Only an explicit user request to transfer ownership enters this branch.
    prior owner seeing a different valid accepted owner stops.
 
 Complete record: goal, authority, intent, IDs, revisions, evidence, pending
-receipts/timers, unresolved decisions, next action, and transfer ownership/gap.
+receipts/timers, unresolved decisions, next action, and transfer status.
 
 ## Receipts (bind each decision to evidence)
 
@@ -87,8 +87,8 @@ covers only ordinary reading, writing, and local checks. Heartbeat deliveries
 are acknowledged with no user-facing text. Process each whole delivery before
 acknowledgment and validate its Task, Dispatch, sender, authority, revisions,
 and receipts before advancing the run record. Duplicate deliveries are
-deduplicated by runtime identity. Healthy unchanged observations produce no
-user-facing update. After accepting worker, Task, or Run completion, the driver
+deduplicated by runtime identity. Healthy unchanged passes are silent.
+After accepting worker, Task, or Run completion, the driver
 invokes [axstack-cleanup](../../axstack-cleanup/SKILL.md) inline; it never
 dispatches cleanup work.
 
@@ -99,8 +99,8 @@ session liveness, delivery, and verified advancement are distinct evidence.
 On `consumer_fenced`, reconcile the active coordinator rather than borrowing an
 identity. Respect settlement protection including `user_takeover`.
 
-No execution heartbeat or substitute scheduler is created by Axstack. Native
-review automation follows [Review automation health](#review-automation-health).
+Axstack creates no execution heartbeat or substitute scheduler. See
+[Review automation health](#review-automation-health).
 Tracking grants no merge, release, model-substitution, or scope authority.
 
 ## Deadline (one rule for every owned timer)
@@ -131,15 +131,16 @@ nothing without tested independent review.
 
 ## Close-out
 
-PRs merge by forge state—not branch ancestry; close out: (1) settle every worker
+PRs merge by forge state; close out: (1) settle every worker
 terminal; (2) compact record with counts and denominators—user
 interventions/deviations from plan/repairs; (3) `axstack-auditor`: settle
 non-zero/requested, else `counts zero`; an unavailable auditor leaves close-out
 pending, never skipped silently; (4) release merged run worktrees and branches;
-use `axstack-cleanup` and close selected external-tracker tickets when applicable;
+use `axstack-cleanup`, remove the run's own automations 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
-receipt or `counts zero`; release and ticket receipts; archive timestamp.
+receipt or `counts zero`; automation, release, and ticket receipts; archive timestamp.
 `active`/receipt-incomplete record: close-out pending, never done. One-step
 lookups exempt.

package/skills/axstack/references/routing.md

@@ -14,10 +14,10 @@ tools, credentials, quota, subscription, or default to `mixed`.
 
 At run start, snapshot all 24 role IDs with provider/model/mode/effort; absent
 or unconfigured roles are recorded explicitly; invent no provider default.
-Such a role holds only that role's work, not the run. A role installed or changed later
-must not silently enter the snapshot; adding it needs an explicit user
-decision. Live profiles are authoritative at snapshot time and for availability;
-bundled presets are setup inputs, not runtime proof.
+Such a role holds only that role's work. A role installed or changed later must not
+silently enter the snapshot; adding it needs an explicit user decision. Live profiles
+are authoritative at snapshot time and for availability; bundled presets are setup
+inputs, not runtime proof.
 
 Preset changes apply to new runs only; an active run keeps its snapshot.
 Changing it or replacing a session needs an explicit user decision and
@@ -102,13 +102,13 @@ reason in the run record, or in the brief for tiny direct work.
 - **Small:** clear, bounded one-PR work. The driver captures the named
   **small-change intent** from the current request or user-chosen existing
   issue plus explicit acceptance checks and exclusions, snapshots it once, and
-  proceeds. No earlier snapshot, spec, ticket ceremony, or second approval is
-  required; do not route to `axstack-align` solely because that snapshot is
-  not yet written. Strict TDD, mode-specific review, model, risk, and human-merge
+  proceeds. No prior snapshot, spec, tickets, or second approval is required; do not route
+  to `axstack-align` solely because the snapshot is not yet written. Strict TDD,
+  mode-specific review, model, risk, and human-merge
   contracts still apply.
-- **Unclear:** clarify the uncertainty through `axstack-align` or one bounded
-  question, then classify it as small or substantial; a small ambiguity does
-  not force substantial-work paperwork.
+- **Unclear:** clarify via `axstack-align` or a bounded question, then
+  classify small or substantial; it does not force substantial-work paperwork.
+  [Design lens](design-lens.md) Rung 1 is Unclear; use `axstack-align`.
 
 Reassess size when growth adds an additional PR, a new execution dependency
 that materially expands scope, an unsettled material design question, or a

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

@@ -33,8 +33,8 @@ and Dispatch decides; parent/child display lineage does not. The creator closes
 what it created at ordinary settlement; the cross-run sweep below may retire
 its settled leftovers. A finite scheduled pass closes only its own exact terminal as
 its final action. Manual chats, automation dedicated workspaces, and genuine
-`user_takeover` sessions are never removed. Deleting a session means closing
-its terminal; agent chat history is not deleted.
+`user_takeover` sessions are never removed by ordinary settlement or sweep.
+Deleting a session means closing its terminal; agent chat history is not deleted.
 
 If native exact terminal close returns `runtime_error` for a provably finished
 agent, send `/quit` + Enter to that exact terminal, wait about 5 seconds, then
@@ -45,6 +45,30 @@ leaves its terminal for the next pass, without treating that expected failure
 as a hold. At pass start, clear only provably finished predecessor terminals
 of the same automation in its dedicated workspace by this exact-handle path.
 
+## Owned automation retirement
+
+At Close-out, reconcile the run record with native inventory: the recorded
+owning Run must have created the exact automation IDs selected for retirement.
+The sweeping pass uses that recorded owning Run, not its own Run, for cross-run
+watches. A cross-run sweep may retire a disabled per-run watch only when its
+owning run is closed or every watched PR is merged or closed. Uncertain recorded
+ownership, watch state, or disable result holds the affected automation.
+
+For each eligible automation, disable it and verify native readback before
+`orca automations remove <id>` on its exact ID, and verify absence by native
+readback. The observer only disables and reports; the driver removes its own
+run's automation. Only a retired owned per-run watch's workspace may be removed
+under these guards. Never remove the durable review manager and its dedicated
+workspace or a user-created automation and its dedicated workspace.
+
+Remove that dedicated workspace only after confirming its exact ownership, no
+live terminal, a clean worktree, and a head on the remote. Recheck ownership and
+liveness immediately before workspace removal. If dirty or unpublished, use the
+salvage and bundle verification below before removal; failed verification or
+uncertain liveness is a hold. The current scheduled pass cannot remove its own
+workspace while its terminal is live; the driver or a later sweep finishes that
+step. Record separate automation and workspace receipts.
+
 ## Preserve before removal
 
 Workers write reports, probes, logs, evidence, and scratch to the private

package/skills/axstack-align/SKILL.md

@@ -17,6 +17,17 @@ Load before acting:
 
 This preserves the required contracts -> lifecycle -> audit load edge.
 
+## Design the shape
+
+Set the rung from researched facts; never ask the user to choose it. A change
+inside one module's existing interface, ownership, data flow, and failure
+guarantees is Rung 0: no design questions or sketch. Otherwise load the
+[design lens ladder](../axstack/references/design-lens.md) for Rung 1 or 2
+and settle only unresolved areas in its order within the existing budget. Carry a
+Rung 1 or 2 sketch in the substantial spec's `Design` section or the returned
+small-change intent. A design question alone does not make small work
+substantial; apply routing's existing size reassessment rule.
+
 ## Settle the frontier
 
 1. **Research and map dependencies.** Inspect the available code, docs, and

package/skills/axstack-implement/SKILL.md

@@ -84,8 +84,17 @@ Size alone never requires user approval.
 Use the normal behavior path unless the accepted improvement scope is
 explicitly marked **structure-preserving**. The author never chooses that tag.
 
+Only when the scope identity carries a sketch, copy it into the author brief
+under the [design lens](../axstack/references/design-lens.md).
+
 ### Normal behavior path
 
+When that sketch exists, make the first red check target its `Usage` line.
+The structure-preserving path stays as is.
+If a repeated workaround or unnamed boundary conflicts with the sketch, the
+author stops and returns a sketch conflict. The driver reopens only the
+affected decision through Align under the existing material-revision rule.
+
 Choose a behavior from the accepted scope, including its failure behavior or a
 real integration boundary. Test it through an observable interface rather than
 restating source text or mirroring the intended implementation. Execute the

package/skills/axstack-improve/SKILL.md

@@ -42,7 +42,9 @@ specialization materially helps; create no new profile.
 Produce a small ranked candidate set. For each candidate include:
 
 1. Source evidence and the scoped problem.
-2. Current and proposed shape.
+2. Current and proposed shape. Only when the scope identity carries a sketch,
+   use the [design lens](../axstack/references/design-lens.md) vocabulary and
+   red flags and return candidates in sketch form.
 3. Concrete benefit and tradeoffs.
 4. Behavior to preserve and test approach.
 5. Uncertainty and recommendation strength.

package/skills/axstack-review/SKILL.md

@@ -243,7 +243,10 @@ This section applies to peer and authored PR modes.
       is safe because of on the evidence ladder; below "ran it" is unproven.
    4. Requirements, acceptance, and user behavior.
    5. Architecture and solution design, including SOLID and credible simpler
-      alternatives.
+      alternatives. Only when the scope identity carries a sketch, compare
+      the architecture with the [design lens](../axstack/references/design-lens.md)
+      sketch and red flags. A deviation from a `Binding` line without an
+      accepted spec revision is a finding.
    6. Simplicity and maintainability: KISS, YAGNI, and cyclomatic complexity
       where measurement is useful. Never invent a metric or demand an
       abstraction merely to satisfy a principle.

package/skills/axstack-spec/SKILL.md

@@ -35,7 +35,10 @@ and the lifecycle's [audit skill](../axstack-audit/SKILL.md) hook.
    Missing access preserves the GitHub selection and stops the phase without
    mutation or fallback. Markdown mode skips external access preflight.
 3. **Draft with decision evidence.** Write observable acceptance criteria
-   and explicit exclusions in the selected store. First record the driver's
+   and explicit exclusions in the selected store. Only when the scope identity
+   carries a sketch, include the [design lens](../axstack/references/design-lens.md)
+   sketch in the approved revision's `Design` section and its `Usage` line in
+   acceptance. First record the driver's
    independent assessment, then load
    [Orca runtime](../axstack/references/orca-runtime.md) before dispatching the
    configured `axstack-advisor-astra` and `axstack-advisor-fable` independently,

package/skills/axstack-tickets/SKILL.md

@@ -41,8 +41,12 @@ an actual checker dispatch, not for ordinary mapping or state reconciliation.
    issues represent user-visible capabilities; one capability may span several
    tasks and PRs. GitHub capability issues link the approved spec issue and its
    SHA-256 body digest. Keep detailed execution breakdowns in the repository.
-   For every capability, derive acceptance checks from the pinned spec and
-   identify internal tasks, dependencies, PR ownership, and worktrees. For each task the driver records
+   For every capability, derive acceptance checks from the pinned spec. Only
+   when its scope identity carries a sketch, follow the
+   [design lens](../axstack/references/design-lens.md) sketch's modules, put
+   its named failure in capability acceptance, and treat a task spanning a
+   sketch boundary as a split signal. Identify internal tasks, dependencies,
+   PR ownership, and worktrees. For each task the driver records
    one theme and a coarse size estimate from the ownership, interface, and
    dependency map. A task estimated in the exception band is assessed for a
    split at mapping time and split where a green, atomic, reviewable split

package/skills/axstack-watch/SKILL.md

@@ -137,8 +137,9 @@ observed state distinct from merged, and the human merges by default.
 ## 6. End and preserve continuity
 
 End a chat-run watch only after all members merged or closed or user
-cancellation, with own-automation disable/readback and driver-owned cleanup
-receipts in [Watch runtime](references/watch-runtime.md#chat-run-watch).
+cancellation, with own-automation disable/readback and driver-owned automation
+removal and workspace cleanup receipts in
+[Watch runtime](references/watch-runtime.md#chat-run-watch).
 
 End a standalone watch early when all required PRs merge, at cancellation, or
 at its shared default 24 h deadline. In every case, stop all owned

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

@@ -10,7 +10,10 @@ A standalone PR owner remains accountable through the default 24-hour window.
 current GitHub state, persists event IDs, wakes the owner only for a new
 actionable event, and never sends or mutates. Healthy observations update
 quietly. Reuse prior watch identity rather than registering a duplicate, and
-stop task-owned registrations at completion, cancellation, or expiry.
+stop task-owned registrations at completion, cancellation, or expiry. The owner
+must disable and read back its own automation, then remove it by exact ID under
+[Workspace hygiene](../../axstack/references/workspace-hygiene.md#owned-automation-retirement).
+Remove its dedicated workspace only after the terminal and preservation guards pass.
 
 ## Chat-run watch
 
@@ -109,8 +112,11 @@ Stop only when all members merged or closed, or on user cancellation recorded
 by the driver in the run record. Re-read membership and confirm no ambiguous
 publication or unsettled pass; cancellation
 prevents new work but does not prove running workers exited. The observer may
-disable only its own automation and must verify native disable/readback. A
-failed or uncertain disable is a hold. Report the stop receipt to the driver.
+disable only its own automation and must verify native disable/readback. A failed
+or uncertain disable is a hold. Report the stop receipt to the driver; the
+driver removes the automation by exact ID, verifies absence, and removes the
+dedicated workspace after the observer terminal closes under
+[Workspace hygiene](../../axstack/references/workspace-hygiene.md#owned-automation-retirement).
 The driver separately settles workers, preserves evidence, and archives the run;
 an unavailable driver leaves those steps pending. The standalone 24-hour expiry
 and peer observation contracts are unchanged.