acstack 0.53.0 → 0.54.0

package/hooks/lib/read-guard.mjs

@@ -12,6 +12,8 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
 
 export const DEFAULT_MIN_BYTES = 32768;
 
@@ -25,13 +27,13 @@ export function envSaysNotMain(env = process.env) {
 
 /**
  * The one settings function: workflow.read_guard and
- * workflow.read_guard_bytes from the nearest
- * .acstack/project.yaml above cwd. Hand-rolled like the other hooks' readers,
- * because no YAML library is guaranteed at hook time.
+ * workflow.read_guard_bytes from project.yaml in the repository's project
+ * folder. Hand-rolled like the other hooks' readers, because no YAML library
+ * is guaranteed at hook time. pi passes the folder it already resolved.
  */
-export function readGuardSettings(cwd) {
+export function readGuardSettings(cwd, folder = projectFolder(cwd)) {
   const settings = { enabled: true, minBytes: DEFAULT_MIN_BYTES };
-  const yaml = projectYaml(cwd);
+  const yaml = folder ? readText(path.join(folder, 'project.yaml')) : undefined;
   if (yaml === undefined) return settings;
   const stack = [];
   for (const raw of yaml.split('\n')) {
@@ -54,20 +56,19 @@ export function readGuardSettings(cwd) {
   return settings;
 }
 
-function projectYaml(cwd) {
-  let dir = path.resolve(cwd);
-  while (true) {
-    const file = path.join(dir, '.acstack', 'project.yaml');
-    if (fs.existsSync(file)) {
-      try {
-        return fs.readFileSync(file, 'utf8');
-      } catch {
-        return undefined;
-      }
-    }
-    const parent = path.dirname(dir);
-    if (parent === dir) return undefined;
-    dir = parent;
+const CLI = fileURLToPath(new URL('../../cli/bin/acstack.js', import.meta.url));
+
+/** The project folder the CLI reports for cwd, or undefined outside a project. */
+function projectFolder(cwd) {
+  const result = spawnSync(process.execPath, [CLI, 'project-data', 'path'], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  return result.status === 0 ? result.stdout.trim() || undefined : undefined;
+}
+
+function readText(file) {
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch {
+    return undefined;
   }
 }
 
@@ -118,11 +119,14 @@ function resolvePath(file, cwd) {
  * `ledger` has has(key) and add(key); add throws when it cannot record, and
  * then the read is allowed so a repeat can never be trapped.
  */
-export function decide({ toolName, toolInput, cwd, main, ledger, settings = readGuardSettings(cwd) }) {
+export function decide({ toolName, toolInput, cwd, main, ledger, settings }) {
   try {
-    if (!main || !settings.enabled || !ledger) return { block: false };
+    if (!main || !ledger) return { block: false };
     const file = wholeReadTarget(toolName, toolInput, cwd);
     if (!file) return { block: false };
+    // Resolved only for a whole-file read, since it costs a CLI call.
+    settings ??= readGuardSettings(cwd);
+    if (!settings.enabled) return { block: false };
     const stat = fs.statSync(file);
     if (!stat.isFile() || stat.size < settings.minBytes) return { block: false };
     const key = `${fs.realpathSync(file)}\0${stat.size}\0${stat.mtimeMs}`;

package/hooks/project-data.sh

@@ -1,38 +1,9 @@
 #!/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"
+# Print the project folder for the current repository. Fails outside Git, or
+# when the CLI names a fix (legacy data, orphaned entry, conflicting modes);
+# that message and any legacy-data warning reach the user on stderr.
+acstack_project_folder() {
+  "$1" project-data path
 }

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
-# hook reads one known file with no CLI call. The file's frontmatter records the
+# Active (pending) handoff lives at the fixed path <project folder>/HANDOFF.md;
+# the hook asks the CLI for the folder once. 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)
+#   <project folder>/changes/<change>/handoffs/<timestamp>.md   (when the change dir exists)
+#   <project folder>/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
@@ -33,11 +33,8 @@ 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
+project_folder=$(acstack_project_folder "${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}/cli/bin/acstack.js") || exit 0
+cd "$project_folder" 2>/dev/null || 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
@@ -46,7 +43,7 @@ ACSTACK_HOOK_INPUT="$(cat)"
 export ACSTACK_HOOK_INPUT
 
 python3 <<'PY'
-import json, os, re, shutil, subprocess, sys
+import json, os, re, shutil, sys
 
 try:
     data = json.loads(os.environ.get("ACSTACK_HOOK_INPUT", ""))
@@ -59,7 +56,7 @@ if not isinstance(data, dict):
 if data.get("source") != "compact":
     sys.exit(0)
 
-active = os.path.join(".acstack", "HANDOFF.md")
+active = "HANDOFF.md"
 try:
     with open(active, encoding="utf-8") as f:
         raw = f.read()
@@ -105,7 +102,7 @@ if not body.strip():
 # "map" is the current key; "change" is accepted for anchors written by
 # pre-map versions of the handoff skill. The value feeds os.path.join, so
 # sanitize it the same way as the stamp – a name with "/" or ".." must not
-# route the archived handoff outside acstack/.
+# route the archived handoff outside the project folder.
 change = meta.get("map") or meta.get("change") or "ad-hoc"
 change = re.sub(r"[^A-Za-z0-9._-]", "-", str(change))
 if not change.strip("."):
@@ -121,22 +118,14 @@ 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("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("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 (its project folder holds project.yaml), the hook also
 # injects the plugin's orchestrator instructions as additionalContext so installs
 # stay version-agnostic. Otherwise prints a one-line reminder.
 
@@ -181,14 +181,12 @@ if [ -n "$plugin_root" ]; then
   esac
 fi
 
-# 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
+if ! project_folder=$(acstack_project_folder "$cli_wrapper"); then
   exit 0
 fi
 
-if [ ! -f "$project_root/.acstack/project.yaml" ]; then
+if [ ! -f "$project_folder/project.yaml" ]; then
   echo 'acstack: no project config found. Run /acstack:setup to set up.' >&2
   exit 0
 fi
@@ -205,7 +203,7 @@ if ! command -v python3 >/dev/null 2>&1; then
   exit 0
 fi
 
-python3 - "$claude_md" <<'PY'
+python3 - "$claude_md" "$project_folder" <<'PY'
 import json, re, sys
 path = sys.argv[1]
 with open(path, 'r', encoding='utf-8') as f:
@@ -213,6 +211,7 @@ with open(path, 'r', encoding='utf-8') as f:
 # SessionStart reaches the lead session, so it keeps the lead block and drops the delegated one.
 content = re.sub(r'<!-- acstack:delegated:start -->[\s\S]*?<!-- acstack:delegated:end -->\n?', '', content)
 content = re.sub(r'<!-- acstack:lead:(start|end) -->\n?', '', content)
+content += "\n\nThis repository's ACStack project folder: " + sys.argv[2] + "\n"
 print(json.dumps({
     "hookSpecificOutput": {
         "hookEventName": "SessionStart",

package/orchestrator/AGENTS.md

@@ -87,17 +87,22 @@ ACStack runs on Claude Code, Codex, and pi. The skills name each capability once
 
 ## Project configuration
 
-- 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`.
+- All ACStack-owned project data lives in one folder per repository, the **project folder**
+    - `~/.claude/acstack/bin/acstack project-data path` prints its absolute path, even before it exists
+    - Every worktree of a repository shares it; the session-start hook also states it in your context
+    - The command exits non-zero outside a Git repository, and names the fix for legacy data, orphaned entries, or conflicts
+    - These files write its parts as `<project folder>/project.yaml`, `<project folder>/specs/`, and so on
+- **Global mode** (the default) keeps the project folder under `~/.acstack/projects/` (or `$ACSTACK_HOME/projects/`)
+    - The repository holds no ACStack files and needs no `.gitignore` rules
+- **Tracked mode** (opt-in) keeps the records in the main checkout's committed `.acstack/`; the project folder is a link to it
+    - Edits to a feature branch's own `.acstack/` take effect only once they reach the main checkout
+- Data moves only when the developer asks: `acstack project-data mode tracked|global`, `migrate`, or `relink <entry>`
+    - For legacy layouts, follow the explicit migration procedure in `docs/config-reference.md`
+    - Update installed tools first, stop old agents and review servers, migrate, then restart with updated tools
+    - Never silently migrate data or work around legacy data by creating a partial project folder
+- Never change the Git index or force-add files to track project data
+
+All project-specific commands and paths come from `<project folder>/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:
 
@@ -331,19 +336,19 @@ The investigator reports:
 
 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 `<project folder>/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 `<project folder>/domain-map.yaml`
+3. For each affected domain with a `<project folder>/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 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
+4. Stage updated specs only in tracked mode, when you commit in the main checkout
+    - In global mode, and from other worktrees in tracked mode, specs update in place and stay out of the commit
 5. Flag unmapped source files. Prompt the user to map them.
 
-Spec sync updates local records with every commit, including when those records stay ignored.
+Spec sync updates the living specs with every commit, whether or not the commit includes them.
 
 ---
 
@@ -360,9 +365,9 @@ Spec sync updates local records with every commit, including when those records
 
 ## Living specs
 
-- `.acstack/specs/` contains the cumulative source of truth for the system
+- `<project folder>/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 `<project folder>/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)
@@ -385,12 +390,12 @@ Read-only reviewers report discrepancies to the completion owner.
 
 The verification owner gathers evidence for the final revision. Opening a PR does not require running every test locally.
 
-Read `.acstack/project.yaml` for the available commands and inspect the project's CI configuration before relying on it:
+Read `<project folder>/project.yaml` for the available commands and inspect the project's CI configuration before relying on it:
 
 1. Use focused local checks by default: cover changed behavior, affected callers, and relevant integration paths
 2. Run applicable build, lint, and typecheck checks; scope them when the tooling supports it
 3. A configured command is not a requirement to run its entire suite. Run the full suite locally only when explicitly required by the user or project instructions, or when broad or uncertain impact cannot be covered adequately by narrower checks
-4. When `commands.test_collect` is configured, compare the count against `.acstack/.test-baseline` if present; investigate removed coverage and honor project baseline requirements
+4. When `commands.test_collect` is configured, compare the count against `<project folder>/.test-baseline` if present; investigate removed coverage and honor project baseline requirements
 5. Run configured frontend build, lint, and tests when frontend files changed, and complete applicable design and browser gates
 
 Required CI checks must pass before merge, not before opening a PR. Defer broader checks to CI only after confirming it runs them for this change; do not assume CI runs every test.
@@ -419,7 +424,7 @@ Do not claim completion with failed or blocked required checks. Investigate, fix
 
 ## Frontend visual verification
 
-**This section applies only when `.acstack/project.yaml` sets `frontend` and `workflow.frontend_verification` is `true`.**
+**This section applies only when `<project folder>/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.
 
@@ -427,7 +432,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 (`.acstack/verification/VERIFICATION-KNOWLEDGE.md`)
+1. Reads the project's verification knowledge base (`<project folder>/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
@@ -440,8 +445,8 @@ The frontend-verifier agent:
 
 Run `/acstack:setup` to set up browser verification. This creates:
 
-- **`.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
+- **`<project folder>/agent-browser.json`** – CDP connection config, selected by an absolute `--config` path or `AGENT_BROWSER_CONFIG`
+- **`<project folder>/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.
 

package/package.json

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

package/pi/agents/frontend-verifier.md

@@ -28,7 +28,7 @@ You review screenshots. You report results. You do not need user approval.
 
 ## Project configuration
 
-Read `.acstack/project.yaml` for frontend settings:
+ACStack keeps project data in the project folder, the path `~/.claude/acstack/bin/acstack project-data path` prints. Read `<project folder>/project.yaml` for frontend settings:
 
 - `frontend.directory` – frontend source directory
 - `frontend.dev_server_url` – dev server URL
@@ -39,14 +39,15 @@ Read `.acstack/project.yaml` for frontend settings:
 
 You do not read `frontend.browser.mode` or `frontend.browser.fallback`. Step 3 asks the ACStack CLI which browser mode to use, and the CLI reads both.
 
-If `.acstack/project.yaml` has no `frontend` section, report SKIP and exit.
+If `<project folder>/project.yaml` has no `frontend` section, report SKIP and exit.
 
 ## Step 0: Read the knowledge base
 
 Before doing anything, check for a knowledge base:
 
 ```bash
-cat .acstack/verification/VERIFICATION-KNOWLEDGE.md 2>/dev/null
+project="$(~/.claude/acstack/bin/acstack project-data path)"
+cat "$project/verification/VERIFICATION-KNOWLEDGE.md" 2>/dev/null
 ```
 
 This file contains URL patterns, element patterns, gotchas, and lessons learned. Read it if it exists. If not, you'll create it in Step 7.
@@ -205,10 +206,10 @@ Track whether you launched the browser so you can clean it up in Step 8.
 
 ## Step 4: Verify with agent-browser
 
-Select the project's browser config explicitly from the project root:
+Select the project's browser config explicitly by its absolute path:
 
 ```bash
-export AGENT_BROWSER_CONFIG="$(pwd)/.acstack/agent-browser.json"
+export AGENT_BROWSER_CONFIG="$(~/.claude/acstack/bin/acstack project-data path)/agent-browser.json"
 ```
 
 Require the file for configured verification; do not assume root config autodiscovery.
@@ -299,13 +300,13 @@ After every verification run, update the knowledge base if you learned something
 
 ### Knowledge base
 
-`.acstack/verification/VERIFICATION-KNOWLEDGE.md` – URL patterns, element patterns, gotchas, lessons learned.
+`<project folder>/verification/VERIFICATION-KNOWLEDGE.md` – URL patterns, element patterns, gotchas, lessons learned.
 
 If it doesn't exist, create it with what you learned during this run.
 
 ### Rules
 
-- All verification knowledge lives in `.acstack/verification/VERIFICATION-KNOWLEDGE.md`.
+- All verification knowledge lives in `<project folder>/verification/VERIFICATION-KNOWLEDGE.md`.
 - Do NOT create knowledge files anywhere else.
 - If a selector or element pattern stops working, update the knowledge base.
 - If you discover a new pattern, add it.

package/pi/agents/task-checker.md

@@ -19,7 +19,7 @@ You are read-only: do not edit source, tests, or specs.
 ## Establish scope and ownership
 
 Read the supplied requirements, affected paths, known risks, and available command results.
-Read `.acstack/project.yaml` for commands, directories, environment activation, and applicable frontend gates.
+Read `project.yaml` in the project folder that `~/.claude/acstack/bin/acstack project-data path` prints for commands, directories, environment activation, and applicable frontend gates.
 
 - Distinguish focused review from ownership of completion verification
 - If the assignment is unclear, clarify it with the delegating session before duplicating checks

package/pi/agents/task-executor.md

@@ -23,7 +23,7 @@ Implement the assigned requirements under the shared Implementation discipline i
 
 ## Project configuration
 
-Read `.acstack/project.yaml` for project-specific settings:
+Read `project.yaml` in the project folder that `~/.claude/acstack/bin/acstack project-data path` prints for project-specific settings:
 
 - `directories.source` – where to write source code
 - `directories.tests` – test directory, subject to assigned ownership

package/pi/agents/test-writer.md

@@ -32,7 +32,7 @@ You write tests from requirements and application programming interface (API) co
 
 ## Project configuration
 
-Read `.acstack/project.yaml` for project-specific settings:
+Read `project.yaml` in the project folder that `~/.claude/acstack/bin/acstack project-data path` prints for project-specific settings:
 
 - `directories.tests` – where to create test files
 - `directories.source` – source code root (for mirroring structure)