acstack 0.50.4 → 0.52.0

package/skills/explore/SKILL.md

@@ -92,7 +92,7 @@ You have full context of the ACStack system. Use it naturally, don't force it.
 ### Check for context
 
 At the start, quickly check what exists – maps on the configured tracker
-(`ls acstack/maps/` on the files backend) and living specs
+(`ls .acstack/maps/` on the files backend) and living specs
 (`~/.claude/acstack/bin/acstack list --specs --json`).
 
 ### When no map exists

package/skills/grilling/SKILL.md

@@ -65,7 +65,7 @@ session.
 
 ## Presentation
 
-`workflow.grilling.questions` in `acstack/project.yaml` picks the mode:
+`workflow.grilling.questions` in `.acstack/project.yaml` picks the mode:
 
 | Value            | Behaviour                                                                            |
 | ---------------- | ------------------------------------------------------------------------------------ |
@@ -108,7 +108,7 @@ the tracker's `update` and `create` operations:
 
 2. Create a node for each new question the answer surfaced, with `answers`
    naming the node that surfaced it. Mark precise questions `open`; mark the
-   rest `fog`. If fog does not change the alignment artifact, write the
+   rest `fog`. If fog does not change the design, write the
    evidence or event that reopens it.
 
 3. Invoke the `record-context` skill for each resolution – it decides whether
