acstack 0.47.1 → 0.48.1

package/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acstack-cli",
-  "version": "0.47.1",
+  "version": "0.48.1",
   "description": "CLI for the ACStack agentic coding stack",
   "type": "module",
   "license": "MIT",
@@ -25,7 +25,7 @@
     "node": ">=20.0.0"
   },
   "scripts": {
-    "build": "npm run sync-version && node build.mjs",
+    "build": "npm run sync-version && node scripts/build-viewer.mjs && node build.mjs",
     "dev": "node build.mjs --watch",
     "typecheck": "tsc --noEmit",
     "lint": "eslint src/",
@@ -36,11 +36,19 @@
   "devDependencies": {
     "@eslint/js": "^9.39.5",
     "@types/node": "^22.0.0",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@xyflow/react": "^12.12.0",
     "chalk": "^5.4.0",
     "commander": "^14.0.0",
+    "elkjs": "^0.12.0",
     "esbuild": "^0.24.0",
     "eslint": "^9.39.5",
     "fast-glob": "^3.3.0",
+    "lucide-react": "^1.55.0",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "react-markdown": "^10.1.0",
     "typescript": "^5.7.0",
     "typescript-eslint": "^8.67.0",
     "vitest": "^3.0.0",

package/docs/adr/0018-alignment-packs-use-local-viewers.md

@@ -0,0 +1,11 @@
+# Alignment packs use local viewers
+
+Alignment packs must not depend on a remote viewer or remote script. ACStack can open a generated pack in a local browser, including through a localhost server.
+
+## Considered options
+
+A pinned remote viewer keeps generated files smaller. It also makes review depend on network access and trust in a hosted script.
+
+## Consequences
+
+ACStack must inline or vendor the viewer code it needs. A Herdr-style terminal view can follow later if a clean graph viewer exists.

package/docs/adr/index.md

@@ -15,3 +15,4 @@
 - [0015](0015-a-node-id-links-to-its-issue-through-an-anchor.md) – A node id links to its issue through an anchor
 - [0016](0016-the-map-root-carries-no-status-of-its-own.md) – The map root carries no status of its own
 - [0017](0017-call-impeccable-copy-only-its-questions.md) – Call impeccable's command line, and copy only its question sets
+- [0018](0018-alignment-packs-use-local-viewers.md) – Alignment packs use local viewers

package/docs/workflows.md

@@ -121,7 +121,7 @@ Nodes live in a tracker. That is the storage layer, and you can swap it.
 
 - `/acstack:implement` claims `afk` work nodes from the frontier when a map exists
     - It treats the request itself as the work item when none does
-    - Either way, parallel explorer subagents run over the relevant code before anyone writes anything
+    - Either way, parallel read-only codebase-search subagents run over the relevant code before anyone writes anything
 - The command resolves paths at claim time
     - A node describes behaviour
     - It can sit unstarted for weeks

package/orchestrator/AGENTS.md

@@ -55,7 +55,7 @@ ACStack runs on Claude Code, Codex, and pi. The skills name each capability once
 - **Launch a subagent** – start a child agent with its own context, by its ACStack name (`test-writer`, `task-executor`, `task-checker`, `frontend-verifier`)
     - Claude Code: the Agent tool, with `subagent_type` set to that name
     - pi: the `subagent` tool from `pi-subagents`
-    - `Explore` names a read-only codebase-search agent: Claude Code's `Explore`, pi's `scout`
+    - **Read-only codebase-search subagent** – Claude Code's `Explore`, pi's `scout`
     - `debugger` names a debugging agent
     - On a host without a matching built-in agent, launch a general subagent with that brief
 - **Agent team** – parallel full sessions, each owning one scope and launching its own subagents
@@ -502,7 +502,7 @@ Launch each agent by the name below (see Host tools for how your host takes it).
 | Implement task        | `task-executor`     | CANNOT modify tests                                |
 | Verify implementation | `task-checker`      | Mock skepticism, full regression, TDD isolation    |
 | Verify frontend UI    | `frontend-verifier` | Real browser, screenshots, non-negotiable          |
-| Find/locate something | `Explore`           | Built-in codebase search                           |
+| Find/locate something | `Explore` / `scout` | Read-only codebase search; `scout` on pi           |
 | Debug/investigate     | `debugger`          | Built-in debugging agent                           |
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acstack",
-  "version": "0.47.1",
+  "version": "0.48.1",
   "private": false,
   "description": "Agentic coding stack with first-class Claude Code and pi support: skills, orchestrator instructions, and verification agents.",
   "license": "MIT",

package/skills/bootstrap/SKILL.md

@@ -41,7 +41,7 @@ Your job is to:
 
 ## Phase 1: independent exploration (passes 1-3)
 
-Launch **3 parallel `Explore` subagents** at once. Each gets a different exploration strategy:
+Launch **3 parallel read-only codebase-search subagents** at once. Use `Explore` on Claude Code and `scout` on pi. Each gets a different exploration strategy:
 
 ### Pass 1 – entry points strategy
 
@@ -90,7 +90,7 @@ Launch a single subagent to merge the 3 independent drafts per domain. It resolv
 
 ## Phase 3: validation (passes 5-7)
 
-Launch 3 parallel Explore subagents to validate ALL domains independently – each checks that FRs match actual code behavior.
+Launch 3 parallel read-only codebase-search subagents to validate ALL domains independently. Each checks that FRs match actual code behavior.
 
 ## Phase 4: correction merge (pass 8)
 

package/skills/grilling/SKILL.md

@@ -29,9 +29,11 @@ session.
    nothing else. Never ask a question whose answer depends on one still open.
 
 2. **Facts are your job, never the user's.** Skip a question that an
-   environment fact would answer. Dispatch parallel `Explore` subagents, one
-   per distinct place to look, not a fixed count. Fold what they find into
-   the round.
+   environment fact would answer.
+
+   Dispatch parallel read-only codebase-search subagents, one per distinct
+   place to look, not a fixed count. Use `Explore` on Claude Code and `scout`
+   on pi. Fold what they find into the round.
 
 3. **Run it before you ask it.** Check whether running something could answer
    the question – behaviour, timing, output, or performance. If it could,
@@ -106,8 +108,8 @@ the tracker's `update` and `create` operations:
     Write the answer per the `writing` skill.
 
 2. Create a node for each new question the answer surfaced, with `answers`
-   naming the node that surfaced it. Questions that can be stated precisely
-   are `open`; the rest are `fog`.
+   naming the node that surfaced it. Mark precise questions `open`; mark the
+   rest `fog`.
 
 3. Invoke the `record-context` skill for each resolution – it decides whether
    the decision earns an ADR, a glossary term, both, or neither.

package/skills/implement/SKILL.md

@@ -98,9 +98,11 @@ Claim each node as you start it:
 
 Nodes describe behaviour, not paths. **Resolve paths at claim time**.
 
-Before any code change, dispatch parallel explorer subagents over the
-relevant code. Use as many as there are distinct places to look, not a fixed
-count. Act on what they find.
+Before any code change, dispatch parallel read-only codebase-search subagents
+over the relevant code. Use `Explore` on Claude Code and `scout` on pi.
+
+Use as many as there are distinct places to look, not a fixed count. Act on
+what they find.
 
 ### 5. Execute within the claim
 
@@ -219,8 +221,9 @@ diff.
 - **The tracker is the progress record** – claim on start, resolve on pass,
   release on stall. No checkbox files, no phase fields.
 
-- **Explore before writing** – parallel explorer subagents over the relevant
-  code, sized to the node, before any edit.
+- **Explore before writing** – parallel read-only codebase-search subagents
+  over the relevant code, sized to the node, before any edit. Use `Explore` on
+  Claude Code and `scout` on pi.
 
 - **Resume is a query** – picking up where you left off means asking the
   tracker what is workable now, not reconstructing history. A fresh session

package/skills/map/SKILL.md

@@ -94,7 +94,7 @@ 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>" \
+  --kind destination --label "<at most four words>" --summary "<one sentence>" \
   --body "<the destination, as settled>"
 ```
 
@@ -111,9 +111,9 @@ operation. First 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 carries a required `kind` and `label`, its short diagram name.
+  Work nodes and the destination add a one-sentence business `--summary`.
+  `trackers/files.md` holds the kinds, the caps, and the CLI's contract.
 
 - Every node body carries a diagram, two at most. A childless `notes` node is
   the one exception.
@@ -182,8 +182,8 @@ the list, marked `skip: <reason>`.
     - `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.
+     when independent. Research goes to read-only codebase-search subagents:
+     `Explore` on Claude Code and `scout` on pi.
 
      Implementation work follows `/acstack:implement`'s procedure – it owns
      the claim-execute-resolve flow, the explorer dispatch, and the TDD

package/skills/map/trackers/files.md

@@ -16,15 +16,18 @@ To enumerate a project's maps: `ls acstack/maps/`.
 
 | 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>]` |
+| create    | `acstack node create --map <name> --title <t> --kind <k> --label <l> [--summary <s>] [--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]` |
+| update    | `acstack node update <id> --map <name> [--title] [--status] [--mode] [--kind] [--label] [--summary] [--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.
 
+`--summary` is optional: one plain sentence, on one line, for a business
+reader. `create` refuses a blank one, and on `update` an empty string clears it.
+
 ## No body header
 
 The GitHub backend opens every node body with a header line, because an issue

package/skills/pre-commit-review/SKILL.md

@@ -73,7 +73,8 @@ If no meaningful code changes exist (only docs, config, assets), report "No code
 
 ## Step 2: DISCOVER – Learn project conventions (parallel)
 
-Launch **3 parallel Explore subagents** to build a dynamic understanding of the project's current conventions.
+Launch **3 parallel read-only codebase-search subagents** to build a dynamic understanding of the project's current conventions.
+Use `Explore` on Claude Code and `scout` on pi.
 Do NOT hardcode conventions – discover them fresh each time.
 
 **Subagent A – Living Specs & Architecture:**
@@ -177,7 +178,8 @@ Add each finding to the review as `SHOULD | PROSE`, at the `file:line` it names.
 
 ## Step 4: ADJACENT – Check surrounding code for rot
 
-For each file with findings from Step 3, launch an **Explore subagent** (up to 3 in parallel).
+For each file with findings from Step 3, launch a **read-only codebase-search subagent**.
+Use up to 3 subagents in parallel.
 Each subagent examines the rest of that file and its immediate imports for the same categories of issue.
 
 ```

package/skills/quick-fix/SKILL.md

@@ -39,7 +39,7 @@ If the user provided an error message or stack trace, note the key details (file
 
 **Do NOT skip this step.** Delegate exploration to subagents:
 
-1. **Locate the code**: Launch an Explore subagent to find the files involved. Read only a file you can already name.
+1. **Locate the code**: Launch a read-only codebase-search subagent to find the files involved. Use `Explore` on Claude Code and `scout` on pi. Read only a file you can already name.
 
 2. **Read the integration points**: Have the subagent read the broken function's callers and callees, not just the function. Understand:
     - What calls this code? (upstream)

package/skills/setup/row-fixes.md

@@ -50,9 +50,11 @@ frontend and has not turned browser verification on. Turn it on:
 read it. Without it, every path through spec sync skips in silence, and the
 living specs never update.
 
-Launch an **Explore subagent** over `directories.source` to propose domains. Ask
-it for the top-level functional areas. Ask for a kebab-case name, the paths that
-belong to it, and one line saying what it owns.
+Launch a **read-only codebase-search subagent** over `directories.source` to propose domains.
+Use `Explore` on Claude Code and `scout` on pi.
+
+Ask it for the top-level functional areas.
+Ask for a kebab-case name, the paths that belong to it, and one line saying what it owns.
 
 Guidance for the subagent: