acstack 0.0.0-stage → 0.47.0

package/skills/implement/design-pass.md

@@ -0,0 +1,32 @@
+# The audit and polish pass
+
+Step 5 in `SKILL.md` runs the pipeline in eight numbered steps. `SKILL.md`
+states when steps 5 to 7 run. This file holds how to run them.
+
+5. **`/impeccable audit`** – report design findings on the changed frontend
+   files. The audit edits nothing. It needs no browser.
+
+    You type the command yourself. impeccable's plugin loads it into your chat
+    as a markdown playbook.
+
+    Read the design gate with `~/.claude/acstack/bin/acstack design-gate`.
+
+    The file list is the one the checker derived in its section 5.5, from
+    `git status --porcelain -- <frontend.directory>`.
+
+6. **`/impeccable polish`** – fix the same files. Polish reads the audit
+   findings as its backlog. It edits source.
+
+    You type this command yourself too.
+
+    Tell polish to leave a factual claim in copy untouched. Tell it to list
+    every such claim in its report.
+
+    Only `polish` runs from the audit's "Recommended Actions". Tell the audit
+    to name each other command against the finding that earned it.
+
+    Name `harden`, `clarify`, `adapt`, `optimize`, and `onboard` in your
+    completion report, so the user can pick one later.
+
+7. **task-checker subagent, second run** – polish changed the code, so verify
+   it again. This run happens only when polish ran.

package/skills/implement/relaxed-tdd.md

@@ -0,0 +1,28 @@
+# Relaxed TDD
+
+This file holds what changes in step 5 of `SKILL.md` when
+`acstack/project.yaml` sets `workflow.tdd.strict: false`. Read it only then.
+
+`workflow.tdd.strict: false`, relaxed TDD, runs step 2 before step 1. It
+skips nothing. Relaxed TDD means nobody writes the tests first, and the
+first three subagents still run.
+
+The frontend-verifier's gate is the same under either setting.
+
+The format step stays immediately before the checker, so under relaxed
+it formats the new tests as well.
+
+Relaxed costs the test-writer some of its independence, and you state that
+cost rather than hide it. The implementation already sits in the working
+tree when the test-writer runs. Tell it to write the tests from the node's
+requirements, and to leave the implementation unread.
+
+Under strict there is no implementation for it to read, which is the
+stronger guarantee.
+
+The checker's gate moves with the setting. Under `true` the new tests failed
+before the executor and pass after it.
+
+Under `false` nothing can show them failing without the implementation. The
+checker then holds the new tests to existing and passing. It holds the full
+suite to passing, and the test count to not dropping.

package/skills/map/SKILL.md