@@ -127,8 +127,8 @@ belong in git:
 ```markdown
 ## Answer
 
-Map nodes stay out of git. `acstack/maps/` goes in `.gitignore`, because a
-node is working state that the map throws away once it clears.
+Map nodes stay local by default under `.acstack/maps/`.
+The user can opt in through native root `.gitignore` exceptions.
 
 The durable output is the living specs, the architecture decision records and
 the glossary. The `record-context` skill extracts each one as a node

package/skills/handoff/SKILL.md

@@ -54,7 +54,7 @@ its answer looks wrong. It says why a child must stop, and what it checks.
 ## First: is this yours to invoke?
 
 If the user asked for a handoff, proceed. If you invoke it on your own
-initiative, first read `workflow.handoff.self_invoke` from `acstack/project.yaml`.
+initiative, first read `workflow.handoff.self_invoke` from `.acstack/project.yaml`.
 
 If it is `false`, stop. Tell the user a handoff looks warranted and why. Ask
 permission.
@@ -102,8 +102,8 @@ 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`.
@@ -157,7 +157,7 @@ Its first line repeats the acknowledgement requirement verbatim, with
 Acknowledge before any other tool call. Run ~/.claude/acstack/bin/acstack handoff ack accept --file <this-file> "<one-line reason>", or ack decline --file <this-file> "<one-line reason>". The command writes <this-file>.ack, which the sender watches.
 ```
 
-This temp file is not `acstack/HANDOFF.md`, the `compact-and-continue` anchor.
+This temp file is not `.acstack/HANDOFF.md`, the `compact-and-continue` anchor.
 Never put this line into that anchor, which has to start with `---` frontmatter.
 
 Head the rest with the same skeleton the `compact-and-continue` anchor uses. The

package/skills/host/SKILL.md

@@ -29,7 +29,7 @@ Three terms, before they get used:
 ## Why this is per machine, not per project
 
 The answers go to the ACStack CLI's global config, never to
-`acstack/project.yaml`. Read [`notes.md`](notes.md) when the user asks why.
+`.acstack/project.yaml`. Read [`notes.md`](notes.md) when the user asks why.
 
 ## What this skill installs
 

package/skills/host/detect-host.sh

@@ -246,8 +246,8 @@ project_root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
 # verification, so we look for it at column zero only - `frontend:` nested under
 # some other key means something else entirely.
 has_frontend="false"
-if [ -n "$project_root" ] && [ -f "${project_root}/acstack/project.yaml" ]; then
-  if grep -q '^frontend:' "${project_root}/acstack/project.yaml" 2>/dev/null; then
+if [ -n "$project_root" ] && [ -f "${project_root}/.acstack/project.yaml" ]; then
+  if grep -q '^frontend:' "${project_root}/.acstack/project.yaml" 2>/dev/null; then
     has_frontend="true"
   fi
 fi

package/skills/host/notes.md

@@ -20,7 +20,7 @@ interface. That is a JSON file at `~/.config/acstack/config.json`, or under
 `$XDG_CONFIG_HOME` when you set that environment variable. Run
 `~/.claude/acstack/bin/acstack config path` to print the real location.
 
-They do not go in `acstack/project.yaml`.
+They do not go in `.acstack/project.yaml`.
 
 Project concerns stay in `project.yaml`. In particular
 `frontend.browser.mode` stays there as the *project's preference*, while
@@ -77,7 +77,7 @@ git worktrees and say so. An environment variable for an orchestrator that was
 never declared is worth a warning, not a refusal.
 
 **The host declares, the project prefers.** `host.browser.*` says what this
-machine can do. `frontend.browser.mode` in `acstack/project.yaml` says what the
+machine can do. `frontend.browser.mode` in `.acstack/project.yaml` says what the
 project would like.
 
 Today the only thing that compares the two is the ACStack command-line

package/skills/host/questions.md

@@ -22,7 +22,7 @@ What it reports, and what each field is evidence for:
 | `orca_topology.serve_unit_active` | A user-level service named exactly `orca` is running, which is the shape of a machine serving Orca to a viewer elsewhere. The name is an assumption: whatever provisions the server picks it, and nothing pins it yet. A unit installed under any other name reads here as "no server". The topology recommendation below then comes out `local` when this machine has Orca, and stays empty when it does not |
 | `claude_settings.orca_hooks_present` | `~/.claude/settings.json` mentions Orca somewhere. The match is a loose, case-insensitive search for that word anywhere in the file, so an unrelated path or permission entry containing it counts too – this is evidence that Orca has wired its hooks in, not proof |
 | `claude_settings.backup_exists` | `~/.claude/settings.json.bak` exists |
-| `project.root`, `project.has_frontend` | The git repository the current directory sits in, and whether its `acstack/project.yaml` configures a frontend |
+| `project.root`, `project.has_frontend` | The git repository the current directory sits in, and whether its `.acstack/project.yaml` configures a frontend |
 
 Several sections also carry a `recommended` field. That is the script's
 mechanical reading of the evidence above it and nothing more. It is a starting

package/skills/implement/SKILL.md

@@ -22,7 +22,7 @@ $ARGUMENTS
 ### 1. Find the work
 
 Check the configured tracker for maps (`workflow.maps.tracker` in
-`acstack/project.yaml`; the map skill's `trackers/` docs declare the
+`.acstack/project.yaml`; the map skill's `trackers/` docs declare the
 operations – files backend shown below).
 
 **A map exists** (or `$ARGUMENTS` names one):
@@ -40,12 +40,10 @@ off the root.
 
 Before claiming one, check whether the map is ready to build from:
 
-- If any `fog` node changes the alignment artifact, stop and point the user at
-  `/acstack:map`.
-- If `workflow.alignment_packs.approval_gate` is true and no reviewer approved
-  the alignment artifact, stop and point the user at `/acstack:map`.
-- If a `fog` node needs later evidence and does not change the artifact, leave
-  it on the map with its reopening trigger.
+- If any `fog` node changes the design, stop and point the user at `/acstack:map`
+- For a bound design, require `approval.valid: true` from `acstack design-review status <entry>`
+- If approval is invalid, return to `/acstack:design-doc` for reconciliation and exact-revision approval
+- If a `fog` node needs later evidence without changing the design, leave it with its reopening trigger
 
 If the frontier holds only `hitl` nodes – human in the loop, meaning a
 person must answer them – stop and point the user at `/acstack:map`. Those
@@ -57,7 +55,7 @@ small unit of work, and nothing has to declare it small.
 
 ### 2. Read project configuration
 
-Read `acstack/project.yaml` for build/test/lint commands and directory paths.
+Read `.acstack/project.yaml` for build/test/lint commands and directory paths.
 
 ### 3. Create feature branch
 
@@ -104,6 +102,15 @@ Nodes describe behaviour, not paths. **Resolve paths at claim time**.
 Investigate relevant source, callers, tests, and docs directly or through useful delegation.
 Pass discovered paths and requirements to any delegated agents to avoid repeated searches.
 
+- Before implementation, read the root node's `Design entry` reference when present
+- Run `acstack design-review status <entry>`
+- Require its `planning.tracker` and `planning.map` to match the active map before trusting its approval
+- Stop on a missing or different binding; an approval for another map does not authorize this work
+- Require `approval.valid: true`
+- Reconcile feedback and contributions through `/acstack:design-doc` when approval is invalid
+- Reopen review after source, saved comments, or contribution inputs change
+- Keep unsettled requirements in design/map records; living specs describe verified implementation
+
 ### 5. Execute within the claim
 
 Apply the shared Implementation discipline to the claimed node or bare request.
@@ -118,11 +125,11 @@ Apply the shared Implementation discipline to the claimed node or bare request.
 
 
 **Decision log**: on afk nodes, append one row per decision point to
-`<main checkout>/acstack/.decisions/<name>.tsv`. A decision point is a fork chosen, a
+`<main checkout>/.acstack/decision-logs/<name>.tsv`. A decision point is a fork chosen, a
 unit verified, a revert, or a blocker.
 
 Read `decision-log.md` before the first row. It holds how to find the main
-checkout, the columns, and the `.gitignore` the directory needs.
+checkout, the columns, and the root ignore baseline.
 
 **Parallelism**: use teams when independent nodes benefit from parallel work.
 Assign non-overlapping files, and schedule shared-file changes sequentially.
@@ -147,14 +154,14 @@ decision landed. With a map, then:
 - Classify anything the work surfaced:
     - Agent-clearable fog gets research, tests, or a throwaway prototype.
     - Design-changing fog becomes a `hitl` node and returns to `/acstack:map`.
-    - Local fog that does not change the artifact stays inside the claim notes.
-- Rebuild or rerun the alignment review when the work changes the artifact.
+    - Local fog that does not change the design stays inside the claim notes.
+- Reopen design review when source, saved comments, or contribution inputs change.
 - Recompute the frontier – resolutions unblock nodes.
 
 ### 7. Build verification
 
 After each node (and before ending the session), run the commands from
-`acstack/project.yaml`: build, full test suite, lint and typecheck. All must
+`.acstack/project.yaml`: build, full test suite, lint and typecheck. All must
 pass before claiming the next node.
 
 ### 8. Completion

package/skills/implement/decision-log.md

@@ -19,7 +19,7 @@ gets no row.
 ## Where the log lives
 
 The log is one file per map, in the main checkout:
-`<main checkout>/acstack/.decisions/<name>.tsv`. The `<name>` is the map name
+`<main checkout>/.acstack/decision-logs/<name>.tsv`. The `<name>` is the map name
 you pass to `--map`.
 
 Write it in the main checkout, never in a worktree. Removing a worktree
@@ -30,12 +30,13 @@ it. Find the main checkout from any worktree:
 main=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")
 ```
 
