axstack 0.20.21 → 0.20.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "axstack",
-  "version": "0.20.21",
+  "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/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-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