acstack 0.50.4 → 0.52.0

package/examples/design-doc/acstack/cli.yaml

@@ -0,0 +1,5 @@
+id: cli
+name: CLI package
+summary: Ships the review command, local server, and browser review interface.
+kind: component
+parent: acstack

package/examples/design-doc/acstack/design.yaml

@@ -0,0 +1,39 @@
+id: acstack-design
+name: ACStack design review
+summary: >-
+  ACStack guides design authoring, saves browser feedback, reconciles optional
+  map contributions, and records exact-revision approval with retained evidence.
+detail: journey.md
+elements:
+  - user.yaml
+  - acstack.yaml
+  - skills.yaml
+  - host.yaml
+  - cli.yaml
+  - review-runtime.yaml
+  - viewer.yaml
+  - store.yaml
+  - github.yaml
+concerns:
+  - id: offline-review
+    name: Offline review
+    elements: [review-runtime, viewer, design-source]
+    requirement: >-
+      Reviewers can inspect the design without uploading project details
+      or fetching browser assets.
+    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.
+  - id: honest-scope
+    name: Honest review status
+    elements: [skills, review-runtime, viewer]
+    requirement: >-
+      An exported review artifact must not imply that a reviewer approved
+      a map or implementation.
+    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.

package/examples/design-doc/acstack/github.yaml

@@ -0,0 +1,12 @@
+id: github
+name: GitHub
+summary: Hosts a published copy of the Markdown companion when the developer chooses to share it.
+kind: external-system
+channels: [web]
+detail: publication.md
+relationships:
+  - id: publish-companion
+    from: user
+    to: github
+    direction: one-way
+    label: Optionally publishes the Markdown companion to

package/examples/design-doc/acstack/host.yaml

@@ -0,0 +1,14 @@
+id: host
+name: Agent session setup
+summary: >-
+  Registers ACStack skill commands and adds rules for planning, coding,
+  and checking changes to the agent's session.
+kind: component
+parent: acstack
+channels: [agent]
+relationships:
+  - id: load-skills
+    from: host
+    to: skills
+    direction: one-way
+    label: Registers

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

@@ -0,0 +1,85 @@
+## 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

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

@@ -0,0 +1,16 @@
+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

package/examples/design-doc/acstack/review-runtime.yaml

@@ -0,0 +1,24 @@
+id: review-runtime
+name: Review command and server
+summary: >-
+  Reads and validates authored YAML, serves the browser review interface,
+  saves comments, and exports Markdown.
+kind: component
+parent: cli
+channels: [cli, web]
+relationships:
+  - id: export-design
+    from: skills
+    to: review-runtime
+    direction: one-way
+    label: Guides the agent to run
+  - id: read-source
+    from: review-runtime
+    to: design-source
+    direction: one-way
+    label: Reads design source
+  - id: review-session
+    from: review-runtime
+    to: viewer
+    direction: bidirectional
+    label: Exchanges the design and comments with

package/examples/design-doc/acstack/skills.yaml

@@ -0,0 +1,22 @@
+id: skills
+name: Agent skills
+summary: Guide the agent through authoring and exporting a design for review.
+kind: component
+parent: acstack
+channels: [agent]
+relationships:
+  - id: author-design
+    from: user
+    to: skills
+    direction: one-way
+    label: Requests design guidance from
+  - id: export-design
+    from: skills
+    to: review-runtime
+    direction: one-way
+    label: Guides the agent to run
+  - id: load-skills
+    from: host
+    to: skills
+    direction: one-way
+    label: Registers

package/examples/design-doc/acstack/store.yaml

@@ -0,0 +1,11 @@
+id: design-source
+name: Authored design files
+summary: Holds the local YAML and supporting Markdown that the review server reads.
+kind: store
+detail: publication.md
+relationships:
+  - id: read-source
+    from: review-runtime
+    to: design-source
+    direction: one-way
+    label: Reads design source

