acstack 0.50.4 → 0.52.0

package/skills/archive/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: archive
-description: Close out a cleared map – one whose frontier is empty with no fog and no claims left – by verifying the durable residue, meaning what the effort leaves behind in living specs, ADRs and the glossary, was extracted, then closing the root and disposing of the nodes per workflow.maps.persist. Invoke when a map has just been cleared, when the last node on a map resolves, or when the user asks to archive or close out a map. Refuses and asks first if anything is still open. Also archives legacy acstack/changes/ directories from the pre-map workflow.
+description: Close out a cleared map – one whose frontier is empty with no fog and no claims left – by verifying the durable residue, meaning what the effort leaves behind in living specs, ADRs and the glossary, was extracted, then closing the root and disposing of the nodes per workflow.maps.persist. Invoke when a map has just been cleared, when the last node on a map resolves, or when the user asks to archive or close out a map. Refuses and asks first if anything is still open. Also archives legacy .acstack/changes/ directories from the pre-map workflow.
 argument-hint: "[map or legacy change name]"
 ---
 
@@ -14,24 +14,16 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 ## Purpose
 
-A map is scaffolding. It exists to clear fog – the questions nobody could
-state precisely when the effort started.
-
-Once the fog clears, the answers belong in living specs, ADRs and the
-glossary, not in a second copy that drifts. That is the residue – what
-survives the map.
-
-Archive verifies the residue reached those three places. It then closes the
-map's root node and disposes of the rest.
+Archive verifies implemented specs, durable decisions, and retained review evidence before closing the root and disposing of temporary map nodes.
 
 ## Step 1: Locate the map
 
 If `$ARGUMENTS` names a map, use it. Otherwise list maps on the configured
-tracker (`workflow.maps.tracker`): `ls acstack/maps/` on the files backend,
+tracker (`workflow.maps.tracker`): `ls .acstack/maps/` on the files backend,
 `gh label list --search "map:" --json name` on GitHub.
 
 If exactly one, use it. If several, ask. If `$ARGUMENTS` names a legacy
-`acstack/changes/` directory instead, jump to Legacy below.
+`.acstack/changes/` directory instead, jump to Legacy below.
 
 ## Step 2: Verify no open work remains
 
@@ -64,8 +56,23 @@ frontier only lists nodes with no unresolved blockers. Two nodes that block
 each other show an empty frontier while both questions stay open. An empty
 frontier is therefore no proof of a cleared map.
 
-If anything remains, WARN with what it is and ask for confirmation –
-archiving an uncleared map throws away open questions.
+If anything remains, stop and list the fog, open questions, or claims.
+Ask the user to resolve them or explicitly mark dropped scope out of scope before retrying.
+Do not dispose of an uncleared map.
+
+For a bound design, read the root's `Design entry` reference and run:
+
+```bash
+~/.claude/acstack/bin/acstack design-review status <entry>
+```
+
+- Require returned `planning.tracker` and `planning.map` to match the map being archived
+- Stop on a missing or different binding; another map's approval does not authorize this archive
+- Require `approval.valid: true` for the current exact revision tuple
+- Require completed reconciliation of saved feedback and current map contributions
+- Return invalid approval or unresolved reconciliation to `/acstack:design-doc`
+- Recheck after source, saved comments, or contribution inputs change
+- Never promote historical approval or migrate legacy data during archive
 
 ## Step 3: Extract the residue
 
@@ -76,16 +83,22 @@ On GitHub, compose the walk per `trackers/github.md`.
 Check each resolution left what it should have:
 
 1. **Living specs** – behaviour the effort built should already be in
-   `acstack/specs/` via commit-time sync. Spot-check the affected domains.
+   `.acstack/specs/` via commit-time sync. Spot-check the affected domains.
+
+   Verify against source and verification evidence, not proposals copied from map nodes.
    Fix gaps on sight per the Spec Correction Protocol.
 
-2. **ADRs and glossary** – invoke `record-context` for any resolved decision
-   that meets the bar and that nobody recorded. This is the last chance.
+2. **ADRs and glossary** – apply `record-context`'s existing tests to unrecorded decisions.
+   An ADR requires a hard-to-reverse, surprising decision with a real trade-off.
+   A glossary entry requires an agreed term; neither is the common outcome.
 