-Nobody commits the log. When you first create the `acstack/.decisions/`
-directory, write `.gitignore` inside it, containing a single line:
-
-```text
-*
-```
+- The root managed baseline ignores `.acstack/decision-logs/` by default
+- Check the main checkout's layout before creating or writing the log
+- If it still has legacy project records, stop with an actionable migration error
+- Tell the user to update installed tools, stop old agents and reviews, and explicitly migrate that checkout before restarting
+- Never move another checkout's records automatically or create a partial `.acstack/` there
+- On an already migrated main checkout, run `~/.claude/acstack/bin/acstack project-data ensure` before writing the log
+- Do not add a nested ignore file; native exceptions in the root `.gitignore` alone control tracking
 
 ## What a row holds
 
@@ -59,4 +60,4 @@ Never edit or delete a row. A wrong call gets a new row that supersedes it,
 and its `why` names the row it replaces.
 
 `/acstack:archive` reads the log before it closes the map. It hands lasting
-decisions to `record-context`, then deletes the log file.
+decisions to `record-context` and retains the original log independently of `workflow.maps.persist`.

package/skills/implement/design-pass.md

@@ -17,13 +17,22 @@ flowchart TD
 
 ## 0. Load design context before a UI edit (mandatory)
 
+- Frontend content fills its component's available width with equal horizontal padding; text wraps only after filling that width
+- Reuse the project's font family and a small type scale; equivalent text uses identical typography, with variations reserved for meaningful hierarchy
+- Align related elements to shared edges or baselines; use consistent spacing and indentation to show their hierarchy
+- Center status text and controls on the same row, including inside nested action groups; a centered parent does not align its children
+- Use shared spacing tokens or repeated gaps and padding; avoid one-off offsets that conceal a layout error
+- Reserve scrollbar space in scrollable panels so overflow never shifts text or changes line wrapping
+- Render dropdown menus with shared project components and tokens, not browser-native option menus or per-screen copies
+- Preserve keyboard navigation, screen-reader semantics, visible focus, dismissal, and viewport fit in shared dropdowns
+
 impeccable is a third-party design plugin. It holds the project's design context, meaning the files that state the design rules and the token definitions a UI file follows.
 
 Load that context before your first edit under `frontend.directory`. Load it once per task.
 
 **Check the design gate first**
 