package/examples/design-doc/acstack/user.yaml

@@ -0,0 +1,15 @@
+id: user
+name: Project developer
+summary: Authors the design and reviews the exported artifact locally.
+kind: actor
+relationships:
+  - id: author-design
+    from: user
+    to: skills
+    direction: one-way
+    label: Requests design guidance from
+  - id: publish-companion
+    from: user
+    to: github
+    direction: one-way
+    label: Optionally publishes the Markdown companion to

package/examples/design-doc/acstack/viewer.yaml

@@ -0,0 +1,13 @@
+id: viewer
+name: Browser review interface
+summary: >-
+  Receives the prepared design graph and syncs comments with the local server.
+kind: component
+parent: cli
+channels: [web]
+relationships:
+  - id: review-session
+    from: review-runtime
+    to: viewer
+    direction: bidirectional
+    label: Exchanges the design and comments with

package/hooks/ac-writing-style-reminder.sh

@@ -8,11 +8,9 @@
 #
 # The reminder text is EXTRACTED from output-styles/ac-writing-style.md on every
 # turn, never stored. A hand-typed copy drifts from the style the moment either
-# one changes, and that is exactly what happened to the first version of this
-# hook. Two parts come out of the file:
-#
-#   1. "## Who you are", top-level lines only, which is the persona
-#   2. "## Before you send", in full, which is the checklist
+# one changes. The marked communication block is the canonical standard for
+# chat and durable writing. Extract it in full, including nested guidance;
+# headings and checklist item counts are not an extraction contract.
 #
 # Output is JSON only, with suppressOutput true, so nothing reaches the user's
 # transcript. The hook stays silent unless the active output style is this one.
@@ -66,21 +64,12 @@ awk '
   }
   function emit(s) { out = out esc(s) "\\n" }
 
-  # "## Who you are" holds the persona. Keep its top-level lines: the italic
-  # opener, the bold rules, and the unindented bullets. Drop the sub-bullets,
-  # because the reminder names each rule and the file itself argues for it.
-  /^## Who you are$/            { persona = 1; next }
-  /^## Shape: Minto pyramid$/   { persona = 0 }
-  persona && /^### /            { emit(""); emit($0); next }
-  persona && /^[*-]/            { emit($0); next }
-  persona && /^\*\*/            { emit($0); next }
-
-  # "## Before you send" is the checklist, and it runs to the end of the file.
-  /^## Before you send$/        { checklist = 1; emit(""); emit($0); next }
-  checklist                     { emit($0); next }
+  /^<!-- acstack:communication:start -->$/ { shared = 1; next }
+  /^<!-- acstack:communication:end -->$/   { complete = shared; exit }
+  shared                                  { emit($0) }
 
   END {
-    if (out == "") exit 1
+    if (!complete || out == "") exit 1
     printf "{\"suppressOutput\": true, \"hookSpecificOutput\": {\"hookEventName\": \"UserPromptSubmit\", \"additionalContext\": \"ac-writing-style reminder\\n\\n%s\"}}\n", out
   }
 ' "$style_file" || silent

package/hooks/communication-standard.mjs

@@ -0,0 +1,17 @@
+import { readFileSync } from 'node:fs';
+import { readCommunicationStandard } from './lib/communication-standard.mjs';
+
+try {
+  const { hook_event_name: event } = JSON.parse(readFileSync(0, 'utf8'));
+  if (event !== 'SessionStart' && event !== 'SubagentStart') {
+    throw new Error('Expected SessionStart or SubagentStart');
+  }
+  const standard = readCommunicationStandard(process.argv[2]);
+  console.log(JSON.stringify({
+    suppressOutput: true,
+    hookSpecificOutput: { hookEventName: event, additionalContext: standard },
+  }));
+} catch (error) {
+  console.error(`acstack communication standard: ${error.message}`);
+  process.exitCode = 1;
+}