-3. **Out-of-scope nodes** – report them. A scope boundary is worth the user
-   hearing once more before the map disappears.
+3. **Scope and provenance** – record dropped scope, unresolved limits, and reopening conditions before disposal.
+   Keep durable node identities and their provenance with the affected specs or decision records.
 
-4. **The decision log** – read `<main checkout>/acstack/.decisions/<name>.tsv`
+   Preserve enough context to trace implemented behavior back to its decisions without retaining proposals as requirements.
+   Stop if unresolved scope still needs a decision rather than an explicit out-of-scope resolution.
+
+4. **The decision log** – read `<main checkout>/.acstack/decision-logs/<name>.tsv`
    if it exists. The main checkout is `dirname` of `git rev-parse
    --path-format=absolute --git-common-dir`.
 
@@ -117,47 +130,51 @@ If you reached this skill on your own after a map cleared, name what you
 will delete or move. Then wait for the user's go-ahead. Deletion is
 irreversible and they never asked for it.
 
-`workflow.maps.persist` in `acstack/project.yaml` decides (default `false`):
+`workflow.maps.persist` in `.acstack/project.yaml` decides (default `false`):
 
 | Value             | Action                                                       |
 | ----------------- | ------------------------------------------------------------ |
-| `false` (default) | delete `acstack/maps/<name>/`                                 |
-| `true`            | move the nodes to `acstack/archive/[YYYY-MM-DD]-[name]/nodes/` |
+| `false` (default) | delete `.acstack/maps/<name>/`                                 |
+| `true`            | move the nodes to `.acstack/archive/[YYYY-MM-DD]-[name]/nodes/` |
 
 Default is delete because keeping the nodes leaves a second copy of every
 decision, and the two drift. On the GitHub tracker there is nothing to
 dispose – closed issues are already the archive.
 
-Also dispose of `acstack/handoffs/<name>/` if it exists. Consumed handoffs
-hold conversation content and should not outlive the map they served.
+Retain these records independently of `workflow.maps.persist`:
+
+- Authored design entries and referenced source files
+- Canonical `review.json` files, posted feedback, reconciliation, and exact-revision approval evidence
+- Imported legacy history and original `.acstack/alignment-packs/` artifacts
+- Main-checkout `.acstack/decision-logs/<name>.tsv` files
+- Handoffs that contain review evidence or provenance not retained elsewhere
 
-Also dispose of `acstack/alignment-packs/<safe-map>/` if it exists. Alignment
-packs are local review artifacts. Step 3 already verified the durable residue.
+Never recursively delete alignment, review, decision-log, or handoff directories as archive cleanup.
+Do not invoke a cleanup helper that erases those records.
 
-Delete the map's decision log, `<main checkout>/acstack/.decisions/<name>.tsv`,
-on either tracker. Step 3 already extracted what it held. Leave the directory
-and its `.gitignore` for the next map.
+If a retained source or review record sits inside the proposed node disposal path, stop and resolve its safe retention first.
+Respect native Git ignore rules; never force-add private records.
 
 ## Step 6: Report
 
 - Nodes resolved / out-of-scope counts
 - Residue: domains spot-checked, ADRs and glossary entries written
-- Disposal: deleted, or archive path
+- Disposal: node deletion or archive path, plus retained review evidence and provenance
 - Reminder: commit with `/acstack:commit`
 
-## Legacy: archiving a `acstack/changes/` directory
+## Legacy: archiving a `.acstack/changes/` directory
 
 The pre-map workflow created changes that hold proposal.md, design.md and
 tasks.md. They still archive the old way, so an upgrade never strands work:
 
 1. Read the change's artifacts. Derive the affected domains from the file
-   paths in `tasks.md` via `acstack/domain-map.yaml`.
+   paths in `tasks.md` via `.acstack/domain-map.yaml`.
 
 2. For each domain, merge what the feature ADDED, MODIFIED or REMOVED into
-   `acstack/specs/[domain]/spec.md`.
+   `.acstack/specs/[domain]/spec.md`.
 
 3. Write a `delta.md` into the change directory.
 
     Then run the CLI's `acstack archive <name>`. It moves the artifacts,
-    delta included, to `acstack/changes/archive/[YYYY-MM-DD]-[change-name]/`.
-    It also removes the change from `acstack/changes/`.
+    delta included, to `.acstack/changes/archive/[YYYY-MM-DD]-[change-name]/`.
+    It also removes the change from `.acstack/changes/`.