@@ -0,0 +1,250 @@
+---
+name: map
+description: The entry point for planned work. A map is a graph of question and work nodes. Charts one if none exists – an opening grill, meaning a round of interview questions, that fixes the destination and surfaces the fog, meaning what cannot yet be stated precisely – and works the frontier, the nodes ready to be worked now, if one does. No tiers and no routing – the graph is however big the fog made it, and nothing declares which. Invoke whenever decisions need settling before work can start, the request is foggy or underspecified, or a map already exists and has open nodes. Use implement instead when the way is already clear.
+argument-hint: "[map name, or the request to chart]"
+---
+
+## User input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+# Map
+
+## Tracker
+
+Nodes live behind a pluggable tracker. A backend declares four operations –
+create, read, update, list. ACStack builds everything else from those four:
+frontier, claim, resolve and walk.
+
+Two backends ship, each declared in this skill's directory:
+
+| Backend | Doc | When |
+| ------- | --- | ---- |
+| GitHub issues | `trackers/github.md` | first choice when `gh` holds a login for the repo's GitHub remote |
+| Files | `trackers/files.md` | the fallback – no auth, offline, any remote |
+
+`workflow.maps.tracker` in `acstack/project.yaml` (`github` or `files`) records
+the project's choice. If the key names a backend, read the matching doc and use
+its operations. If the key is absent, pick at materialisation time – the moment
+you first write the map's nodes down.
+
+Recommend `github` when the repo qualifies, `files` otherwise. Confirm the
+choice with the user. Then write the key, so later sessions need not re-decide.
+
+## Which mode
+
+One command runs two modes, and what already exists picks between them. Check
+the configured tracker for existing maps – `ls acstack/maps/` on the files
+backend, `gh label list --search "map:" --json name` on GitHub.
+
+If `$ARGUMENTS` names a map, or exactly one exists, work its frontier – the
+nodes ready to work now. If none exists, chart. If several exist and
+`$ARGUMENTS` does not pick one, ask.
+
+There are no tiers and no complexity judgement.
+
+One question is a small map or no map at all. Fifty questions is a long
+effort. Nothing declares which.
+
+## Charting
+
+1. **Fix the destination first.** Grill for what done looks like (invoke the
+   `grilling` skill). The destination is the root of everything that follows –
+   settle it before any other question.
+
+2. **Load the frontend branch on a frontend destination.** `frontend.md`
+   beside this skill holds five more rules. Read it when the destination
+   touches `frontend.directory`, the path in `acstack/project.yaml` where the
+   frontend lives. Every other map skips it.
+
+3. **Open with a breadth-first grill.** Work the conversation frontier in
+   rounds per the grilling skill. Explore the codebase for facts as you go –
+   facts are your job, never the user's. Try a throwaway prototype before you
+   ask the user anything (grilling's "Run it before you ask it").
+
+4. **Apply the fog test to what surfaced.** A question you can state precisely
+   now is `open`. One you cannot state is `fog` – record it without forcing it
+   sharp. The test is whether you can *state* the question precisely, not
+   whether you can answer it.
+
+### Progressive materialisation
+
+The machinery appears only when it has to persist. After the opening grill:
+
+- **No fog surfaced** – the way was already clear. No map. Say so and proceed
+  to the work.
+
+- **At most one session's worth** – settle it in conversation. Invoke
+  `record-context` on each decision. No map – there is nothing to resume.
+
+- **More than one session's worth** – materialise the map and work the
+  frontier across sessions.
+
+The test is mechanical. Will the fog outlive this session?
+
+### Materialising
+
+Pick the tracker (see Tracker above), then create the nodes with its `create`
+operation. First the root:
+
+```bash
+# files backend – github.md has the equivalent
+~/.claude/acstack/bin/acstack node create --map <name> --title "<destination>" \
+  --kind destination --label "<at most four words>" \
+  --body "<the destination, as settled>"
+```
+
+- The root is the destination. Pass no `--status` flag, so it opens.
+
+    The root's state follows its subtree. It stays open while any node below
+    it is open, fog or claimed. `archive` resolves it when the map clears.
+    Nothing else writes the root's status, and the frontier never returns it.
+
+- The root counts as pinned without the flag, and on GitHub it carries the
+  `root-node` label. The walk returns pinned nodes in full at the start of
+  every session, so every session orients to the root.
+
+- On GitHub, every node body opens with a header line that encodes its edges.
+  `trackers/github.md` holds the format. The files backend writes none.
+
+- Every node carries a `kind` and a `label`, both required. A `label` is the
+  node's short name for a diagram. `trackers/files.md` holds the kinds, the
+  caps, and the contract the CLI enforces.
+
+- Every node body carries a diagram, two at most. A childless `notes` node is
+  the one exception.
+
+    `visuals.md` holds which visual each kind gets, where it sits in the body,
+    and the rules a hand-drawn one follows. Read it before the first body.
+
+- Standing preferences for the effort become one resolved node. Style rules
+  and constraints the grill surfaced go there. Create it with
+  `--answers <root id> --kind notes --label "<at most four words>" --pinned`.
+
+- Every other surfaced question becomes a node. Give it `open` or `fog` per
+  the fog test.
+
+    Pass `--answers <id>` to name the node whose resolution surfaced it. That
+    link is the node's provenance, the trail back to the root. Pass
+    `--blocked-by` only where you genuinely cannot settle one node before
+    another.
+
+- `mode` defaults to `hitl` – human in the loop, meaning a person answers it.
+
+    A node earns `afk` – away from keyboard, meaning an agent settles it alone
+    – only by containing no decision. Research earns it, and so does work
+    whose questions are all settled. Get this wrong and an agent quietly
+    decides something that was the human's.
+
+- Write every title and body per the `writing` skill.
+- Nodes describe behaviour, not file paths. A node can sit on the frontier for
+  weeks while the codebase moves – you resolve the paths at claim time.
+
+- Draw every parent's diagram once every node exists, per Regenerating
+  diagrams below. A parent draws its subtree, so nothing can draw one earlier.
+  The root is a parent too, and it draws the whole map.
+
+- On the files backend, suggest adding `acstack/maps/` to `.gitignore`
+  (`trackers/files.md` gives the reason).
+
+## Working the frontier
+
+All commands below are the files backend's shape – on GitHub, compose the
+same queries per `trackers/github.md`.
+
+Before step 1, copy the bold title of each numbered step below into your todo
+list word for word, ahead of any task-specific items. A step you skip stays in
+the list, marked `skip: <reason>`.
+
+1. **Orient.** The packaging walk (`acstack node walk --map <name>`) – the root
+   and pinned nodes in full, everything else gisted, meaning title and status
+   only. Zoom in with `node read <id>` when a gist matters – it drops the
+   generated diagram blocks, and `--visuals` puts them back. Do not load
+   every body.
+
+    Also check `node list --map <name> --status claimed`. A claim marks a node
+    someone is working, so a dead session's claim hides it from the frontier
+    forever. If a claim exists and you know of no session working it, ask the
+    user and release it (`--status open`).
+
+2. **Query the frontier.** `acstack node frontier --map <name>` – open nodes
+   with no unresolved blockers, shallowest provenance depth first, number
+   only as a tiebreak. Provenance depth is how many `answers` links separate
+   a node from the root, so the broadest questions come first. The query never
+   returns the root.
+
+3. **Route by `mode` – the only field the machine routes on** (`kind` picks
+   the node's diagram shape, never its route):
+    - `hitl` nodes: run grilling rounds over them. A round is the whole hitl
+     frontier.
+    - `afk` nodes: claim and run without the user. Unlimited, and in parallel
+     when independent. Research goes to `Explore` subagents, with the findings
+     written into the resolution.
+
+     Implementation work follows `/acstack:implement`'s procedure – it owns
+     the claim-execute-resolve flow, the explorer dispatch, and the TDD
+     pipeline. Do not restate that flow here. Invoke it.
+
+4. **Claim, then resolve** – `afk` nodes only. A `hitl` resolution happens
+   inside the grilling round, with no claim step. Both are compositions over
+   `update`:
+
+   ```bash
+   ~/.claude/acstack/bin/acstack node update <id> --map <name> --status claimed
+   ~/.claude/acstack/bin/acstack node update <id> --map <name> --status resolved \
+     --append-body "## Answer
+
+   <what was decided or done, and why>"
+   ```
+
+   The pipeline's state lives inside the claim, not on the node – there is no
+   phase field to maintain. If the work stalls or fails, release the claim
+   (`--status open`) and the node is plainly open again.
+
+5. **After every resolution**, in order:
+    - Invoke `record-context`
+    - Create nodes for anything the resolution surfaced
+    - Create the critique node when the resolved node changed the frontend,
+      per `frontend.md`
+    - Regenerate the diagram on the resolved node's parent (see Regenerating
+      diagrams)
+    - Recompute the frontier
+
+    The regeneration comes after the new nodes exist. A surfaced node hangs
+    off the node you just resolved, inside that same subtree.
+
+    A shallow node arriving late jumps the queue – that is correct, something
+    big just opened up.
+
+6. **Graduate fog as it sharpens.** When you can state a fog node precisely,
+   run `update <id> --status open` – one field, one write. Rewrite the title
+   and body to the sharp statement if they drifted.
+
+Never filter on leaf position or "has a resolved question above it". Work
+nodes can hang anywhere, including straight off the root – a bug is work with
+no question above it.
+
+## Regenerating diagrams
+
+A parent's diagram draws its subtree, so any status change below it leaves
+that diagram wrong. Regenerate on the resolved node's parent after every
+resolution, and on every parent at each frontier recompute. The map skill's
+`visuals.md` holds the commands and the write rules (Regenerating a parent's
+diagram).
+
+## Done
+
+The map clears when the frontier is empty and no fog remains. The durable
+residue is what the map leaves behind – the living specs through commit-time
+sync, the ADRs and glossary entries through `record-context`. You have already
+extracted it along the way.
+
+Report what the map settled. Point at anything the map left `out-of-scope`.
+
+Then invoke `archive` to close the map out. It re-checks the gate itself and
+refuses if anything is still open. It verifies the residue actually landed,
+resolves the root, and asks before disposing of the nodes.

package/skills/map/frontend.md

@@ -0,0 +1,227 @@
+# Frontend destinations
+
+A map whose destination changes the frontend carries five rules that no other
+map loads, and this file holds all five.
+
+`SKILL.md` decides when to read this file. The destination has to touch
+`frontend.directory`, the path in `acstack/project.yaml` where the frontend
+lives.
+
+Two plugins appear in the rules below.
+
+- **impeccable** reviews a shipped user interface against the product's own
+  design rules
+- **open-designer** writes a design a human can look at before anyone builds it
+
+ACStack needs neither. Each rule below says which plugin it needs, and what
+happens when that plugin is absent.
+
+The diagram names the direction questions, meaning the ones a finished design
+answers by existing.
+
+```mermaid
+flowchart TD
+  P["Read PRODUCT.md for framing"] --> Q["Ask impeccable's design questions"]
+  Q --> F{"A finalized design matches the screen?"}
+  F -->|yes| L["Link the design, drop the direction questions"]
+  F -->|no| I{"open-designer installed?"}
+  I -->|yes| V["Node: design the screen in the viewer"]
+  I -->|no| A["Ask the direction questions in the grill"]
+  L --> C["Critique the screen after the work ships"]
+  V --> C
+  A --> C
+```
+
+## Read PRODUCT.md before the opening grill
+
+`PRODUCT.md` is impeccable's product brief. It states the product's users, its
+purpose, and its positioning. impeccable's `init` playbook writes it, and
+ACStack never writes it.
+
+- **Read it before the opening grill** when the file exists, and read it for
+  framing alone
+- **Never ask the user anything the file already states**
+- **Look in impeccable's own resolution order** – `PRODUCT.md`, then
+  `Product.md`, then `product.md`, at the project root
+    - When the root holds none, impeccable also checks `.agents/context/` and
+      `docs/`
+- **Ask the map's own questions when no `PRODUCT.md` exists**, and carry on
+- **This rule needs no plugin installed**, because reading a file needs nothing
+  running
+
+The resolution order comes from impeccable 4.2.0.
+
+## Ask impeccable's design questions
+
+Every frontend destination surfaces the same questions, and impeccable already
+wrote them. Charting copies them into `hitl` question nodes during the opening
+grill. A `hitl` node is one a human answers.
+
+**ACStack never runs `/impeccable shape`.** It copies the questions. That is
+what keeps the map working when impeccable is absent. This rule needs no
+plugin installed.
+
+The questions come from impeccable's `shape` playbook, version 4.2.0, at
+`reference/shape.md` inside the impeccable plugin.
+
+**Purpose, people, outcome** is impeccable's first shape round.
+
+- "What is this surface or feature for, and what problem must it solve?"
+- "Who specifically reaches it, in what situation and state of mind?"
+- "What is the primary thing they must understand or do? What would success look like?"
+- "What is uniquely true here that a neighboring product or generic template could not claim?"
+
+**Material, behavior, boundaries** is impeccable's second shape round.
+impeccable asks it only when a material decision is still open.
+
+- "What real content, evidence, data, and assets must the experience carry? What are realistic minimum, typical, and maximum ranges?"
+- "Which states and transitions matter: first-run, empty, loading, error, success, permissions, overflow, or expert use?"
+- "What is the intended fidelity, breadth, and interactivity: exploration, production-ready screen, full flow, or broader surface?"
+- "What must remain untouched? What would make the result feel wrong even if it looked polished?"
+- "Which platform, framework, performance, accessibility, localization, or delivery constraints are binding?"
+
+**The visual world** adds one more question. It comes from impeccable's
+`new-work.md` rather than from `shape.md`, because impeccable resolves the
+design direction in a later phase. ACStack words the question itself, since
+impeccable does not state it as one line.
+
+- Does this screen inherit the product's existing visual world, extend it, or
+  replace it?
+
+### Two groups of questions
+
+Two rules below act on these groups.
+
+- **The direction questions** are the visual world question, and "What is the
+  intended fidelity, breadth, and interactivity"
+    - A design answers both by existing
+- **The states questions** are "Which states and transitions matter" and the
+  content-and-ranges question
+    - A design answers neither
+
+Two rules govern how you ask.
+
+- **Skip any question `PRODUCT.md` already answers**, since the file states the
+  users, the purpose, and the positioning
+- **Ask 2 to 3 related questions per round**, which is impeccable's own cadence
+    - Never dump the whole set at once
+
+## Link a finalized design instead of asking direction
+
+An open-designer design is a set of standalone HTML pages a human picks
+between. A finalized page is one the human chose.
+
+Designs live under `.open-designer/designs/<name>/`, one directory per design,
+each holding an `index.json`. `index.json` finalizes a page by holding an
+entry at `chosen.pages[<page id>]`. Nothing else marks it – there is no status
+field and no finalized flag.
+
+```bash
+jq -r '.chosen.pages // {} | keys[]' .open-designer/designs/<name>/index.json
+```
+
+- **`chosen.pages` is an object keyed by page id**, and each value is an object
+  holding `variantId`, `tweaks`, and an optional `state`
+- **A design finalizes one page at a time**, so each finalized page needs its
+  own key in `chosen.pages`
+- **An `index.json` carrying `chosen.variantId` and no `chosen.pages` is the old
+  single-page shape**, which finalizes that design's one page
+
+`index.json` gives a page two names. `id` is the name the design's author typed,
+and `label` is an optional human-readable name.
+
+- **Match the destination against both**, since every page carries an `id` and
+  only some carry a `label`
+- **Ask in the grill when the match is unclear**, and offer the finalized pages
+  as the options
+- **Ask when two pages match**, and never pick one
+- **Treat no match as no finalized design**, which sends charting to the viewer
+  rule below
+
+A match changes two things about the destination.
+
+- **Drop the direction questions**, since the chosen page already answers them
+- **Name the design in the destination node** by its `index.json` path and its
+  page id
+
+Keep the states questions either way. A finalized page shows one state of one
+screen, and the map still needs the rest.
+
+This rule needs no plugin installed, because a finalized design is a file on
+disk. The layout comes from open-designer 0.7.4.
+
+## Send the human to the viewer when no design exists
+
+With no finalized design and open-designer installed, charting creates one
+`hitl` node that sends a human to the viewer.
+
+open-designer registers a key in `~/.claude/plugins/installed_plugins.json`
+that starts with `open-designer@`. Check for that key.
+
+```bash
+grep -q '"open-designer@' ~/.claude/plugins/installed_plugins.json
+```
+
+The registry key is `<plugin>@<marketplace>`. The marketplace half is wherever
+the user installed from, so match the half before the `@` alone.
+
+Four rules shape the viewer node.
+
+- **Its `kind` is `work` and its `mode` is `hitl`**, so it carries no `afk`
+  label
+- **Its title says what the human does** – design the screen in the viewer
+- **Its body names the command**, `/open-designer:design`
+- **Every direction question is `blocked-by` that node**, since the design
+  answers them
+    - `trackers/github.md` and `trackers/files.md` hold how each backend writes
+      `blocked-by`
+
+The states questions carry no blocker, because a human can answer them while the
+design is still open.
+
+With open-designer absent, create no viewer node. The direction questions stay
+open and the grill asks them.
+
+## Critique the screen after the work ships
+
+Every resolved work node that changed the frontend gets one `hitl` node that
+critiques the shipped screen.
+
+**This rule needs the design gate on.** The design gate is the set of design
+checks impeccable adds to ACStack's pipeline. One command answers whether it is
+on.
+
+```bash
+~/.claude/acstack/bin/acstack design-gate
+```
+
+It prints `on` and exits 0, or prints `off: <reason>` and exits 1. On `off`,
+create no critique node.
+
+Three rules shape the critique node.
+
+- **Its `kind` is `research` and its `mode` is `hitl`**, because its output is
+  findings and a human runs it
+- **Its body names the command**, `/impeccable critique <the screen>`
+- **It `answers` the work node that shipped the screen**
+
+The round after the critique resolves runs on the report.
+
+- **`/impeccable critique` closes its report with recommended `/impeccable
+  <verb>` commands**, and those commands become the options in the next grill
+  round
+- **impeccable's critique recommends only from its own list**
+    - `adapt`, `animate`, `audit`, `bolder`, `clarify`, `colorize`, `critique`,
+      `delight`, `distill`, `document`, `harden`, `layout`, `onboard`,
+      `optimize`, `overdrive`, `polish`, `quieter`, `shape`, and `typeset`
+- **A human picks the command, never an agent** – every command that changes
+  what the screen is trying to be waits for a grill round
+    - Those commands are `adapt`, `animate`, `bolder`, `clarify`, `colorize`,
+      `delight`, `distill`, `harden`, `live`, `onboard`, `overdrive`, and
+      `quieter`
+    - `live` is one critique never recommends, and a human can still pick it
+- **A chosen command becomes one work node that runs it**
+- **That node is `afk`**, meaning an agent settles it alone, because the human
+  already made the decision
+
+The command list comes from impeccable 4.2.0.

package/skills/map/trackers/files.md

@@ -0,0 +1,74 @@
+# Files tracker
+
+The fallback backend: no auth, works offline, works on any remote. One
+markdown file per node under `acstack/maps/<name>/`, managed by the ACStack
+CLI. Nodes here are transient working state – scratch discarded once the map
+clears.
+
+Suggest adding `acstack/maps/` to `.gitignore` when you first create the
+map.
+
+CLI path: `~/.claude/acstack/bin/acstack`
+
+To enumerate a project's maps: `ls acstack/maps/`.
+
+## The four operations
+
+| Operation | Command |
+| --------- | ------- |
+| create    | `acstack node create --map <name> --title <t> --kind <k> --label <l> [--status] [--mode] [--answers <id>] [--blocked-by <ids>] [--pinned] [--body <md>] [--body-file <path>]` |
+| read      | `acstack node read <id> --map <name> [--json] [--visuals]` |
+| update    | `acstack node update <id> --map <name> [--title] [--status] [--mode] [--kind] [--label] [--answers] [--blocked-by] [--pinned true\|false] [--body] [--body-file] [--append-body]` |
+| list      | `acstack node list --map <name> [--status <s>] [--json]` |
+
+`create` rejects a node that omits `--kind` or `--label`. `--kind` takes one of
+`destination`, `notes`, `decision`, `research`, or `work`. `--label` takes the
+node's short name for a diagram, at most four words and thirty characters.
+
+## No body header
+
+The GitHub backend opens every node body with a header line, because an issue
+has nowhere else to put the fields. This backend writes none.
+
+Frontmatter holds the same facts. `answers` and `blocked-by` sit there
+directly, the map is the directory name, and the root is the node that
+`answers` chains up to. A header here would copy data the CLI already owns
+and would be free to drift from it.
+
+`node read` prints the frontmatter, so a reader sees the same facts either
+way.
+
+## Composed queries
+
+The CLI builds composed queries from the four operations above, rather than
+storing them.
+The CLI ships the two this backend would otherwise recompute by hand every
+session:
+
+- `acstack node frontier --map <name> [--mode hitl|afk] [--json]` – open
+  nodes with no unresolved blockers, shallowest provenance depth first.
+  Provenance depth is how many `answers` links separate a node from the root.
+
+    The frontier never returns the root, the one node whose frontmatter has no
+    `answers`. The root is never work.
+
+- `acstack node walk --map <name> [--full] [--json] [--visuals]` – the
+  packaging walk: the root first, then each node that hangs off it, depth
+  first. The walk prints the root and pinned nodes in full.
+
+Claim and resolve are `update` calls:
+
+```bash
+acstack node update <id> --map <name> --status claimed
+acstack node update <id> --map <name> --status resolved --append-body "## Answer
+..."
+```
+
+## What `read` and `walk` strip
+
+Both commands drop every diagram block a node body holds. A diagram block is
+the rendered map that sits between the `<!-- acstack:diagram -->` markers
+`node diagram` writes. `--visuals` prints the blocks. `--json` always carries
+the whole body.
+
+See `docs/adr/0014-reading-a-node-hides-its-generated-diagram.md` for why.