acstack 0.53.0 → 0.54.0

package/pi/extension.ts

@@ -14,7 +14,7 @@
  *                        from the SSOT style file   (hooks/ac-writing-style-reminder.sh)
  *   agent_before_settle  nudge with a continuity-versus-freshness checkpoint
  *                        as context fills          (hooks/context-pressure.sh)
- *   session_compact      re-inject .acstack/HANDOFF.md after a compaction, and
+ *   session_compact      re-inject <project folder>/HANDOFF.md after a compaction, and
  *                        restart the nudge ladder   (hooks/session-start-handoff.sh,
  *                                                    hooks/context-pressure.sh)
  *   tool_call            block a main agent's first whole read of a large
@@ -33,51 +33,35 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
-import { execFileSync } from "node:child_process";
+import { spawnSync } from "node:child_process";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 // @ts-ignore -- plain ESM shared with hooks/read-guard.mjs, no type declarations
-import { decide, envSaysNotMain } from "../hooks/lib/read-guard.mjs";
+import { decide, envSaysNotMain, readGuardSettings } from "../hooks/lib/read-guard.mjs";
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const troubleshoot = path.join(packageRoot, "TROUBLESHOOTING.md");
 
-function hasLegacyProjectData(root: string): boolean {
-	if (!fs.lstatSync(path.join(root, "acstack"), { throwIfNoEntry: false })?.isDirectory()) return false;
-	return ["project.yaml", "domain-map.yaml"].some(name => {
-		const entry = fs.lstatSync(path.join(root, "acstack", name), { throwIfNoEntry: false });
-		return entry?.isFile() || entry?.isSymbolicLink();
-	}) || ["alignment-packs", "design-reviews", "maps", "specs", "changes", "archive", "decision-logs"].some(name => {
-		const entry = fs.lstatSync(path.join(root, "acstack", name), { throwIfNoEntry: false });
-		return entry?.isDirectory() || entry?.isSymbolicLink();
-	});
-}
-
-function projectRoot(cwd: string): string {
-	let root = path.resolve(cwd);
-	while (true) {
-		if (fs.existsSync(path.join(root, ".acstack")) || hasLegacyProjectData(root)) return root;
-		const parent = path.dirname(root);
-		if (parent === root) break;
-		root = parent;
-	}
+/**
+ * Ask the bundled CLI for this repository's project folder, the way the
+ * Claude Code hooks do. Null outside a Git repository, or when the CLI names a
+ * fix (legacy data, orphaned entry, conflicting modes); that message and any
+ * legacy-data warning reach the user once per cwd.
+ */
+const projectFolders = new Map<string, string | null>();
+function projectFolder(ctx: ExtensionContext | undefined, cwd: string): string | null {
+	const key = path.resolve(cwd);
+	if (projectFolders.has(key)) return projectFolders.get(key)!;
+	let folder: string | null = null;
 	try {
-		return execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+		const result = spawnSync(process.execPath, [path.join(packageRoot, "cli", "bin", "acstack.js"), "project-data", "path"], { cwd: key, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+		const message = result.stderr.trim();
+		if (message && ctx) report(ctx, message.startsWith("acstack:") ? message : `acstack: ${message}`, result.status === 0 ? "warning" : "error");
+		if (result.status === 0) folder = result.stdout.trim() || null;
 	} catch {
-		return path.resolve(cwd);
-	}
-}
-
-function ensureProjectData(ctx: ExtensionContext, root: string): boolean {
-	if (hasLegacyProjectData(root)) {
-		report(ctx, "acstack: legacy project data found; run ~/.claude/acstack/bin/acstack project-data migrate before using it.", "warning");
-	}
-	try {
-		execFileSync(process.execPath, [path.join(packageRoot, "cli", "bin", "acstack.js"), "project-data", "ensure"], { cwd: root, stdio: ["ignore", "pipe", "pipe"] });
-		return !hasLegacyProjectData(root);
-	} catch (error) {
-		report(ctx, `acstack: project-data ensure failed; ignore policy is not confirmed installed. Skipping project activation and private writes. ${error instanceof Error ? error.message : String(error)}`, "error");
-		return false;
+		folder = null;
 	}
+	projectFolders.set(key, folder);
+	return folder;
 }
 
 /** pi-subagents' background runner sets this in every child process. */
@@ -349,7 +333,7 @@ function flowList(value: string): string[] {
 }
 
 /**
- * The workflow.handoff keys from .acstack/project.yaml. A port of read_config
+ * The workflow.handoff keys from <project folder>/project.yaml. A port of read_config
  * in hooks/context-pressure.sh, hand-rolled for the same reason: no YAML
  * library is guaranteed to be installed.
  */
@@ -496,12 +480,12 @@ const HANDOFF_PREAMBLE =
 	"wrong assumption taken after compaction is expensive to unwind.\n\n";
 
 /**
- * Consume .acstack/HANDOFF.md the way hooks/session-start-handoff.sh does:
+ * Consume <project folder>/HANDOFF.md the way hooks/session-start-handoff.sh does:
  * only a file carrying the acstack_handoff marker, moved into a per-map
  * archive so it is never injected twice. Returns the text to inject.
  */
-export function consumeHandoff(cwd: string, now: Date = new Date()): string | undefined {
-	const active = path.join(cwd, ".acstack", "HANDOFF.md");
+export function consumeHandoff(folder: string, now: Date = new Date()): string | undefined {
+	const active = path.join(folder, "HANDOFF.md");
 	const raw = readText(active);
 	if (!raw?.trim()) return undefined;
 
@@ -522,11 +506,11 @@ export function consumeHandoff(cwd: string, now: Date = new Date()): string | un
 	let stamp = (meta.created || "").replace(/[^A-Za-z0-9._-]/g, "-");
 	if (!stamp) stamp = now.toISOString().replace(/\.\d+Z$/, "Z").replace(/:/g, "-");
 
-	const changeDir = path.join(cwd, ".acstack", "changes", map);
+	const changeDir = path.join(folder, "changes", map);
 	const archiveDir =
 		map !== "ad-hoc" && fs.existsSync(changeDir)
 			? path.join(changeDir, "handoffs")
-			: path.join(cwd, ".acstack", "handoffs", map);
+			: path.join(folder, "handoffs", map);
 	try {
 		fs.mkdirSync(archiveDir, { recursive: true });
 		let dest = path.join(archiveDir, `${stamp}.md`);
@@ -664,18 +648,16 @@ export default function acstack(pi: ExtensionAPI): void {
 
 	const orchestratorFile = path.join(packageRoot, "orchestrator", "AGENTS.md");
 	const styleFile = path.join(packageRoot, "output-styles", "ac-writing-style.md");
-	const unsafeProjects = new Set<string>();
-	const isProject = (cwd: string) => !unsafeProjects.has(projectRoot(cwd)) && fs.existsSync(path.join(projectRoot(cwd), ".acstack", "project.yaml"));
+	const isProject = (cwd: string) => {
+		const folder = projectFolder(undefined, cwd);
+		return folder !== null && fs.existsSync(path.join(folder, "project.yaml"));
+	};
 	let warnedSubagents = false;
 
 	pi.on("session_start", async (event, ctx) => {
 		if (!delegated) linkClis(ctx);
-		const root = projectRoot(ctx.cwd);
-		if (ensureProjectData(ctx, root)) unsafeProjects.delete(root);
-		else {
-			unsafeProjects.add(root);
-			return;
-		}
+		projectFolders.delete(path.resolve(ctx.cwd));
+		if (projectFolder(ctx, ctx.cwd) === null) return;
 
 		if (delegated) return;
 		if (!warnedSubagents && !pi.getAllTools().some((tool) => tool.name === "subagent" || tool.name === "Agent" || tool.name === "team_agent")) {
@@ -705,7 +687,7 @@ export default function acstack(pi: ExtensionAPI): void {
 
 		if (isProject(ctx.cwd)) {
 			const orchestrator = readText(orchestratorFile);
-			if (orchestrator) sections["acstack-orchestrator"] = orchestratorFor(orchestrator, delegated ? "delegated" : "lead");
+			if (orchestrator) sections["acstack-orchestrator"] = `${orchestratorFor(orchestrator, delegated ? "delegated" : "lead")}\n\nThis repository's ACStack project folder: ${projectFolder(undefined, ctx.cwd)}\n`;
 			else report(ctx, `acstack: could not read ${orchestratorFile}`, "warning");
 		}
 
@@ -742,7 +724,7 @@ export default function acstack(pi: ExtensionAPI): void {
 		const lastText = readText(lastFile)?.trim();
 		const lastRung = lastText && /^\d+$/.test(lastText) ? Number.parseInt(lastText, 10) : undefined;
 
-		const cfg = readHandoffConfig(readText(path.join(projectRoot(ctx.cwd), ".acstack", "project.yaml")));
+		const cfg = readHandoffConfig(readText(path.join(projectFolder(undefined, ctx.cwd) ?? "/nonexistent", "project.yaml")));
 		const nudge = contextNudge(usage.tokens, usage.contextWindow, cfg, lastRung, process.env.HERDR_ENV === "1");
 		if (!nudge) return;
 
@@ -773,9 +755,9 @@ export default function acstack(pi: ExtensionAPI): void {
 			}
 		}
 
-		const root = projectRoot(ctx.cwd);
-		if (!ensureProjectData(ctx, root)) return;
-		const handoff = consumeHandoff(root);
+		const folder = projectFolder(ctx, ctx.cwd);
+		if (folder === null) return;
+		const handoff = consumeHandoff(folder);
 		if (handoff) {
 			pi.sendMessage({ customType: "acstack-handoff", content: handoff, display: true }, { deliverAs: "nextTurn" });
 		}
@@ -795,7 +777,7 @@ export default function acstack(pi: ExtensionAPI): void {
 		if (!main) return;
 		let ledger = readLedgers.get(sessionId);
 		if (!ledger) readLedgers.set(sessionId, (ledger = new Set()));
-		const result = decide({ toolName: event.toolName, toolInput: event.input, cwd: ctx.cwd, main, ledger });
+		const result = decide({ toolName: event.toolName, toolInput: event.input, cwd: ctx.cwd, main, ledger, settings: readGuardSettings(ctx.cwd, projectFolder(ctx, ctx.cwd)) });
 		if (result.block) return { block: true, reason: result.message };
 	});
 

package/profiles/fullstack-python.yaml

@@ -1,5 +1,5 @@
 # Fullstack Python (backend) + Node/TS (frontend) profile for acstack
-# Used by /acstack:setup to generate .acstack/project.yaml
+# Used by /acstack:setup to generate project.yaml in the project folder
 
 commands:
   test: "pytest tests/ --tb=short -x"

package/profiles/node-typescript.yaml

@@ -1,5 +1,5 @@
 # Node/TypeScript project profile for acstack
-# Used by /acstack:setup to generate .acstack/project.yaml
+# Used by /acstack:setup to generate project.yaml in the project folder
 
 commands:
   test: "npm test"

package/profiles/python.yaml

@@ -1,5 +1,5 @@
 # Python project profile for acstack
-# Used by /acstack:setup to generate .acstack/project.yaml
+# Used by /acstack:setup to generate project.yaml in the project folder
 
 commands:
   test: "pytest tests/ --tb=short -x"

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 changes/ directories from the pre-map workflow.
 argument-hint: "[map or legacy change name]"
 ---
 
@@ -18,12 +18,15 @@ Archive verifies implemented specs, durable decisions, and retained review evide
 
 ## Step 1: Locate the map
 
+ACStack keeps project data in the project folder, the path
+`~/.claude/acstack/bin/acstack project-data path` prints.
+
 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 "$(~/.claude/acstack/bin/acstack project-data path)/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.
+`<project folder>/changes/` directory instead, jump to Legacy below.
 
 ## Step 2: Verify no open work remains
 
@@ -83,7 +86,7 @@ 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.
+   `<project folder>/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.
@@ -98,9 +101,8 @@ Check each resolution left what it should have:
    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`.
+4. **The decision log** – read `<project folder>/decision-logs/<name>.tsv`
+   if it exists.
 
     afk runs append one row per decision an agent made alone. Hand each
     lasting decision to `record-context`. A later row supersedes an earlier
@@ -130,12 +132,12 @@ 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 `<project folder>/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 `<project folder>/maps/<name>/`                                 |
+| `true`            | move the nodes to `<project folder>/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
@@ -145,15 +147,15 @@ 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
+- Imported legacy history and original `<project folder>/alignment-packs/` artifacts
+- `<project folder>/decision-logs/<name>.tsv` files
 - Handoffs that contain review evidence or provenance not retained elsewhere
 
 Never recursively delete alignment, review, decision-log, or handoff directories as archive cleanup.
 Do not invoke a cleanup helper that erases those records.
 
 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.
+Never change the Git index or force-add records to commit them.
 
 ## Step 6: Report
 
@@ -162,19 +164,19 @@ Respect native Git ignore rules; never force-add private records.
 - 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 `<project folder>/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 `<project folder>/domain-map.yaml`.
 
 2. For each domain, merge what the feature ADDED, MODIFIED or REMOVED into
-   `.acstack/specs/[domain]/spec.md`.
+   `<project folder>/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 `<project folder>/changes/archive/[YYYY-MM-DD]-[change-name]/`.
+    It also removes the change from `<project folder>/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 the project folder's 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 `<project folder>/specs/`. The project folder is the path `~/.claude/acstack/bin/acstack project-data path` prints; pass its absolute path to every subagent that reads or writes 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 `<project folder>/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 `<project folder>/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 `<project folder>/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 `<project folder>/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 `.acstack/agent-browser.json`.
+  that endpoint via `agent-browser.json` in the project folder.
 
 - `vm-free-port.sh` for clearing a stuck port 19988 after a dropped
   session.
@@ -42,17 +42,17 @@ and is driving a real Chrome on the laptop.
 
 See the `browser-verify` skill for the install command.
 
-### 2. Create `.acstack/agent-browser.json` in each configured project
+### 2. Create `agent-browser.json` in each configured project's folder
 
 ```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:
+The project folder is the path `~/.claude/acstack/bin/acstack project-data path` prints from the repository.
+Select the config explicitly before browser commands:
 
 ```bash
-export AGENT_BROWSER_CONFIG="$(pwd)/.acstack/agent-browser.json"
+export AGENT_BROWSER_CONFIG="$(~/.claude/acstack/bin/acstack project-data path)/agent-browser.json"
 ```
 
 For manual CDP checks without project configuration, use `agent-browser --cdp 19988 ...` instead; do not pass a missing config.

package/skills/bridge/SKILL-WINDOWS.md

@@ -299,7 +299,7 @@ Two tasks run it:
 Every request from a VM carries a shared secret called the opener token.
 `register-tasks.ps1` generates it and stores it at
 `%LOCALAPPDATA%\playwriter-bridge\opener.token`. It then pushes the token over
-`ssh` to `~/.config/acstack/opener.token` on each VM.
+`ssh` to `~/.acstack/opener.token` on each VM.
 
 The token is not optional. The reverse tunnel makes 19989 reachable by
 anything running on the VM, and this service puts pages on your screen.

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 the project's 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,7 +13,7 @@ For setup (installing agent-browser, creating config files, scaffolding knowledg
 
 ## Project configuration
 
-Read `.acstack/project.yaml` for:
+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.directory` – frontend source directory
 - `frontend.dev_server_url` – dev server URL
@@ -52,7 +52,7 @@ Without `--json` it prints the same two facts on one line: the mode, then the re
 
 ### How it decides
 
-The host declares which modes this machine can provide. It does so on three axes in the global config at `~/.config/acstack/config.json`:
+The host declares which modes this machine can provide. It does so on three axes in the global config at `~/.acstack/config.json` (`$ACSTACK_HOME/config.json` when that variable is set):
 
 - `host.browser.remote` – this machine can reach a browser on another machine
 - `host.browser.headless` – this machine can launch headless Chromium
@@ -181,13 +181,13 @@ Omit `--headless` to see the browser. Useful during development.
 
 ## agent-browser command reference
 
-For configured verification, explicitly select the absolute `.acstack/agent-browser.json` path before running the commands below:
+For configured verification, explicitly select the absolute `<project folder>/agent-browser.json` path before running the commands below:
 
 ```bash
-export AGENT_BROWSER_CONFIG="$(pwd)/.acstack/agent-browser.json"
+export AGENT_BROWSER_CONFIG="$(~/.claude/acstack/bin/acstack project-data path)/agent-browser.json"
 ```
 
-- Run this from the project root only when the file exists; alternatively pass `--config /absolute/project/.acstack/agent-browser.json`
+- Run this only when the file exists; alternatively pass `--config` with the same absolute path
 - 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

package/skills/commit/SKILL.md

@@ -45,25 +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:
+The project folder is the path `~/.claude/acstack/bin/acstack project-data path` prints. Read `<project folder>/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 `<project folder>/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 `<project folder>/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 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
+5. Stage updated specs only when they sit inside the current working tree
+    - That happens only in tracked mode, when you commit in the main checkout
+    - Otherwise the specs stay updated in the project folder and out of the commit
     - Stage `DESIGN.md` and `.impeccable/design.json` too when the refresh ran
-6. Include only opted-in spec updates in the commit
-7. Flag unmapped source files and prompt user to map them
+6. 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 `<project folder>/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,8 @@ 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.
+`<project folder>/HANDOFF.md` anchor, where the project folder is the path
+`~/.claude/acstack/bin/acstack project-data path` prints. 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 +100,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  | `.acstack/.test-baseline` and referenced check logs; reuse valid evidence under the shared policy |
-| What the code does          | the living specs in `.acstack/specs/`                                              |
+| Test baseline, last result  | `<project folder>/.test-baseline` and referenced check logs; reuse valid evidence under the shared policy |
+| What the code does          | the living specs in `<project folder>/specs/`                                              |
 
 On GitHub, `--map` refuses – pipe `gh issue list` into `--stdin` per the
 map skill's `trackers/github.md`.
@@ -143,7 +144,7 @@ not optional.
 
 ## Write the anchor
 
-Write `.acstack/HANDOFF.md`. The frontmatter is **mandatory and machine-read**.
+Write `"$(~/.claude/acstack/bin/acstack project-data path)/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`.
 
@@ -218,9 +219,10 @@ 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` 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.
+`<project folder>/HANDOFF.md` holds conversation content. In global mode, the
+default, it sits outside the repository. In tracked mode it sits in the main
+checkout's committed `.acstack/`, so warn the user not to commit the anchor or
+consumed handoffs.
 
 ## Notes
 
@@ -232,8 +234,8 @@ Warn if user exceptions expose the anchor or consumed handoffs to tracking.
     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).
+  `<project folder>/handoffs/<map>/<created>.md` (legacy
+  `<project folder>/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

@@ -34,7 +34,8 @@ flowchart LR
 
 ## Author entry and element files
 
-- Default new project designs to `.acstack/designs/<id>/design.yaml`, unless the user chooses another location
+- Default new project designs to `<project folder>/designs/<id>/design.yaml`, unless the user chooses another location
+    - The project folder is the path `~/.claude/acstack/bin/acstack project-data path` prints
 - 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
@@ -172,7 +173,9 @@ relationships:
 ## 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
+- Store `Design entry: <path>` in the map root body
+    - Write the path relative to the project folder, such as `designs/<id>/design.yaml`, or relative to the repository for a design kept in the repository
+    - ACStack resolves it against the project folder first, then the current checkout
 - 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`
@@ -213,7 +216,7 @@ relationships:
 - 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/`
+- Use a nonsymlink legacy directory under `<project folder>/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
@@ -224,7 +227,7 @@ relationships:
 ```
 
 - 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 reads saved pack versions, approvals, annotations, and the corresponding decision log in the project folder
 - 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
@@ -235,4 +238,4 @@ relationships:
 - 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
+- Never change the Git index or force-add review records

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 "$(~/.claude/acstack/bin/acstack project-data path)/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,8 @@ session.
 
 ## Presentation
 
-`workflow.grilling.questions` in `.acstack/project.yaml` picks the mode:
+`workflow.grilling.questions` in `<project folder>/project.yaml` picks the mode.
+The project folder is the path `~/.claude/acstack/bin/acstack project-data path` prints.
 
 | Value            | Behaviour                                                                            |
 | ---------------- | ------------------------------------------------------------------------------------ |
@@ -127,8 +128,8 @@ belong in git:
 ```markdown
 ## Answer
 
-Map nodes stay local by default under `.acstack/maps/`.
-The user can opt in through native root `.gitignore` exceptions.
+On the files backend, map nodes live under `<project folder>/maps/`.
+In global mode, the default, that folder sits outside the repository, so nodes are never committed.
 
 The durable output is the living specs, the architecture decision records and
 the glossary. The `record-context` skill extracts each one as a node