-The design gate is the set of optional checks impeccable adds to acstack's pipeline. `workflow.design_review` in `acstack/project.yaml` turns the gate on. Ask acstack for the answer:
+The design gate is the set of optional checks impeccable adds to acstack's pipeline. `workflow.design_review` in `.acstack/project.yaml` turns the gate on. Ask acstack for the answer:
 
 ```bash
 ~/.claude/acstack/bin/acstack design-gate --json
@@ -85,7 +94,7 @@ impeccable installs its own PostToolUse hook, a check Claude Code runs right aft
 - Follow the shared Implementation discipline in `orchestrator/AGENTS.md`
 - The verification owner gathers the file list, completes static checks, and handles the detector
     - A delegated task-checker may own this work, but its presence is optional
-- Read `acstack/project.yaml` before deriving paths
+- Read `.acstack/project.yaml` before deriving paths
     - This pass requires a configured `frontend`
     - `frontend.directory` defaults to `frontend/` when omitted
     - If the project configures no frontend, warn that `frontend.directory` is missing and skip this pass
@@ -107,6 +116,11 @@ git status --porcelain -- <frontend.directory>
 
 ## 2. Run the design detector
 
+- Verify shared edges, text baselines, control centers, gaps, and padding before running the detector
+- Check nested groups as well as their parents; a shared row must not leave status text aligned to a button's top edge
+- Check normal, pending, error, and narrow layouts; compare bounding boxes or text baselines in the browser rather than judging a screenshot alone
+- Verify dropdowns reuse the shared component and project tokens before running the detector
+- Check arrow keys, Home/End, Enter/Space, Escape, Tab, focus, and viewport fit when a shared dropdown changes
 - Check the design gate before running the detector
 
 ```bash

package/skills/map/SKILL.md

@@ -23,7 +23,7 @@ frontier, claim, resolve and walk.
 Two backends ship in this skill's directory: `trackers/github.md` for repos
 with GitHub auth, and `trackers/files.md` as the fallback.
 
-`workflow.maps.tracker` in `acstack/project.yaml` (`github` or `files`) records
+`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.
@@ -33,7 +33,7 @@ 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
+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
@@ -51,7 +51,7 @@ still one map.
 
 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
+   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
@@ -64,11 +64,18 @@ still one map.
    sharp. The test is whether you can *state* the question precisely, not
    whether you can answer it.
 
-5. **Classify fog.** Read `alignment.md`. Blocking fog changes the alignment
-   artifact. Deferred fog does not.
+5. **Classify fog.** Read `alignment.md`. Blocking fog changes the design.
+   Deferred fog does not.
 
 ### Progressive materialisation
 
+Before deciding whether the map must persist:
+
+- Invoke `/acstack:design-doc` for shared behavior, component boundaries, or data-flow decisions
+- Apply that condition to conversation-only work as well as persisted maps
+- Skip design documents when those decisions are absent, including pure copyediting
+- When a design is required, require current design approval before implementation; changed source or contribution inputs reopen review
+
 The machinery appears only when it must persist. After the opening grill:
 
 - **No fog surfaced** – say so and proceed to the work
@@ -81,70 +88,7 @@ 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>" --summary "<one sentence>" \
-  --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 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.
-
-    `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.
-
-- Apply `alignment.md` after diagrams are current. Build the artifact, run the
-  review gate, and start implementation only after approval.
-- On the files backend, suggest adding `acstack/maps/` to `.gitignore`
-  (`trackers/files.md` gives the reason).
+Read [materialising.md](materialising.md) and follow its full procedure before creating map nodes.
 
 ## Working the frontier
 
@@ -200,12 +144,12 @@ the list, marked `skip: <reason>`.
 5. **After every resolution**, in order:
     - Invoke `record-context`
     - Create nodes for anything the resolution surfaced
-    - Classify new fog by whether it changes the alignment artifact
+    - Classify new fog by whether it changes the design
     - 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)
-    - Rebuild or rerun the alignment review when the artifact changes
+    - Reopen design review when source, saved comments, or contribution inputs change
     - Recompute the frontier
 
     The regeneration comes after the new nodes exist. A surfaced node hangs

package/skills/map/alignment.md