package/hooks/communication-standard.sh

@@ -0,0 +1,6 @@
+#!/bin/sh
+# Startup context is independent of project activation and selected output style.
+set -eu
+root="${CLAUDE_PLUGIN_ROOT:-}"
+[ -n "$root" ] || root="$(CDPATH='' cd -- "$(dirname -- "$0")/.." && pwd)"
+exec node "$root/hooks/communication-standard.mjs" "$root"

package/hooks/context-pressure.sh

@@ -40,7 +40,7 @@
 #   nudge when it crosses each rung rather than on every single stop.
 #
 #   The default rungs are workflow.handoff.nudge_warn and nudge_severe from
-#   acstack/project.yaml (defaulting to 200000 / 500000), and then one rung
+#   .acstack/project.yaml (defaulting to 200000 / 500000), and then one rung
 #   every workflow.handoff.nudge_step tokens (default 100000) above the last
 #   one. Setting workflow.handoff.context_thresholds replaces the default rungs
 #   entirely with the listed ones - written either block style (one "- item"
@@ -361,7 +361,7 @@ def read_config():
         "context_thresholds": None,
     }
     try:
-        with open(os.path.join("acstack", "project.yaml"), encoding="utf-8", errors="replace") as f:
+        with open(os.path.join(".acstack", "project.yaml"), encoding="utf-8", errors="replace") as f:
             lines = f.read().split("\n")
     except OSError:
         return cfg

package/hooks/hooks.json