package/skills/bootstrap/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bootstrap
-description: Multi-pass AI crawl to generate initial living specs from the existing codebase. Use when acstack/specs/ domains need their initial spec.md files bootstrapped from code.
+description: Multi-pass AI crawl to generate initial living specs from the existing codebase. Use when .acstack/specs/ domains need their initial spec.md files bootstrapped from code.
 argument-hint: "[domain-names (optional)]"
 disable-model-invocation: true
 ---
@@ -15,9 +15,9 @@ Consider the user input before you proceed, if it is not empty.
 
 ## Purpose
 
-This skill bootstraps cumulative living specs in `acstack/specs/`. It crawls the existing codebase with multiple independent AI passes. It then merges the passes and validates the results.
+This skill bootstraps cumulative living specs in `.acstack/specs/`. It crawls the existing codebase with multiple independent AI passes. It then merges the passes and validates the results.
 
-**IMPORTANT**: This is a one-time bootstrapping operation. Only run when `acstack/specs/` domains have no `spec.md` files yet.
+**IMPORTANT**: This is a one-time bootstrapping operation. Only run when `.acstack/specs/` domains have no `spec.md` files yet.
 
 ## Your role: orchestrator only
 
@@ -33,9 +33,9 @@ Your job is to:
 
 ## Pre-flight check
 
-1. Read `acstack/domain-map.yaml` to get the list of domains and their file path mappings.
+1. Read `.acstack/domain-map.yaml` to get the list of domains and their file path mappings.
 2. If `$ARGUMENTS` specifies domain names, filter to only those domains.
-3. Check if any `acstack/specs/*/spec.md` files already exist:
+3. Check if any `.acstack/specs/*/spec.md` files already exist:
     - If specs exist, warn the user. Ask for confirmation before overwriting.
     - If no specs exist, proceed automatically.
 
@@ -98,7 +98,7 @@ Launch a single subagent to apply validated corrections from Phase 3.
 
 ## Phase 5: human review (pass 9)
 
-Present a summary to the user. Ask: "Review the specs in `acstack/specs/`. Want to edit any domain before finalizing?"
+Present a summary to the user. Ask: "Review the specs in `.acstack/specs/`. Want to edit any domain before finalizing?"
 
 ## Phase 6: finalization (pass 10)
 

package/skills/bridge/SKILL-VM.md

@@ -10,7 +10,7 @@
   binds `127.0.0.1:19988` on this host.
 
 - `agent-browser` (installed per the `browser-verify` skill) pointed at
-  that endpoint via `agent-browser.json`.
+  that endpoint via `.acstack/agent-browser.json`.
 
 - `vm-free-port.sh` for clearing a stuck port 19988 after a dropped
   session.
@@ -42,12 +42,21 @@ and is driving a real Chrome on the laptop.
 
 See the `browser-verify` skill for the install command.
 
-### 2. Create `agent-browser.json` in each project root
+### 2. Create `.acstack/agent-browser.json` in each configured project
 
 ```json
 { "cdp": "19988" }
 ```
 
+Run `~/.claude/acstack/bin/acstack project-data ensure` after creating `.acstack/`.
+Select the config explicitly from the project root before browser commands:
+
+```bash
+export AGENT_BROWSER_CONFIG="$(pwd)/.acstack/agent-browser.json"
+```
+
+For manual CDP checks without project configuration, use `agent-browser --cdp 19988 ...` instead; do not pass a missing config.
+
 ### 3. Accept the laptop's key
 
 Append the laptop's SSH public key to `~/.ssh/authorized_keys`.

package/skills/bridge/SKILL-WINDOWS.md

@@ -276,9 +276,9 @@ pages.
 The opener shows a page from a VM in this laptop's default browser. It is a
 second service, not part of the bridge.
 
-The bridge carries CDP to a Chrome the extension drives. The opener takes a
-document and opens a tab. See `docs/adr/0006-document-opener-service.md` for
-why these stay apart.
+The bridge carries CDP to a Chrome the extension drives. The opener opens
+documents in the default browser without requiring an automation session.
+Separate services let either function run without the other.
 
 Two tasks run it:
 