@@ -1,38 +1,29 @@
-# Alignment review
+# Design review
 
-The alignment artifact is the human-readable end-state view that the CLI renders from the map.
+Use an authored design for shared behavior, component boundaries, and data-flow decisions; map nodes track questions and work.
 
 ## Fog classes
 
-- Blocking fog changes the artifact
-- Deferred fog needs later evidence, or sits below the level the artifact must settle
-- Clear blocking fog before implementation starts
-- Leave deferred fog on the map with the evidence or event that reopens it
+- Blocking fog changes the design
+- Deferred fog needs later evidence or sits below the design's scope
+- Clear blocking fog before implementation
+- Record the evidence or event that reopens deferred fog
 - Never defer fog because asking feels inconvenient
 
 ## Review gate
 
-Build the artifact after diagrams are current:
-
-```bash
-~/.claude/acstack/bin/acstack map --map <name>
-```
-
-The artifact is disposable. The map remains the source of truth.
-
-Run the review before implementation when `workflow.alignment_packs.approval_gate` is true:
-
-```bash
-~/.claude/acstack/bin/acstack align-viewer --map <name>
-```
-
-If the review requests changes, read the feedback file the command prints.
-Update the map, regenerate the diagrams, and rerun the review.
-
-Start implementation only after the reviewer approves the artifact, or after the project disables the approval gate.
+- Follow `/acstack:design-doc` to author the design, bind the map, and record node contributions
+- Run `~/.claude/acstack/bin/acstack design-doc <entry>` for live review
+- Reconcile saved feedback and current contributions through `design-review reconcile`
+- Require `approval.valid: true` from `~/.claude/acstack/bin/acstack design-review status <entry>` before implementation
+- Approval covers the exact source, saved comments, and map contribution inputs
+- Reopen review when those inputs change; regenerating presentation alone preserves approval
+- Use `node walk`, `node frontier`, and `node diagram` for planning views, not architecture generation
+- ACStack removes legacy `map --map` and `align-viewer` without aliases
+- Use explicit `design-review migrate` for legacy feedback (see `/acstack:design-doc`)
 
 ## New fog during implementation
 
-- If new fog changes the artifact, return to `/acstack:map`
-- If new fog does not change the artifact, keep working with a local note
-- Rebuild or rerun the review when implementation changes the artifact
+- Return design-changing fog to `/acstack:map`
+- Keep other fog with its reopening trigger
+- Revise the authored design and repeat reconciliation and approval when review inputs change

package/skills/map/frontend.md

@@ -4,7 +4,7 @@ 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
+`frontend.directory`, the path in `.acstack/project.yaml` where the frontend
 lives.
 
 Two plugins appear in the rules below.

package/skills/map/materialising.md

@@ -0,0 +1,74 @@
+# Materialising a map
+
+Create map nodes with the selected tracker after charting requires persistence.
+
+Read this procedure when [the map skill](SKILL.md#materialising) reaches materialisation, before creating any node.
+
+Pick the tracker (see [Tracker](SKILL.md#tracker)), 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>" --summary "<one sentence>" \
+  --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`](trackers/github.md) holds the format. The files backend writes none.
+
+- 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`](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.
+
+    [`visuals.md`](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](SKILL.md#regenerating-diagrams). A parent draws its subtree, so nothing can draw one earlier.
+  The root is a parent too, and it draws the whole map.
+
+- When a design is required:
+    - Record `Design entry: <repository-relative-path>` in the root node body
+    - Bind the entry back to the map with `planning: {tracker: files | github, map: <name>}`
+    - Require `design-review status` to return that same `planning` binding before using its approval for this map
+    - Record proposals in the node body's `## Design contributions` section using the format in `/acstack:design-doc`
+    - Reconcile proposals and saved feedback explicitly; surface conflicts as decision nodes
+- On the files backend, the root Git ignore rules exclude `.acstack/maps/` unless the user opts in
+  ([`trackers/files.md`](trackers/files.md) gives the reason).

package/skills/map/trackers/files.md

@@ -1,16 +1,16 @@
 # 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
+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.
+The root managed baseline ignores `.acstack/maps/` by default.
+Native exceptions after that baseline let the user opt in to tracking any part.
 
 CLI path: `~/.claude/acstack/bin/acstack`
 
-To enumerate a project's maps: `ls acstack/maps/`.
+To enumerate a project's maps: `ls .acstack/maps/`.
 
 ## The four operations
 
@@ -73,5 +73,3 @@ 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.