@@ -1,6 +1,14 @@
 {
   "hooks": {
     "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/communication-standard.sh\""
+          }
+        ]
+      },
       {
         "hooks": [
           {
@@ -26,6 +34,16 @@
         ]
       }
     ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/communication-standard.sh\""
+          }
+        ]
+      }
+    ],
     "Stop": [
       {
         "hooks": [

package/hooks/lib/communication-standard.mjs

@@ -0,0 +1,16 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** Read the only authored communication standard, refusing partial blocks. */
+export function readCommunicationStandard(root) {
+  const file = join(root, 'output-styles', 'ac-writing-style.md');
+  const lines = readFileSync(file, 'utf8').split(/\r?\n/);
+  const starts = lines.flatMap((line, i) => line === '<!-- acstack:communication:start -->' ? [i] : []);
+  const ends = lines.flatMap((line, i) => line === '<!-- acstack:communication:end -->' ? [i] : []);
+  if (starts.length !== 1 || ends.length !== 1 || starts[0] >= ends[0]) {
+    throw new Error(`${file}: expected one ordered communication marker pair`);
+  }
+  const standard = lines.slice(starts[0] + 1, ends[0]).join('\n').trim();
+  if (!standard) throw new Error(`${file}: empty communication standard`);
+  return standard;
+}

package/hooks/project-data.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# Source from host hooks before reading config or writing project data.
+acstack_has_legacy_project_data() {
+  local root="$1" name
+  for name in project.yaml domain-map.yaml; do
+    { [ -f "$root/acstack/$name" ] || [ -L "$root/acstack/$name" ]; } && return 0
+  done
+  for name in alignment-packs design-reviews maps specs changes archive decision-logs; do
+    { [ -d "$root/acstack/$name" ] || [ -L "$root/acstack/$name" ]; } && return 0
+  done
+  return 1
+}
+
+acstack_project_root() {
+  local root
+  root="$PWD"
+  while [ "$root" != / ]; do
+    if [ -d "$root/.acstack" ] || acstack_has_legacy_project_data "$root"; then
+      printf '%s\n' "$root"
+      return
+    fi
+    root=$(dirname "$root")
+  done
+  git rev-parse --show-toplevel 2>/dev/null || printf '%s\n' "$PWD"
+}
+
+acstack_ensure_project_data() {
+  local root="$1" bundled_cli="$2"
+  if acstack_has_legacy_project_data "$root"; then
+    echo 'acstack: legacy project data found; run ~/.claude/acstack/bin/acstack project-data migrate before using it.' >&2
+  fi
+  if ! (cd "$root" && "$bundled_cli" project-data ensure >&2); then
+    echo 'acstack: project-data ensure failed; ignore policy is not confirmed installed. Skipping project activation and private writes.' >&2
+    return 1
+  fi
+  # A second config root must never hide unmigrated project data.
+  ! acstack_has_legacy_project_data "$root"
+}

package/hooks/session-start-handoff.sh

@@ -9,13 +9,13 @@
 # the load-bearing state the summary may have compressed away (next action, task
 # ledger, agent-team file ownership, blockers).
 #
-# Active (pending) handoff lives at the fixed path acstack/HANDOFF.md, so this
+# Active (pending) handoff lives at the fixed path .acstack/HANDOFF.md, so this
 # hook reads one known file with no CLI call. The file's frontmatter records the
 # change it belongs to. On consume, the file is MOVED into that change's own
 # folder, accumulating a per-change history:
 #
-#   acstack/changes/<change>/handoffs/<timestamp>.md   (when the change dir exists)
-#   acstack/handoffs/<change>/<timestamp>.md           (ad-hoc, or change archived)
+#   .acstack/changes/<change>/handoffs/<timestamp>.md   (when the change dir exists)
+#   .acstack/handoffs/<change>/<timestamp>.md           (ad-hoc, or change archived)
 #
 # Storing consumed handoffs inside the change dir means they travel with the
 # change when /acstack:archive moves it. Names are timestamped with a numeric
@@ -32,6 +32,12 @@
 set -u
 
 command -v python3 >/dev/null 2>&1 || exit 0
+source "$(dirname "${BASH_SOURCE[0]}")/project-data.sh"
+project_root=$(acstack_project_root)
+export ACSTACK_LEGACY_PROJECT_DATA=0
+acstack_has_legacy_project_data "$project_root" && ACSTACK_LEGACY_PROJECT_DATA=1
+export ACSTACK_BUNDLED_CLI="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}/cli/bin/acstack.js"
+cd "$project_root" || exit 0
 
 # Capture the hook payload from stdin before running python. The heredoc below
 # becomes python's stdin (the program source), so the payload must travel via an
@@ -40,7 +46,7 @@ ACSTACK_HOOK_INPUT="$(cat)"
 export ACSTACK_HOOK_INPUT
 
 python3 <<'PY'
-import json, os, re, shutil, sys
+import json, os, re, shutil, subprocess, sys
 
 try:
     data = json.loads(os.environ.get("ACSTACK_HOOK_INPUT", ""))
@@ -53,7 +59,7 @@ if not isinstance(data, dict):
 if data.get("source") != "compact":
     sys.exit(0)
 
-active = os.path.join("acstack", "HANDOFF.md")
+active = os.path.join(".acstack", "HANDOFF.md")
 try:
     with open(active, encoding="utf-8") as f:
         raw = f.read()
@@ -115,14 +121,22 @@ if not stamp:
 # Route to the change's own folder when that change dir exists, so consumed
 # handoffs travel with the change on /acstack:archive. Otherwise fall back to a
 # neutral top-level handoffs dir (ad-hoc work, or a change already archived).
-change_dir = os.path.join("acstack", "changes", change)
+change_dir = os.path.join(".acstack", "changes", change)
 if change != "ad-hoc" and os.path.isdir(change_dir):
     archive_dir = os.path.join(change_dir, "handoffs")
 else:
-    archive_dir = os.path.join("acstack", "handoffs", change)
+    archive_dir = os.path.join(".acstack", "handoffs", change)
 
 # Find a non-colliding destination: <stamp>.md, then <stamp>-2.md, -3.md, ...
 dest = None
+try:
+    subprocess.run([os.environ["ACSTACK_BUNDLED_CLI"], "project-data", "ensure"],
+                   check=True, stdout=sys.stderr, stderr=sys.stderr)
+    if os.environ["ACSTACK_LEGACY_PROJECT_DATA"] == "1":
+        raise OSError("Legacy project data found; run ~/.claude/acstack/bin/acstack project-data migrate first")
+except (OSError, subprocess.CalledProcessError) as error:
+    print("acstack: project-data ensure failed; ignore policy is not confirmed installed. Leaving the active handoff untouched. " + str(error), file=sys.stderr)
+    sys.exit(0)
 try:
     os.makedirs(archive_dir, exist_ok=True)
     candidate = os.path.join(archive_dir, stamp + ".md")

package/hooks/session-start.sh

@@ -17,7 +17,7 @@
 # Both symlinks point at ${CLAUDE_PLUGIN_ROOT}/cli/bin/acstack.js, which is a
 # tiny node wrapper that loads ../dist/index.js.
 #
-# When a project is initialized (acstack/project.yaml exists), the hook also
+# When a project is initialized (.acstack/project.yaml exists), the hook also
 # injects the plugin's orchestrator instructions as additionalContext so installs
 # stay version-agnostic. Otherwise prints a one-line reminder.
 
@@ -181,7 +181,14 @@ if [ -n "$plugin_root" ]; then
   esac
 fi
 
-if [ ! -f acstack/project.yaml ]; then
+# Install the ignore baseline even when setup has not written project.yaml.
+source "${plugin_root}/hooks/project-data.sh"
+project_root=$(acstack_project_root)
+if ! acstack_ensure_project_data "$project_root" "$cli_wrapper"; then
+  exit 0
+fi
+
+if [ ! -f "$project_root/.acstack/project.yaml" ]; then
   echo 'acstack: no project config found. Run /acstack:setup to set up.' >&2
   exit 0
 fi

package/orchestrator/AGENTS.md

@@ -66,7 +66,17 @@ ACStack runs on Claude Code, Codex, and pi. The skills name each capability once
 
 ## Project configuration
 
-All project-specific commands and paths come from `acstack/project.yaml`. Read this file before you run any build, test or lint command. If it doesn't exist, prompt the user to run `/acstack:setup`.
+- All ACStack-owned project data lives under `.acstack/` and stays local by default
+- The root `.gitignore` is the sole tracking policy; user exceptions after its managed baseline opt individual parts in
+- Before a configuration gate, CLI and host session startup run `~/.claude/acstack/bin/acstack project-data ensure`
+- When creating `.acstack/` manually, run that command immediately; it needs no project config
+- Filesystem creation alone triggers nothing; the next CLI invocation or session startup enforces the baseline, without a watcher
+- Never force-add ignored project data, change the Git index, or create automatic tracking exceptions
+- For legacy layouts, follow the explicit migration procedure in `docs/config-reference.md`
+- Update installed tools first, stop old agents and reviews, migrate the selected checkout, then restart with updated tools
+- Never silently migrate another checkout or work around legacy data by creating a partial `.acstack/` there
+
+All project-specific commands and paths come from `.acstack/project.yaml`. Read this file before you run any build, test or lint command. If it doesn't exist, prompt the user to run `/acstack:setup`.
 
 Key fields:
 
@@ -250,18 +260,19 @@ flowchart TD
 
 Spec sync keeps living specs current, whichever workflow you ran. It runs as part of every `/acstack:commit`.
 
-When `workflow.spec_sync` is `true` in `acstack/project.yaml`:
+When `workflow.spec_sync` is `true` in `.acstack/project.yaml`:
 
 1. Run `git diff --staged` to see what is changing
-2. Map changed files to spec domains via `acstack/domain-map.yaml`
-3. For each affected domain with a `acstack/specs/[domain]/spec.md`:
+2. Map changed files to spec domains via `.acstack/domain-map.yaml`
+3. For each affected domain with a `.acstack/specs/[domain]/spec.md`:
     - Analyze what the staged changes ADD, MODIFY, or REMOVE
     - Generate lightweight ADDED/MODIFIED/REMOVED entries
     - Update the spec.md
-4. Stage updated spec files in the same commit
+4. 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 the user's choice
 5. Flag unmapped source files. Prompt the user to map them.
 
-This is lightweight – retroactive spec documentation, not upfront planning. Specs converge toward reality with every commit.
+Spec sync updates local records with every commit, including when those records stay ignored.
 
 ---
 
@@ -278,9 +289,9 @@ This is lightweight – retroactive spec documentation, not upfront planning. Sp
 
 ## Living specs
 
-- `acstack/specs/` contains the cumulative source of truth for the system
+- `.acstack/specs/` contains the cumulative source of truth for the system
 - `/acstack:commit` updates them automatically through spec sync; `/acstack:archive` closes out a cleared map
-- Domain-organized per `acstack/domain-map.yaml`
+- Domain-organized per `.acstack/domain-map.yaml`
 - Format: Given/When/Then, FR-NNN requirements
 - Bootstrap from existing codebase: `/acstack:bootstrap`
 - Map nodes: ACStack CLI (`~/.claude/acstack/bin/acstack node create | read | update | list`, plus the composed `node frontier` and `node walk` queries)
@@ -303,13 +314,13 @@ Read-only reviewers report discrepancies to the completion owner.
 
 **Before marking ANY task as complete, you MUST verify the project builds.**
 
-Read `acstack/project.yaml` for the specific commands. The general pattern:
+Read `.acstack/project.yaml` for the specific commands. The general pattern:
 
 1. Run the build command if the project configures one
 2. Run lint
 3. Run typecheck if the project configures one
 4. Run the full test suite – ALL tests must pass
-5. Compare the test count against `.test-baseline`. The count must not drop.
+5. Compare the test count against `.acstack/.test-baseline`. The count must not drop.
 6. Run the frontend build and lint if the project configures a frontend
 
 ### When to run
@@ -329,7 +340,7 @@ Read `acstack/project.yaml` for the specific commands. The general pattern:
 
 ## Frontend visual verification
 
-**This section applies only when `acstack/project.yaml` sets `frontend` and `workflow.frontend_verification` is `true`.**
+**This section applies only when `.acstack/project.yaml` sets `frontend` and `workflow.frontend_verification` is `true`.**
 
 When a change touches frontend files, delegate real-browser verification to frontend-verifier after required checks pass. Never substitute a confidence claim for browser evidence.
 
@@ -337,7 +348,7 @@ The design pass runs before browser verification when the design gate is on, fol
 
 The frontend-verifier agent:
 
-1. Reads the project's verification knowledge base (`<helpers_dir>/VERIFICATION-KNOWLEDGE.md`)
+1. Reads the project's verification knowledge base (`.acstack/verification/VERIFICATION-KNOWLEDGE.md`)
 2. Checks what frontend files changed
 3. Starts the dev server if it's not running
 4. Connects to a browser through the Chrome DevTools Protocol (CDP), over a remote tunnel or local headless Chromium
@@ -350,8 +361,8 @@ The frontend-verifier agent:
 
 Run `/acstack:setup` to set up browser verification. This creates:
 
-- **agent-browser.json** – CDP connection config in the project root
-- **VERIFICATION-KNOWLEDGE.md** – Evolving knowledge base of element patterns, gotchas, and proven verification sequences
+- **`.acstack/agent-browser.json`** – CDP connection config, selected by an absolute `--config` path or `AGENT_BROWSER_CONFIG`
+- **`.acstack/verification/VERIFICATION-KNOWLEDGE.md`** – Evolving knowledge base of element patterns, gotchas, and proven verification sequences
 
 `frontend.browser.mode` in project.yaml holds the browser environment: remote, headless, or local.