package/skills/browser-verify/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: browser-verify
-description: How to interact with a browser for frontend verification using agent-browser CLI and CDP. ALWAYS use when UI or frontend files are modified and workflow.frontend_verification is true in acstack/project.yaml. Also use before running agent-browser commands, when element refs go stale, when CDP connection fails, or when verifying UI behavior. Covers all commands (snapshot, screenshot, click, fill, type), element ref strategy, DOM staleness rules, selector priority, and remote/headless/local environment troubleshooting.
+description: How to interact with a browser for frontend verification using agent-browser CLI and CDP. ALWAYS use when UI or frontend files are modified and workflow.frontend_verification is true in .acstack/project.yaml. Also use before running agent-browser commands, when element refs go stale, when CDP connection fails, or when verifying UI behavior. Covers all commands (snapshot, screenshot, click, fill, type), element ref strategy, DOM staleness rules, selector priority, and remote/headless/local environment troubleshooting.
 ---
 
 # Browser helpers
@@ -13,11 +13,11 @@ For setup (installing agent-browser, creating config files, scaffolding knowledg
 
 ## Project configuration
 
-Read `acstack/project.yaml` for:
+Read `.acstack/project.yaml` for:
 
 - `frontend.directory` – frontend source directory
 - `frontend.dev_server_url` – dev server URL
-- `frontend.helpers_dir` – path to verification knowledge (default: `<frontend.directory>/tests/helpers/`)
+- `frontend.helpers_dir` – helper programs, not verification metadata
 - `frontend.browser.mode` – the browser environment this project prefers: `remote`, `headless`, or `local`
 - `frontend.browser.fallback` – set it to `none` to forbid any other mode standing in. Every other value allows one
 - `frontend.browser.cdp_port` – CDP port. Default `19988` for `mode: remote` (Playwriter bridge), `9555` for `headless`/`local`.
@@ -181,7 +181,16 @@ Omit `--headless` to see the browser. Useful during development.
 
 ## agent-browser command reference
 
-All commands assume `agent-browser.json` exists in the project root.
+For configured verification, explicitly select the absolute `.acstack/agent-browser.json` path before running the commands below:
+
+```bash
+export AGENT_BROWSER_CONFIG="$(pwd)/.acstack/agent-browser.json"
+```
+
+- Run this from the project root only when the file exists; alternatively pass `--config /absolute/project/.acstack/agent-browser.json`
+- Do not rely on root config autodiscovery
+- Manual CDP quality checks remain available without project configuration or a configured browser mode
+- For those checks, omit the missing config and use `agent-browser --cdp <port> ...` with the explicitly chosen endpoint
 
 | Command | Purpose |
 |---------|---------|
@@ -225,5 +234,5 @@ The snapshot gives you accessible names and roles automatically. Use these to fi
 - **frontend-verifier agent** uses agent-browser for configured real-browser verification – this skill is its reference
 - **verification owner** completes static and design checks under `skills/implement/design-pass.md` before configured browser verification
 - **/acstack:setup** runs the setup interviews (install, config, knowledge base scaffolding) and offers a fix for each row the health check fails
-- **`acstack config check`** audits the browser infrastructure and changes nothing
+- **`acstack config check`** reports browser infrastructure gaps without changing browser settings
 - **/acstack:quick-fix** uses agent-browser for visual verification of bug fixes

package/skills/code-review/SKILL.md

@@ -7,10 +7,12 @@ description: Apply Linus Torvalds code philosophy – eliminate special cases, p
 
 Channel the mindset of Linux's creator: be direct, eliminate over-engineering, and prioritize simplicity.
 
+Read `../../output-styles/ac-writing-style.md` relative to this skill directory; apply its shared standard to code design as well as explanations.
+
 ## Core Principles
 
 - **"Good Taste"**: Eliminate special cases through better design rather than adding conditionals
-- **Simplicity First**: If it needs more than 3 levels of indentation, redesign it
+- **Simplicity First**: Simplify tangled control flow and mixed responsibilities; cite concrete complexity rather than indentation or line counts
 - **Data Structures Matter**: "Bad programmers worry about code. Good programmers worry about data structures"
 - **Pragmatism**: Solve real problems, not imaginary ones
 
@@ -27,7 +29,11 @@ When reviewing code or making design decisions, ask these questions in order:
 
 1. **Is this a real problem?** – Reject over-design
 2. **Is there a simpler way?** – Always seek the simplest solution
-3. **What are the core data relationships?** – Design around data flow
+3. **What are the core data relationships?** – Read connected callers and dependencies, not only the diff
+    - Do boundaries group coherent responsibilities, with peer components at comparable abstraction levels?
+    - Do small, useful interfaces hide real complexity (deep modules), without exposing internals or adding pass-through layers?
+    - Do names match meaning and structure follow responsibility rather than folder layout?
+    - Do not force nesting or wrappers; judge effects on callers, not line count or indirection
 4. **Can we eliminate special cases?** – Redesign to avoid if/else branches
 5. **Does complexity match problem severity?** – Don't build rockets to swat flies
 

package/skills/commit/SKILL.md

@@ -45,24 +45,25 @@ For each planned commit:
 
 **This step is non-negotiable.** After drafting the commit message but BEFORE creating the commit, spec sync runs automatically.
 
-Read `acstack/project.yaml` – if `workflow.spec_sync` is `true` (or not explicitly `false`), run spec sync:
+Read `.acstack/project.yaml` – if `workflow.spec_sync` is `true` (or not explicitly `false`), run spec sync:
 
-1. Read `acstack/domain-map.yaml` (if exists)
+1. Read `.acstack/domain-map.yaml` (if exists)
 2. Map staged files to spec domains
-3. For each affected domain where `acstack/specs/[domain]/spec.md` exists:
+3. For each affected domain where `.acstack/specs/[domain]/spec.md` exists:
     - Analyze what the staged changes add, modify, or remove
     - Generate lightweight ADDED/MODIFIED/REMOVED entries
     - Update the domain's spec.md
 4. Refresh `DESIGN.md`, per Step 2 of the `sync` skill
-5. Stage any updated spec files
+5. Stage updated specs only when native `.gitignore` rules allow tracking
+    - Keep ignored specs updated locally; never force-add them or change the Git index to bypass this choice
     - Stage `DESIGN.md` and `.impeccable/design.json` too when the refresh ran
-6. Include spec updates in the commit
+6. Include only opted-in spec updates in the commit
 7. Flag unmapped source files and prompt user to map them
 
 **Skip spec sync ONLY when:**
 
 - `workflow.spec_sync` is explicitly `false` in project.yaml
-- No `acstack/domain-map.yaml` exists
+- No `.acstack/domain-map.yaml` exists
 - Changed files don't match any domain
 - Changes are docs/config only (no behavioral changes)
 - No spec.md exists for affected domains (don't create from scratch here)

package/skills/compact-and-continue/SKILL.md

@@ -55,7 +55,7 @@ instead – in your final message, or through your host's agent-messaging tool
 or compacts.
 
 A child session would write the lead's quiet marker and the shared
-`acstack/HANDOFF.md` anchor. Both belong to the lead alone.
+`.acstack/HANDOFF.md` anchor. Both belong to the lead alone.
 
 Five facts sit behind that command, measured on Claude Code 2.1.241. Each one
 names a way the command has already been got wrong:
@@ -99,8 +99,8 @@ something by running a command, it should run the command.
 | Map state and reading order | `~/.claude/acstack/bin/acstack node walk --map <name>` (reading order of the map) |
 | What can be worked next     | `~/.claude/acstack/bin/acstack node frontier --map <name>` (what is workable now) |
 | Files in flight             | `git status --short` and `git diff`                                               |
-| Test baseline, last result  | `.test-baseline`, then run the suite                                              |
-| What the code does          | the living specs in `acstack/specs/`                                              |
+| Test baseline, last result  | `.acstack/.test-baseline`, then run the suite                                              |
+| What the code does          | the living specs in `.acstack/specs/`                                              |
 
 On GitHub, `--map` refuses – pipe `gh issue list` into `--stdin` per the
 map skill's `trackers/github.md`.
@@ -141,7 +141,7 @@ not optional.
 
 ## Write the anchor
 
-Write `acstack/HANDOFF.md`. The frontmatter is **mandatory and machine-read**.
+Write `.acstack/HANDOFF.md`. The frontmatter is **mandatory and machine-read**.
 The hook ignores any file without the marker, so it never touches a user's own
 unrelated `HANDOFF.md`.
 
@@ -216,8 +216,9 @@ note.
 Tell them to run that `/compact` line, then to type `continue`. The hook
 re-injects the anchor and retires it, so the anchor never loads twice.
 
-`acstack/HANDOFF.md` is transient working state. If `.gitignore` does not cover
-it, say so. The file holds conversation content, so nobody should commit it.
+`.acstack/HANDOFF.md` holds conversation content and stays local by default.
+Run `~/.claude/acstack/bin/acstack project-data ensure` after creating `.acstack/`.
+Warn if user exceptions expose the anchor or consumed handoffs to tracking.
 
 ## Notes
 
@@ -229,8 +230,8 @@ it, say so. The file holds conversation content, so nobody should commit it.
     skill moves the work to a genuinely new session
 
 - **Consume-once.** The hook retires the anchor as it injects it, moving it to
-  `acstack/handoffs/<map>/<created>.md` (legacy
-  `acstack/changes/<name>/handoffs/` when that directory still exists).
+  `.acstack/handoffs/<map>/<created>.md` (legacy
+  `.acstack/changes/<name>/handoffs/` when that directory still exists).
   Collisions get a `-2` suffix
 
 - **Subagents and teammates have isolated context.** This protects the

package/skills/design-doc/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: design-doc
+description: Author a structured design document and review it through a live local or SSH connection that saves comments for the agent.
+---
+
+# Author and review a design document
+
+Author one design source for interactive browser review and a GitHub-readable Markdown companion with Mermaid.
+The React Flow browser view supports drill-down and comments saved on the agent's device.
+
+```mermaid
+flowchart LR
+    A[Agree on the design scope] --> B[Author entry and element files]
+    B --> C[Validate and review in the browser]
+    C -->|invalid source| B
+    C --> D[Save comments for the agent]
+    M[Map contributions when bound] --> E[Reconcile feedback and contributions]
+    D --> E
+    E -->|revise| B
+    E -->|ready| F[Approve the exact revision]
+    F --> G[Implement and retain review evidence]
+    G -->|review inputs change| B
+```
+
+## Agree on the design scope
+
+- Read the writing and visual-docs skills before authoring prose
+- Inspect the source to establish current responsibilities
+- Ask the user about unresolved product decisions before inventing behavior
+- Distinguish existing behavior from proposed changes throughout the document
+- Open with the proposed change, the review questions, and the trade-offs the reviewer must judge
+- Use the worked journey to show who does what and where the proposal changes today's flow
+- Use `examples/design-doc/acstack/` as the worked example
+
+## Author entry and element files
+
+- Default new project designs to `.acstack/designs/<id>/design.yaml`, unless the user chooses another location
+- Keep the entry and its referenced files in one directory tree
+- Use stable IDs matching `[a-zA-Z][a-zA-Z0-9_-]{0,79}`
+- Give the entry `id`, `name`, `summary`, and an `elements` array of relative YAML paths
+- Optionally add `detail` with a relative Markdown path for the overview and worked journey
+- Give each element `id`, `name`, `summary`, and `kind`
+- Write each summary as a standalone responsibility, not a code fragment or a list of implementation steps
+- Keep peer elements at comparable levels of abstraction
+- Reuse element names in the overview, relationships, and detail; connect readable names to code identifiers when they differ
+- Model only real entities; the document overview is context, not an architecture node
+- Choose `kind` from `actor`, `component`, `store`, or `external-system`
+    - An actor participates from outside the system, such as a person or an external autonomous agent
+    - An agent built into the system is a component
+- Use optional `parent` only for genuine containment, not dependencies or shared concerns
+    - Each component represents one entity, shown as either a collapsed card or an expanded container, never both
+    - Keep relationships across containers explicit rather than inventing a shared owner
+    - Let nesting express containment without a duplicate "Contains" or "Embeds" arrow
+    - Do not draw an arrow between an ancestor and its descendant; nesting already expresses containment
+    - Show interactions between the responsible components rather than between a container and its contents
+- Use optional `detail` to reference supporting Markdown
+    - Repository paths and other source metadata are optional context in that Markdown, not prerequisites for a design
+- Use optional `channels` for zero or more software interfaces
+    - Allowed values: `web`, `mobile`, `desktop`, `cli`, `agent`, `email`, `sms`, and `voice`
+    - A web app, CLI, or agent can be its own component
+    - Put interface labels on the software that provides them, not on an actor because that actor uses them
+    - Channels describe access to software; channels do not replace elements
+- Declare each relationship identically in both endpoint files under `relationships`
+    - Include `id`, `from`, `to`, `direction`, and `label`
+    - Choose `direction` from `one-way` or `bidirectional`
+    - Keep canonical `from` and `to` identical in both copies, including bidirectional relationships
+    - Read every arrow as source → verb → target: `Checkout CLI → Reads → Order files`
+    - Use the acting entity as `from`; reading files points from the reader to the store, not along the returned data
+    - Keep that action convention consistent throughout the document
+    - Use separate arrows when opposite actions need different labels
+    - Use `bidirectional` only when the same label accurately describes both directions, not merely because a workflow includes feedback
+- Keep kind, concern, and channel separate: what an entity is, what requirement spans entities, and how interactions occur
+- Put cross-element requirements in the entry's optional `concerns` array
+    - Include `id`, `name`, `elements`, `requirement`, and `response`
+    - Name at least two affected element IDs
+    - Explain both the requirement and the design response in meaningful prose
+    - The viewer shows these explanations in each affected element's drawer
+
+```yaml
+id: checkout-design
+name: Checkout design
+summary: The checkout CLI reads orders from a local store.
+elements: [checkout.yaml, orders.yaml]
+concerns:
+  - id: local-data
+    name: Local data
+    elements: [checkout, orders]
+    requirement: Orders must stay on the developer's machine.
+    response: The CLI reads local files without a network service.
+```
+
+```yaml
+# checkout.yaml
+id: checkout
+name: Checkout CLI
+summary: Inspects locally stored orders.
+kind: component
+channels: [cli]
+relationships:
+  - id: read-orders
+    from: checkout
+    to: orders
+    direction: one-way
+    label: Reads
+```
+
+```yaml
+# orders.yaml
+id: orders
+name: Order files
+summary: Persist the orders inspected by the checkout CLI.
+kind: store
+relationships:
+  - id: read-orders
+    from: checkout
+    to: orders
+    direction: one-way
+    label: Reads
+```
+
+## Validate and start review
+
+```sh
+~/.claude/acstack/bin/acstack design-doc path/to/design.yaml \
+  --markdown /tmp/design-review.md
+```
+
+- Keep the command running while the reviewer works
+- Open the printed localhost URL when the browser and agent share a device
+- On separate devices, run the printed SSH forwarding command from the browser's device, then open the localhost URL
+- Use `--port <port>` when another review already uses the default port
+- Choose `--orientation left-to-right` for horizontal flow in the browser and Mermaid; the default is `top-to-bottom`
+- Changing orientation preserves source identity, comments, and approval
+- Use a new Markdown path to protect existing files
+- Keep Markdown beside source files when its relative source links must resolve on GitHub
+- Generate the companion from the same YAML and supporting Markdown; revise the source instead of hand-editing its Mermaid
+- Fix validation errors before asking the user to review
+- Keep each source file within 256 KiB and the document within 4 MiB
+- Keep the document within 200 elements, 100 concerns, and 200 relationships per element
+- Referenced paths cannot escape the entry directory, including through symlinks
+
+## Review the design and saved feedback
+
+- Review through the running server rather than an exported HTML file
+- Read the document overview and worked journey separately from the architecture entities
+- Select elements to read their responsibilities, types, channels, and concern explanations
+- Check that each entity appears once, whether collapsed or expanded
+- Inspect both collapsed and expanded views at a readable zoom
+    - Keep related elements close, with consistent padding around their group
+    - Prefer shared card edges for related elements; allow connector bends around headers instead of unnecessary staggering
+    - Reserve room for labels without spreading unrelated groups apart
+    - Compare width, height, and text readability; a smaller area alone can hide a taller diagram
+- Read every relationship aloud as source → verb → target
+- Inspect containment and crosscutting relationships before reviewing implementation detail
+- Answer the opening review questions and discuss the stated trade-offs
+- Review the generated Markdown companion on GitHub when useful
+- GitHub publication remains separate from the live comment connection
+- Use human feedback as the clarity loop; code tests do not establish whether the explanation makes sense
+- Choose Send to agent to finish pending saves and copy the feedback prompt
+- Copy the displayed prompt manually if the browser denies clipboard access
+- Paste the prompt into the agent's chat to request revisions
+- Read the prompt's `review.json` file and authored design entry
+- Resolve comment targets against the authored design to recover names and context
+- Use the developer's comments as requests to revise the design
+- Retry a failed save before closing the review
+- Preserve local edits when the server reports a conflicting revision
+- Edit the authored files following feedback, then restart the review for the changed design
+- Keep earlier feedback with its original design version rather than silently moving comments to changed text
+- Comments do not approve a design or authorize implementation
+- Approval records the exact authored source, ordered saved comments, and current map contributions
+
+## Reconcile and approve a map-linked design
+
+- Invoke this workflow from map for shared behavior, component boundaries, or data-flow decisions
+- Store `Design entry: <repository-relative-path>` in the map root body
+- Add `planning: {tracker: files | github, map: <name>}` to the entry
+- Use the same contribution format in files and GitHub node bodies
+- Put one fenced JSON array under `## Design contributions`
+
+```json
+[
+  {
+    "id": "interface-choice",
+    "designId": "checkout-design",
+    "targets": ["checkout"],
+    "statement": "The checkout component exposes the command interface"
+  }
+]
+```
+
+- Use document, element, relationship, or concern IDs as targets
+- Read `~/.claude/acstack/bin/acstack design-review status <entry>` for contribution keys and the exact revision tuple
+- Select older feedback with `--review-file <canonical-review.json>` when the source changed
+- Preserve the selected historical snapshot; reconciliation belongs to the current revision
+- Resolve blocking decision nodes or mark them out of scope
+- Surface contradictory proposals as decision nodes rather than choosing one silently
+- Write reconciliation input with the four status fields: `sourceRevision`, `reviewRevision`, `commentsDigest`, and `mapInputsDigest`
+- Add a `decisions` array with `comments`, `contributions`, `outcome`, and nonempty `rationale` in each decision
+- Reference each selected comment index and current contribution key exactly once
+- Choose `applied`, `retained`, or `needs-human`; `needs-human` keeps approval blocked
+- Run `~/.claude/acstack/bin/acstack design-review reconcile <entry> --input <json-file>` with the same optional `--review-file`
+- Empty feedback and contribution sets need no invented reconciliation
+- Reopen `~/.claude/acstack/bin/acstack design-doc <entry>` after authored source changes
+- Choose Approve this revision in the document details after reconciliation
+- Keep unposted drafts intact; approval saves only posted comment edits
+- Require `approval.valid: true` from status before implementation
+- Reopen the gate after authored source, saved feedback, or meaningful contribution inputs change
+- Presentation regeneration alone preserves approval
+- Keep `workflow.design_review` unchanged; it controls the separate frontend design pass
+
+## Import legacy review history explicitly
+
+- ACStack removes `map --map` and `align-viewer` without aliases
+- Author the new design first; the old planning graph cannot define its architecture
+- Keep map planning in `node walk`, `node frontier`, and `node diagram`
+- Use a nonsymlink legacy directory under `.acstack/alignment-packs/`
+- Write an explicit JSON mapping array of `{from: {type, id}, to: {type, id}}` pairs
+- Map every commented legacy target to a valid current target
+- Choose document context explicitly when a legacy target is ambiguous
+
+```sh
+~/.claude/acstack/bin/acstack design-review migrate <entry> \
+  --legacy-dir <path> --mapping <json-file> [--feedback <json-file>]
+```
+
+- Supply `--feedback` only for an explicit exported feedback JSON file
+- Migration reads saved pack versions, approvals, annotations, and the corresponding main-checkout decision log
+- Migration preserves original artifacts and decision logs byte-for-byte
+- Canonical `review.json` retains imported history, source fingerprints, and original comments, quotes, authors, timestamps, and provenance
+- Imported comments append to existing feedback; duplicate source comments import once
+- Historical approval remains history, never current approval
+- An actual import advances the comment revision once and invalidates prior effective approval
+- Repeating the same source and mapping imports nothing again
+- Invalid inputs fail before any write; publication uses the canonical review lock
+- Reconcile imported feedback and obtain current exact-revision approval before implementation or archive
+- Never migrate automatically at startup or archive
+- Retain design sources, canonical reviews, import history, and decision logs independently of `workflow.maps.persist`
+- Respect native Git ignore rules; never force-add private review records