acstack 0.50.3 → 0.51.0

package/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acstack-cli",
-  "version": "0.50.3",
+  "version": "0.51.0",
   "description": "CLI for the ACStack agentic coding stack",
   "type": "module",
   "license": "MIT",

package/docs/config-reference.md

@@ -1,8 +1,8 @@
 # Project configuration
 
-*Every key in `acstack/project.yaml`, the values it takes, its default, and what changes when you change it.*
+*Every key in `.acstack/project.yaml`, the values it takes, its default, and what changes when you change it.*
 
-One file, `acstack/project.yaml`, holds every setting that belongs to a project.
+One file, `.acstack/project.yaml`, holds every setting that belongs to a project.
 
 - **It names what to run**: the test, build, lint, typecheck, and format commands
 - **It names where to look**: the source and test directories, and the frontend
@@ -18,7 +18,7 @@ Three terms first.
 
 ```mermaid
 flowchart TD
-    FILE["acstack/project.yaml<br/>(written by /acstack:setup)"] --> WF["workflow.*<br/>switches, maps, handoff"]
+    FILE[".acstack/project.yaml<br/>(written by /acstack:setup)"] --> WF["workflow.*<br/>switches, maps, handoff"]
     FILE --> RUN["commands.*, directories.*,<br/>test_markers, venv"]
     FILE --> FE["frontend.*<br/>dev server, browser"]
     WF --> SKILLS["commit, grilling, map,<br/>archive, handoff"]
@@ -44,7 +44,7 @@ flowchart TD
 
 *The setup skill writes the whole file. To change one key, run `acstack config set`.*
 
-- `acstack/project.yaml` sits in the project root, beside `acstack/domain-map.yaml`
+- `.acstack/project.yaml` sits under the project root, beside `.acstack/domain-map.yaml`
 - `/acstack:setup` writes it
     - On a fresh project the skill detects the project type, then writes every key from a profile under `profiles/`
     - On a project that already has the file, the skill leads with the health check and offers a menu of changes
@@ -54,7 +54,8 @@ flowchart TD
     - The setup skill copies them from a profile
         - An omitted one names nothing at all
 
-Four commands read the file and change nothing.
+These commands report configuration without changing settings.
+CLI startup can repair the root Git ignore baseline before the command runs.
 
 | Command | What it prints |
 | --- | --- |
@@ -63,6 +64,104 @@ Four commands read the file and change nothing.
 | `acstack config list` | every key the file states |
 | `acstack design-gate` | whether a design review runs here, as `on` and exit 0 or one `off: <reason>` line per reason and exit 1 (section 3) |
 
+### Project data stays local by default
+
+- All ACStack-owned project records live under `.acstack/`
+- The root `.gitignore` controls tracking, independently for every part
+- No configuration key controls tracking
+
+| Part | Canonical path |
+| --- | --- |
+| Project configuration | `.acstack/project.yaml` |
+| Domain map | `.acstack/domain-map.yaml` |
+| Living specs | `.acstack/specs/` |
+| Maps | `.acstack/maps/` |
+| Authored design sources | `.acstack/designs/` |
+| Archives | `.acstack/archive/` |
+| Legacy change records | `.acstack/changes/` |
+| Legacy review artifacts (retained for explicit import) | `.acstack/alignment-packs/` |
+| Canonical design reviews and imported history | `.acstack/design-reviews/` |
+| Architecture decisions | `.acstack/decisions/` |
+| Cross-domain glossary | `.acstack/CONTEXT.md` |
+| Browser connection | `.acstack/agent-browser.json` |
+| Verification knowledge | `.acstack/verification/VERIFICATION-KNOWLEDGE.md` |
+| Test baseline | `.acstack/.test-baseline` |
+| Decision logs | `.acstack/decision-logs/` |
+| Continuation anchor | `.acstack/HANDOFF.md` |
+| Agent handoffs | `.acstack/handoffs/` |
+
+- `/acstack:setup` creates `.acstack/`, then immediately runs `~/.claude/acstack/bin/acstack project-data ensure`
+- Setup asks which parts to track with a multi-select question, with none selected by default
+- CLI and host session startup run `project-data ensure` before checking configuration
+- `ensure` needs no config when `.acstack/` exists and does nothing when no project data exists
+- It installs a managed `/.acstack/**` baseline at the start of the root `.gitignore`
+- Existing user rules follow the baseline, preserving their exceptions
+- Bare filesystem creation cannot trigger a command
+    - The first ACStack CLI invocation or session startup enforces the baseline; ACStack runs no filesystem watcher
+- Add native exceptions after existing rules, outside the managed baseline, to track selected parts
+    - The user can select configuration, specs, and architecture decisions independently
+
+```gitignore
+# User rules after existing rules and the ACStack-managed baseline
+!/.acstack/
+!/.acstack/project.yaml
+!/.acstack/specs/
+!/.acstack/specs/**
+!/.acstack/decisions/
+!/.acstack/decisions/**
+```
+
+- Reopen `.acstack/` before any selected part to override earlier whole-directory ignores
+- A nested file also needs its parent directory reopened, for example `!/.acstack/verification/` before its file exception
+- Git ignore rules do not untrack files already in the Git index
+- ACStack never force-adds ignored files or changes the Git index to enforce this policy
+- ACStack retires `workflow.alignment_packs` auto-generation, approval, and tracking settings; existing fields have no effect
+    - This includes `approval_gate` and `commit_generated_packs`
+    - Setup and config writes no longer offer them; ACStack never silently rewrites or deletes existing files
+    - Native Git ignore rules alone control tracking
+- Map-linked design approval uses the exact source, saved comments, and contribution inputs, without a new workflow flag
+- `workflow.design_review` still controls only the frontend design pass
+- Installed tools under `~/.claude/acstack/bin/`, XDG configuration, and host-owned `.claude/` settings keep their existing locations
+- Helper programs and user code under `frontend.helpers_dir` stay where they are
+    - Verification metadata always uses `.acstack/verification/VERIFICATION-KNOWLEDGE.md`
+
+### Explicit migration from the old layout
+
+1. Update installed ACStack tools before moving project data
+2. Stop old agent sessions and review processes; old CLI versions and hooks cannot read the new layout
+3. From the checkout to migrate, run `~/.claude/acstack/bin/acstack project-data migrate`
+4. Review the working-tree changes, then restart agents and reviews with the updated tools
+
+- Migration preflights all moves and aborts on collisions without overwriting destination data
+- It moves old `acstack/` project records, root `CONTEXT.md`, `.test-baseline`, and `agent-browser.json` into the canonical destinations
+- It moves `docs/adr/` to `.acstack/decisions/` and old decision logs to `.acstack/decision-logs/`
+- It moves verification knowledge, not arbitrary helper directories or their programs
+- Previously tracked old paths become pending deletions; their new destinations stay local unless the user opts in
+- Migration preserves local data and makes no Git index changes or automatic tracking exceptions
+- Migrate each checkout explicitly; never move another checkout's data automatically
+- Decision logs still belong to the main checkout at `<main checkout>/.acstack/decision-logs/`
+    - If that checkout remains on the legacy layout, stop and report an actionable migration error
+    - Do not create a partial `.acstack/` directory there as a workaround
+
+### Explicit import from retired map reviews
+
+- ACStack removes legacy `map --map` and `align-viewer` without aliases
+- Use `design-doc <entry>` for authored design review
+- Use `node walk`, `node frontier`, and `node diagram` for map planning
+- Author the new design before importing legacy feedback
+
+```sh
+~/.claude/acstack/bin/acstack design-review migrate <entry> \
+  --legacy-dir <path> --mapping <json-file> [--feedback <json-file>]
+```
+
+- Choose a nonsymlink directory under `.acstack/alignment-packs/`
+- Supply explicit target mappings; see the `design-doc` skill for mapping and reconciliation instructions
+- Migration preserves source artifacts and decision logs unchanged
+- Canonical `review.json` keeps imported feedback and approval history; historical approval never authorizes the current design
+- Startup and archive never import automatically
+- Design source, review evidence, imported history, and decision logs outlive temporary map nodes regardless of `workflow.maps.persist`
+
 ### 1.1. Which file a write lands in
 
 *The key decides, and the key alone.*
@@ -70,7 +169,7 @@ Four commands read the file and change nothing.
 - A `host.*` key describes the machine
     - It goes to the global config at `~/.config/acstack/config.json`
 - Every other key in this document describes the project
-    - It goes to `acstack/project.yaml`
+    - It goes to `.acstack/project.yaml`
 - Section 10 covers the `host.*` keys
 - `acstack config get <key>` and `acstack config unset <key>` read the same key table and route the same way
 
@@ -152,7 +251,7 @@ So the result decides which path a write takes, and never the shape of the key.
 
 *A file ACStack itself produced always reads back.*
 
-- A project that holds `acstack/` and no `project.yaml` gets the file created
+- A project that holds `.acstack/` and no `project.yaml` gets the file created
 - A block stating nothing takes a key underneath it, whether the file spells that block as a bare colon, as `null` or as `~`
     - That is the state `acstack config unset` leaves behind
         - The tool accepts its own output
@@ -210,7 +309,7 @@ Three refusals protect a file neither command can handle.
 
 | Key | Values | Default | What changes |
 | --- | --- | --- | --- |
-| `workflow.spec_sync` | `true`, `false` | `true` | the `commit` skill runs spec sync before it commits, unless this says `false`; with `false` the living specs under `acstack/specs/` stop tracking the code |
+| `workflow.spec_sync` | `true`, `false` | `true` | the `commit` skill runs spec sync before it commits, unless this says `false`; with `false` the living specs under `.acstack/specs/` stop tracking the code |
 | `workflow.tdd.strict` | `true`, `false` | none | deprecated compatibility boolean; no sequencing effect, including explicit `true` |
 | `workflow.tdd.orchestrator_strict` | `true`, `false` | none | deprecated compatibility boolean; no delegation effect, including explicit `true` |
 | `workflow.frontend_verification` | `true`, `false` | `false` | the frontend-verifier runs only when this is `true`, the file configures a `frontend` block, and the change touched frontend files |
@@ -271,7 +370,7 @@ A **map** is a graph of question nodes and work nodes. A **tracker** is the back
 | Key | Values | Default | What changes |
 | --- | --- | --- | --- |
 | `workflow.maps.tracker` | `github`, `files` | none | the `map`, `implement`, and `archive` skills read the matching backend document and use its operations |
-| `workflow.maps.persist` | `true`, `false` | `false` | `true` moves a cleared map's node files to `acstack/archive/[YYYY-MM-DD]-[name]/nodes/`; `false` deletes `acstack/maps/<name>/` |
+| `workflow.maps.persist` | `true`, `false` | `false` | `true` moves a cleared map's node files to `.acstack/archive/[YYYY-MM-DD]-[name]/nodes/`; `false` deletes `.acstack/maps/<name>/` |
 
 - An absent `workflow.maps.tracker` means nobody has chosen yet
     - The `map` skill then picks at the moment it first writes a map's nodes down, confirms the choice with the user, and writes the key
@@ -423,7 +522,7 @@ Two limits are worth knowing.
         - `200_000` reads as 200,000
     - Exponent and float notation do not
         - `2e5` and `2.0` fall back to the default
-- The hook opens `acstack/project.yaml` relative to the working directory
+- The hook opens `.acstack/project.yaml` relative to the working directory
     - A session running outside the project root therefore gets the defaults, whatever the file says
 
 ## 7. commands, directories, test_markers and venv
@@ -433,7 +532,7 @@ Two limits are worth knowing.
 | Key | Values | Default | What changes |
 | --- | --- | --- | --- |
 | `commands.test` | a shell command, or `null` | from the profile | the verification owner runs the configured tests |
-| `commands.test_collect` | a shell command, or `null` | from the profile | the verification owner compares counts with `.test-baseline`; counts alone do not prove coverage |
+| `commands.test_collect` | a shell command, or `null` | from the profile | the verification owner compares counts with `.acstack/.test-baseline`; counts alone do not prove coverage |
 | `commands.build` | a shell command, or `null` | from the profile | the verification owner checks the build with it |
 | `commands.lint` | a shell command, or `null` | from the profile | the verification owner lints with it, usually with a fix flag |
 | `commands.typecheck` | a shell command, or `null` | from the profile | the verification owner type-checks with it |
@@ -461,7 +560,7 @@ Two limits are worth knowing.
 | `frontend.directory` | a path | `frontend/` | where the frontend lives |
 | `frontend.dev_server_url` | a URL | `http://localhost:3000` | the address the frontend-verifier opens |
 | `frontend.dev_server_check` | a shell command | a `curl` of the URL | how the frontend-verifier decides the dev server is up |
-| `frontend.helpers_dir` | a path | `<frontend.directory>/tests/helpers/` | where `VERIFICATION-KNOWLEDGE.md` lives; the `verification-knowledge` row of the check fails when the file is missing, and when the key states nothing |
+| `frontend.helpers_dir` | a path | `<frontend.directory>/tests/helpers/` | where helper programs live; verification metadata always lives at `.acstack/verification/VERIFICATION-KNOWLEDGE.md` |
 | `frontend.commands.dev` | a shell command | none | how the frontend-verifier starts the dev server; without it the verifier cannot start one itself |
 | `frontend.commands.build` | a shell command | from the profile | the frontend build the verification owner runs |
 | `frontend.commands.lint` | a shell command | from the profile | the frontend lint the verification owner runs |
@@ -480,7 +579,7 @@ The Chrome DevTools Protocol (CDP) is the wire protocol the verifier drives a br
 | --- | --- | --- | --- |
 | `frontend.browser.mode` | `remote`, `headless`, `local` | none | the mode `acstack config browser-mode` resolves for the frontend-verifier, weighed against the three host axes; it also picks the `cdp_port` default |
 | `frontend.browser.fallback` | `none`, `remote`, `headless`, `local` | none | only `none` acts: it forbids another mode from standing in when the host does not declare the preferred one |
-| `frontend.browser.cdp_port` | a whole number from 1 to 65535 | `19988` under `mode: remote`, `9555` otherwise | the port the frontend-verifier dials, and the port the `agent-browser-json` row of the check requires `agent-browser.json` to name |
+| `frontend.browser.cdp_port` | a whole number from 1 to 65535 | `19988` under `mode: remote`, `9555` otherwise | the port the frontend-verifier dials, and the port the `agent-browser-json` row of the check requires `.acstack/agent-browser.json` to name |
 
 The two defaults come from two different browsers.
 
@@ -491,7 +590,7 @@ The two defaults come from two different browsers.
 The port default applies wherever the CLI needs a number.
 
 - `acstack config check` holds a project that states no `cdp_port` to the default its mode implies
-- It fails when `agent-browser.json` names a different port
+- It fails when `.acstack/agent-browser.json` names a different port
 - `acstack config show` behaves the other way, printing only what the project states
     - "What did the project say" and "which port do we dial" are different questions
 

package/docs/dev-setups.md

@@ -27,7 +27,7 @@ flowchart TD
     AXES --> OPT["Optional axes<br/>(preview, terminal workspace, element picker, Orca topology)"]
     ORCH -->|"pick the worktree tool"| WT["new-worktree, teardown-worktree"]
     BROW -->|"pick the browser"| FV["frontend-verifier"]
-    PROJ["What this project prefers<br/>(frontend.browser.* in acstack/project.yaml)"] --> FV
+    PROJ["What this project prefers<br/>(frontend.browser.* in .acstack/project.yaml)"] --> FV
     OPT -.->|"nothing reads them yet"| CHK["acstack config check lists them"]
 ```
 
@@ -46,9 +46,9 @@ flowchart TD
 | `host.terminal_workspace` | `true`, `false` | no | global config | `/acstack:setup` offers the workspace once, and never asks again after this is set |
 | `host.element_picker` | `stagewise`, `orca-design-mode`, `none` | no | global config | nothing; check 5 lists it |
 | `host.orca.topology` | `local`, `remote` | no | global config | nothing; check 5 marks it inert unless `host.orchestrators.orca` is `true` |
-| `frontend.browser.mode` | `remote`, `headless`, `local` | no | `acstack/project.yaml` | the preference, weighed against the three host axes |
-| `frontend.browser.cdp_port` | a port number | no | `acstack/project.yaml` | `frontend-verifier`; defaults to `19988` for `remote` and `9555` otherwise |
-| `frontend.browser.fallback` | `none`, or any word | no | `acstack/project.yaml` | only `none` acts: it forbids a stand-in mode |
+| `frontend.browser.mode` | `remote`, `headless`, `local` | no | `.acstack/project.yaml` | the preference, weighed against the three host axes |
+| `frontend.browser.cdp_port` | a port number | no | `.acstack/project.yaml` | `frontend-verifier`; defaults to `19988` for `remote` and `9555` otherwise |
+| `frontend.browser.fallback` | `none`, or any word | no | `.acstack/project.yaml` | only `none` acts: it forbids a stand-in mode |
 
 Where the file lives, and how the CLI reads a value:
 

package/docs/terminal-workspace-keys.md

@@ -74,6 +74,7 @@ Add `shift` to any of these to open it in a full tab instead of a popup.
 | Key | Does |
 |---|---|
 | `e` | edit in `$EDITOR` |
+| `i` | inspect Markdown in Frogmouth (install with `pipx install frogmouth`; existing `i` bindings take precedence) |
 | `o` | open by rule, which for markdown is the reader |
 | `b` | open in the browser you are sitting at |
 | `D` | send the file to your laptop over Taildrop |

package/docs/terminal-workspace.md

@@ -1562,7 +1562,7 @@ export ACSTACK_OPEN_CMD="ssh laptop open"   # or any command taking a URL
     - It needs a tab armed by hand before every session
     - The tab it drives lives in a dedicated Chrome profile rather than your default browser
 - The opener is the answer for reading
-- It is a separate service on purpose, per [ADR 0006](adr/0006-document-opener-service.md)
+- A separate service opens documents without depending on the relay or the browser automation session
 
 What it does is deliberately small:
 

package/docs/workflows.md

@@ -21,7 +21,7 @@ flowchart TD
     F --> T
     T --> C["Commit<br/>(acstack:commit)"]
     C --> Y["Sync specs from the diff<br/>(domain-map.yaml)"]
-    Y --> L[("Living specs<br/>acstack/specs/")]
+    Y --> L[("Living specs<br/>.acstack/specs/")]
     M -->|"every question answered"| A["Archive<br/>(check the decisions landed,<br/>then delete the nodes)"]
     A --> L
 ```
@@ -102,7 +102,7 @@ Nodes live in a tracker. That is the storage layer, and you can swap it.
     - The first line of every issue body carries all of that node's edges
     - One list call therefore returns the whole graph
     - A sub-issue and a dependency mirror those edges, so GitHub's own interface draws the map
-- Files under `acstack/maps/<name>/` are the fallback
+- Files under `.acstack/maps/<name>/` are the fallback
     - Frontmatter holds the edges, so those files carry no header line
 - Frontier, claim, and resolve build on those four operations
     - No tracker implements them itself
@@ -152,9 +152,9 @@ Nodes live in a tracker. That is the storage layer, and you can swap it.
     - There is no question cap
     - The set of answerable questions bounds itself
 - **`record-context`** fires when a decision lands
-    - It writes an ADR under `docs/adr/` only when the decision is hard to reverse *and* surprising *and* a real trade-off
-    - It writes a glossary term when a term got settled, in root `CONTEXT.md` for cross-domain vocabulary
-    - It writes a domain term in `acstack/specs/<domain>/CONTEXT.md` instead
+    - It writes an ADR under `.acstack/decisions/` only when the decision is hard to reverse *and* surprising *and* a real trade-off
+    - It writes a glossary term when a term got settled, in `.acstack/CONTEXT.md` for cross-domain vocabulary
+    - It writes a domain term in `.acstack/specs/<domain>/CONTEXT.md` instead
     - It can write both, or neither
     - ACStack generates the ADR index from the files
     - Nobody hand-edits it
@@ -194,9 +194,9 @@ flowchart LR
 
 `/acstack:commit` groups changes into MECE commits. MECE means mutually exclusive and collectively exhaustive: no change appears twice, and no change goes missing. Before writing them it does five things.
 
-1. Reads `acstack/domain-map.yaml` to map each changed file to a domain.
+1. Reads `.acstack/domain-map.yaml` to map each changed file to a domain.
 2. Works out what the diff adds, modifies or removes, for each affected domain with a `spec.md`.
-3. Writes those entries into the domain's spec and stages them in the same commit.
+3. Writes those entries into the domain's spec; it stages tracked specs and preserves ignored specs locally without force-adding them.
 4. Flags source files that match no domain.
 5. Checks the glossaries.
 
@@ -214,7 +214,7 @@ Four cases stop sync.
 - no file matching a domain
 - a change that touches only docs and config
 
-**Without `acstack/domain-map.yaml` this step does nothing, silently.**
+**Without `.acstack/domain-map.yaml` this step does nothing, silently.**
 
 - `/acstack:setup` generates that file
 - `acstack config check` reports it as missing on a project set up before that existed
@@ -223,11 +223,16 @@ Four cases stop sync.
 
 *A map is working state, not a record you keep. Archive checks the decisions reached your specs, your decision notes, and your glossary, then deletes the nodes.*
 
-- `/acstack:archive` checks for a cleared map: empty frontier, no fog, no claims
-- It spot-checks that the specs, the decision notes and the glossary captured what the effort settled
+- `/acstack:archive` checks all nodes, not just the frontier: no open questions, fog, or claims apart from the root
+- A bound design requires completed feedback reconciliation and current exact-revision approval
+- Archive checks living specs against implemented behavior, not proposals
+- Archive applies `record-context`'s existing ADR and glossary criteria
+- Archive records dropped scope, unresolved limits, and durable node provenance before disposal
+- Design source, canonical review evidence, imported history, and decision logs survive regardless of `workflow.maps.persist`
+- Archive never recursively deletes review artifacts or evidence-bearing handoffs
 - It then disposes of the nodes
     - It deletes them by default
-    - It moves them to `acstack/archive/<date>-<name>/nodes/` when `workflow.maps.persist` is `true`
+    - It moves them to `.acstack/archive/<date>-<name>/nodes/` when `workflow.maps.persist` is `true`
     - Keeping nodes is off by default
     - A kept map is a second copy of every decision
     - The two drift apart
@@ -237,14 +242,14 @@ Four cases stop sync.
     - The user types `/acstack:archive`
     - `/acstack:map` hands off to it once every node resolves
     - The disposal step then asks you first
-- Legacy `acstack/changes/` directories from the pre-map workflow still archive the old way
+- Legacy `.acstack/changes/` directories from the pre-map workflow still archive the old way
     - An upgrade therefore never strands work
 
 ## 7. Living specs
 
-*What the project keeps. ACStack deletes a map once every question resolves. `acstack/specs/` outlives it.*
+*What the project keeps. ACStack deletes a map once every question resolves. `.acstack/specs/` outlives it.*
 
-- Specs live at `acstack/specs/<domain>/spec.md`, organised by the domains in `domain-map.yaml`
+- Specs live at `.acstack/specs/<domain>/spec.md`, organised by the domains in `domain-map.yaml`
 - Each spec states numbered functional requirements (`FR-NNN`) in Given, When, Then form
 - They are cumulative
 - They describe only what the code already does
@@ -257,8 +262,9 @@ Two rules keep them honest.
     - Archive verifies a completed map left nothing behind
     - Both converge on the same files
 - **Fix it when you see it**
-    - Any agent that finds a spec contradicting the code corrects the spec immediately
-    - It rewrites wrong behaviour, appends missing requirements, and deletes stale references
+    - An agent that finds a contradiction corrects the spec or routes the correction to its owner
+    - A read-only reviewer reports the discrepancy to the completion owner
+    - The owner rewrites wrong behaviour, appends missing requirements, and deletes stale references
 
 `/acstack:bootstrap` generates the first set from an existing codebase. A project never starts from an empty directory.
 

package/examples/design-doc/acstack/README.md

@@ -0,0 +1,273 @@
+# ACStack design review
+
+ACStack guides design authoring, saves browser feedback, reconciles optional map contributions, and records exact-revision approval with retained evidence.
+
+<!-- Generated from the entry YAML and its element files; regenerate with design-doc --markdown -->
+
+```mermaid
+flowchart TD
+    element_user["Project developer<br/>actor"]
+    subgraph element_acstack["ACStack plugin"]
+        element_skills["Agent skills<br/>component · agent"]
+        element_host["Agent session setup<br/>component · agent"]
+        subgraph element_cli["CLI package"]
+            element_review-runtime["Review command and server<br/>component · cli, web"]
+            element_viewer["Browser review interface<br/>component · web"]
+        end
+    end
+    element_design-source["Authored design files<br/>store"]
+    element_github["GitHub<br/>external-system · web"]
+    element_user -->|"Requests design guidance from"| element_skills
+    element_user -->|"Optionally publishes the Markdown companion to"| element_github
+    element_skills -->|"Guides the agent to run"| element_review-runtime
+    element_host -->|"Registers"| element_skills
+    element_review-runtime -->|"Reads design source"| element_design-source
+    element_review-runtime <-->|"Exchanges the design and comments with"| element_viewer
+```
+
+## Review the design before implementation
+
+ACStack saves design feedback, reconciles comments and optional map contributions, and records human approval of the exact reviewed inputs.
+
+This example keeps the existing architecture: Agent skills guide the agent; the Review command and server validate source and save review evidence. The Browser review interface shows the design and collects feedback and approval. Review the responsibilities, containment, and labeled arrows before implementation.
+
+### Author, review, reconcile, and approve
+
+1. The developer asks the agent to prepare a design through the Agent skills registered by Agent session setup
+2. The agent writes the entry, element YAML, and supporting Markdown in one bounded directory tree
+3. The agent runs `acstack design-doc design.yaml --markdown /tmp/acstack-design-review.md` with an unused output path and keeps the server running
+4. The server validates source and serves the prepared graph with bundled browser assets; the browser never reads YAML directly
+5. The developer saves comments, chooses Send to agent, and pastes the copied prompt into the agent session
+6. The agent reads the saved review, revises source, and uses `acstack design-review status design.yaml` to inspect feedback and optional map contributions
+7. The agent explicitly reconciles each selected comment and current contribution, then resolves blocking human questions or marks dropped scope out of scope
+8. The agent reopens changed source for review; the human chooses Approve this revision once reconciliation is current
+9. The agent requires `approval.valid: true` from status before implementation, then runs the separate implementation checks
+10. At map closeout, archive verifies implemented functional requirements in living specs, architecture decision records (ADRs), and agreed glossary terms before disposing of temporary nodes
+
+The developer can manually publish the generated Markdown companion to GitHub. Publication does not transfer browser comments or approval, and ACStack does not track that publication automatically.
+
+### Approval belongs to exact inputs
+
+- Approval binds `sourceRevision`, `reviewRevision`, `commentsDigest`, and `mapInputsDigest`, not the rendered page alone
+- Each selected comment and current contribution needs one explicit disposition: `applied`, `retained`, or `needs-human`, with a rationale
+- Unresolved blocking decisions or a `needs-human` disposition prevent approval; comments alone never authorize implementation
+- Source, saved feedback, or meaningful contribution changes reopen the gate; presentation regeneration alone preserves approval
+
+- Use `design-review status` for the current tuple and contribution keys
+- Follow `skills/design-doc/SKILL.md` for the reconciliation schema and `design-review reconcile <entry> --input <json-file>`
+- Select earlier feedback with `--review-file <canonical-review.json>` when reconciling that history
+    - Original comments stay with their original version
+    - Previously selected histories remain review obligations after later source changes
+
+This revised example is a new draft requiring fresh human approval.
+
+### Map binding is optional
+
+This portable example has no map binding. A project can add `planning: {tracker: files | github, map: <name>}` and put `Design entry: <repository-relative-path>` in its map root. Node bodies supply explicit design contributions; the map does not become the architecture graph.
+
+Bundled browser assets require no external fetch or design upload. Agent-side reads of a GitHub-bound map still need GitHub access. The diagram's GitHub arrow describes manual Markdown publication, not tracker synchronization.
+
+### Archive preserves evidence; legacy import is explicit
+
+- Archive checks current approval and reconciliation before closing a bound map
+- Archive verifies implemented requirements against source and verification evidence
+- Archive records qualifying ADRs and glossary terms
+- Archive retains design sources, canonical reviews, import history, original legacy artifacts, and decision logs independently of node disposal
+
+- Use `node walk`, `node frontier`, and `node diagram` for planning; ACStack retires `map --map` and `align-viewer` without aliases
+- Import legacy feedback only through `design-review migrate` with an explicit target mapping
+- Treat imported approval as historical; imported comments require reconciliation and fresh exact-revision approval
+- Startup and archive never migrate automatically
+
+### Local source and optional GitHub publication
+
+- Authored design files are the local YAML and supporting Markdown read by the Review command and server
+- GitHub hosts a published copy of the generated companion only when the Project developer chooses to share it
+- Git ignore rules control ordinary tracking; they neither publish files nor prevent local browser review
+- Both the Authored design files and GitHub drawers explain source ownership, published copies, and ignore rules
+
+### Containment and arrows keep their existing meaning
+
+The ACStack plugin contains Agent skills, Agent session setup, and the CLI package. The CLI package contains the Review command and server and the Browser review interface. The Project developer, Authored design files, and GitHub remain outside the plugin.
+
+- Each component is one entity, shown collapsed or expanded
+- Nesting means containment; arrows connect responsible entities, never ancestors to descendants
+- Read one-way arrows as actor, action, and target: the server reads source, and the developer optionally publishes Markdown
+- The bidirectional review-session arrow covers the prepared graph, posted comments, and retrieved comments
+- Concerns describe shared requirements without changing containment
+
+### Optional repository context
+
+- Authoring, reconciliation, approval, and migration guidance: `skills/design-doc/SKILL.md`
+- Local review and lifecycle commands: `cli/src/commands/design-doc.ts`
+- Bounded source validation, graph, and Markdown generation: `cli/src/lib/design-doc.ts`
+- Contributions and exact-input approval: `cli/src/lib/design-map.ts`, `cli/src/lib/design-lifecycle.ts`
+- Saved review history and legacy imports: `cli/src/lib/design-review.ts`, `cli/src/lib/design-migration.ts`
+- Closeout and evidence retention: `skills/archive/SKILL.md`
+
+- Run the review command from this example directory with a built CLI
+- Choose `--port <port>` if another review uses the default port
+- Use an unused path for each Markdown export
+- Keep the companion beside source when its relative links must work on GitHub
+- New designs default to Git-ignored `.acstack/designs/`; this repository intentionally tracks this public example
+
+
+## Project developer
+
+*Authors the design and reviews the exported artifact locally.*
+
+- Identity: `user`
+- Kind: actor
+- Channels: none
+- Source: [user.yaml](user.yaml)
+
+
+
+## ACStack plugin
+
+*Ships agent skills, session setup, and a bundled CLI.*
+
+- Identity: `acstack`
+- Kind: component
+- Channels: none
+- Source: [acstack.yaml](acstack.yaml)
+
+
+
+## Agent skills
+
+*Guide the agent through authoring and exporting a design for review.*
+
+- Identity: `skills`
+- Kind: component
+- Channels: agent
+- Source: [skills.yaml](skills.yaml)
+
+## Honest review status
+
+- Requirement: An exported review artifact must not imply that a reviewer approved a map or implementation.
+- Design response: Comments and exports are not approval. Approval requires reconciled feedback and contributions, resolved blocking questions, and the exact source, review, comments, and map-input tuple. Implementation checks remain separate.
+- Applies to: skills, review-runtime, viewer
+
+## Agent session setup
+
+*Registers ACStack skill commands and adds rules for planning, coding, and checking changes to the agent's session.*
+
+- Identity: `host`
+- Kind: component
+- Channels: agent
+- Source: [host.yaml](host.yaml)
+
+
+
+## CLI package
+
+*Ships the review command, local server, and browser review interface.*
+
+- Identity: `cli`
+- Kind: component
+- Channels: none
+- Source: [cli.yaml](cli.yaml)
+
+
+
+## Review command and server
+
+*Reads and validates authored YAML, serves the browser review interface, saves comments, and exports Markdown.*
+
+- Identity: `review-runtime`
+- Kind: component
+- Channels: cli, web
+- Source: [review-runtime.yaml](review-runtime.yaml)
+
+## Offline review
+
+- Requirement: Reviewers can inspect the design without uploading project details or fetching browser assets.
+- Design response: The review command and server read bounded local source files and embed validated graph data with bundled browser assets, without uploading the design. Agent-side reads of GitHub-bound maps still require network access.
+- Applies to: review-runtime, viewer, design-source
+
+## Honest review status
+
+- Requirement: An exported review artifact must not imply that a reviewer approved a map or implementation.
+- Design response: Comments and exports are not approval. Approval requires reconciled feedback and contributions, resolved blocking questions, and the exact source, review, comments, and map-input tuple. Implementation checks remain separate.
+- Applies to: skills, review-runtime, viewer
+
+## Browser review interface
+
+*Receives the prepared design graph and syncs comments with the local server.*
+
+- Identity: `viewer`
+- Kind: component
+- Channels: web
+- Source: [viewer.yaml](viewer.yaml)
+
+## Offline review
+
+- Requirement: Reviewers can inspect the design without uploading project details or fetching browser assets.
+- Design response: The review command and server read bounded local source files and embed validated graph data with bundled browser assets, without uploading the design. Agent-side reads of GitHub-bound maps still require network access.
+- Applies to: review-runtime, viewer, design-source
+
+## Honest review status
+
+- Requirement: An exported review artifact must not imply that a reviewer approved a map or implementation.
+- Design response: Comments and exports are not approval. Approval requires reconciled feedback and contributions, resolved blocking questions, and the exact source, review, comments, and map-input tuple. Implementation checks remain separate.
+- Applies to: skills, review-runtime, viewer
+
+## Authored design files
+
+*Holds the local YAML and supporting Markdown that the review server reads.*
+
+- Identity: `design-source`
+- Kind: store
+- Channels: none
+- Source: [store.yaml](store.yaml)
+
+Authored design files define the design in the local checkout; GitHub hosts a published copy only if the developer chooses to share it.
+
+- Local files drive the review
+    - The Review command and server read the local YAML and supporting Markdown to generate the browser view and Markdown companion
+    - Revise these source files when the design changes
+    - Local browser review and saved comments work without publishing design files to GitHub
+- GitHub hosts a published copy
+    - The Project developer can commit and push the generated companion for others to read on GitHub
+    - The developer can publish the companion alone or include the authored source files
+    - GitHub does not replace the local files read by the review server or automatically receive its saved comments
+    - This diagram's publication arrow is separate from using GitHub issues as a map tracker
+- Git ignore rules control tracking, not publication
+    - Ignore rules exclude matching untracked files from ordinary staging
+    - Removing an ignore rule does not stage, commit, or push anything
+    - Already tracked files remain tracked even if an ignore rule later matches them
+    - New project designs under `.acstack/` stay ignored by default; this public example is tracked separately
+
+
+## Offline review
+
+- Requirement: Reviewers can inspect the design without uploading project details or fetching browser assets.
+- Design response: The review command and server read bounded local source files and embed validated graph data with bundled browser assets, without uploading the design. Agent-side reads of GitHub-bound maps still require network access.
+- Applies to: review-runtime, viewer, design-source
+
+## GitHub
+
+*Hosts a published copy of the Markdown companion when the developer chooses to share it.*
+
+- Identity: `github`
+- Kind: external-system
+- Channels: web
+- Source: [github.yaml](github.yaml)
+
+Authored design files define the design in the local checkout; GitHub hosts a published copy only if the developer chooses to share it.
+
+- Local files drive the review
+    - The Review command and server read the local YAML and supporting Markdown to generate the browser view and Markdown companion
+    - Revise these source files when the design changes
+    - Local browser review and saved comments work without publishing design files to GitHub
+- GitHub hosts a published copy
+    - The Project developer can commit and push the generated companion for others to read on GitHub
+    - The developer can publish the companion alone or include the authored source files
+    - GitHub does not replace the local files read by the review server or automatically receive its saved comments
+    - This diagram's publication arrow is separate from using GitHub issues as a map tracker
+- Git ignore rules control tracking, not publication
+    - Ignore rules exclude matching untracked files from ordinary staging
+    - Removing an ignore rule does not stage, commit, or push anything
+    - Already tracked files remain tracked even if an ignore rule later matches them
+    - New project designs under `.acstack/` stay ignored by default; this public example is tracked separately