acstack 0.0.0-stage → 0.47.0

package/skills/browser-verify/SKILL.md

@@ -0,0 +1,229 @@
+---
+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.
+---
+
+# Browser helpers
+
+## Purpose
+
+This is an operational reference for browser-based verification using the `agent-browser` CLI and Chrome DevTools Protocol (CDP). It covers commands, selector strategy, environment setup, and troubleshooting.
+
+For setup (installing agent-browser, creating config files, scaffolding knowledge base), use `/acstack:setup`. To audit what a project already has, run `acstack config check`.
+
+## Project configuration
+
+Read `acstack/project.yaml` for:
+
+- `frontend.directory` – frontend source directory
+- `frontend.dev_server_url` – dev server URL
+- `frontend.helpers_dir` – path to verification knowledge (default: `<frontend.directory>/tests/helpers/`)
+- `frontend.browser.mode` – the browser environment this project prefers: `remote`, `headless`, or `local`
+- `frontend.browser.fallback` – set it to `none` to forbid any other mode standing in. Every other value allows one
+- `frontend.browser.cdp_port` – CDP port. Default `19988` for `mode: remote` (Playwriter bridge), `9555` for `headless`/`local`.
+
+## Which browser mode to use
+
+The project states a preference. The host states what it can actually provide. One command reads both and returns the answer:
+
+```bash
+~/.claude/acstack/bin/acstack config browser-mode --json
+```
+
+It answers from declared configuration alone. It probes nothing, so it returns at once and always gives the same answer on the same machine.
+
+On exit 0 it prints one JSON object:
+
+```json
+{
+  "mode": "headless",
+  "preferred": "remote",
+  "reason": "the project prefers remote, which this host does not declare available, so headless stands in",
+  "fallback": true
+}
+```
+
+- `mode` – the browser mode to use: `remote`, `headless`, or `local`
+- `preferred` – the project's stated `frontend.browser.mode`, or `null` when it states none
+- `reason` – one sentence that explains the choice
+- `fallback` – `true` only when `mode` differs from a stated preference
+
+Without `--json` it prints the same two facts on one line: the mode, then the reason.
+
+### 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`:
+
+- `host.browser.remote` – this machine can reach a browser on another machine
+- `host.browser.headless` – this machine can launch headless Chromium
+- `host.browser.local` – this machine has a display for a visible browser
+
+`/acstack:host` sets them. From there the rules are short:
+
+1. The project's preferred mode wins when the host declares that mode available.
+2. Otherwise the first mode the host does declare stands in, in the order remote, headless, local.
+3. A project that sets `frontend.browser.fallback: none` allows no mode to stand in.
+4. A project that states no preferred mode takes the first mode the host declares. This is not a fallback, so `fallback` stays `false` and `frontend.browser.fallback` has no say.
+
+### When it has no answer
+
+The command exits 1, writes one plain-text message to stderr, and prints nothing on stdout. This happens even with `--json`, so a caller parsing the output gets an empty stdout rather than an object to check a field on.
+
+Three situations produce it. Each message names the one command that fixes it:
+
+- the project configures no frontend, or there is no ACStack project here. The message names `/acstack:setup`
+- this host declares no browser mode available, or nobody has described this host yet. The message names `/acstack:host`
+- the project forbids a fallback, and this host does not declare the mode it prefers. The message names `/acstack:host`
+
+The frontend-verifier treats exit 1 as a FAIL and reports the message verbatim. It never guesses a mode of its own.
+
+## Browser environments
+
+agent-browser works the same way in every environment. Only the CDP connection setup differs.
+
+### Remote browser (Playwriter bridge)
+
+Best experience – you interact with the user's real browser on their machine. Set `frontend.browser.mode: remote` and `frontend.browser.cdp_port: 19988` in project.yaml.
+
+Remote mode uses the Playwriter bridge.
+
+A relay runs on the browser machine and exposes a CDP-shaped endpoint. The Playwriter Chrome extension drives Chrome through the `chrome.debugger` API. Chrome itself opens no CDP listener.
+
+The dev machine reaches the relay through an SSH reverse tunnel.
+
+This section does not decide whether remote mode runs here. `acstack config browser-mode` decides that, from the project's preference and the host's `host.browser.*` axes together. Run it before you connect.
+
+Once that command returns `remote`, the answer is final. If the bridge is then down, the frontend-verifier reports FAIL with troubleshooting steps. It does not launch headless Chromium instead, because the command already ruled on any stand-in mode.
+
+#### Setup
+
+1. **On the browser machine**, install Node 18+. Install Playwriter:
+
+   ```bash
+   npm install -g playwriter
+   ```
+
+2. **In Chrome on the browser machine** (preferably a dedicated profile), install the Playwriter extension. Pin it:
+
+   ```
+   https://chromewebstore.google.com/detail/playwriter-mcp/jfeammnjpkecdekppnclgkkffahnhfhe
+   ```
+
+3. **Run two long-running processes on the browser machine**:
+
+   ```bash
+   # Relay (listens on 127.0.0.1:19988 for the extension and for tunnelled CDP clients)
+   playwriter serve --host 127.0.0.1
+
+   # SSH reverse tunnel from the browser machine to the dev machine
+   ssh -N -R 19988:127.0.0.1:19988 <user>@<dev-machine>
+   ```
+
+4. **Per-tab activation**: in Chrome, click the Playwriter toolbar icon on each tab you want automated.
+
+5. **Verify** from the dev machine:
+
+   ```bash
+   curl -s http://localhost:19988/json/version
+   ```
+
+#### Common gotchas
+
+**Playwriter hardcodes port `19988`.** The port has no config option. The relay, the extension, and the tunnel all use the same port by design.
+
+**The relay must run on the same host as Chrome.** The Playwriter extension hard-rejects any `/extension` client that is not `127.0.0.1`.
+
+Do not run the relay on the dev machine. Run the relay where Chrome runs. Then tunnel to it from the dev machine.
+
+**You must click the extension icon once per tab.** Playwriter attaches per-tab. Playwriter cannot attach to `chrome://` and `about:` pages – use normal web URLs.
+
+**Stale relay blocks the port.** If `playwriter serve` fails because a stale relay already binds port 19988 on the browser machine, run:
+
+```bash
+playwriter serve --host 127.0.0.1 --replace
+```
+
+to kick the previous relay.
+
+**Detection**: `curl localhost:19988/json/version` returns Playwriter-flavored JSON (the bridge mimics a CDP `/json/version` payload).
+
+#### Persistent cross-device setup
+
+Use the `bridge` skill for a durable Windows laptop → Linux VM setup: [`../bridge/SKILL.md`](../bridge/SKILL.md).
+
+It adds auto-reconnecting scheduled tasks, ssh-agent key persistence, multi-VM tunneling, automated diagnosis (`doctor.ps1`), canonical stop (`stop.ps1`), and VM-side port cleanup (`vm-free-port.sh`). It routes to a Windows runbook or a Linux/VM runbook based on where you are. It also defines the paste-ready handoff format for cross-device work.
+
+The scripts ship under `plugins/acstack/assets/playwriter-bridge/`.
+
+### Local headless (no display)
+
+This mode works on headless Linux VMs, CI, and containers – anywhere without a GUI.
+
+**Launch**:
+
+```bash
+chromium --headless --no-sandbox --remote-debugging-port=9555 --disable-gpu --user-data-dir=/tmp/chromium-verify &
+```
+
+Try these binary names in order: `chromium`, `chromium-browser`, `google-chrome`, `google-chrome-stable`.
+
+**Clean up**: Kill the process when done. The frontend-verifier handles this automatically.
+
+### Local with display (WSL, desktop Linux, macOS)
+
+Same as headless but with a visible browser window:
+
+```bash
+chromium --remote-debugging-port=9555 --user-data-dir=/tmp/chromium-verify &
+```
+
+Omit `--headless` to see the browser. Useful during development.
+
+## agent-browser command reference
+
+All commands assume `agent-browser.json` exists in the project root.
+
+| Command | Purpose |
+|---------|---------|
+| `agent-browser open <url>` | Navigate to a URL |
+| `agent-browser snapshot -i` | Accessibility tree with interactive element refs |
+| `agent-browser screenshot <path>` | Take a screenshot |
+| `agent-browser screenshot --annotate <path>` | Screenshot with numbered element labels |
+| `agent-browser click @e<N>` | Click an element by ref |
+| `agent-browser fill @e<N> "text"` | Clear the field, then type |
+| `agent-browser type @e<N> "text"` | Append text without clearing |
+| `agent-browser hover @e<N>` | Hover over an element |
+| `agent-browser press <Key>` | Press a keyboard key |
+| `agent-browser dblclick @e<N>` | Double-click |
+| `agent-browser drag @e<N> @e<M>` | Drag and drop |
+| `agent-browser console` | Check console errors/logs |
+
+### Critical rule: re-snapshot after DOM changes
+
+agent-browser ties element refs (`@e1`, `@e2`, etc.) to a specific DOM state. They go stale after:
+
+- Navigation
+- Clicks that change the DOM (modals, dropdowns, route changes)
+- Hot-reload after code changes
+- Any dynamic content loading
+
+Always run `agent-browser snapshot -i` again before using element refs after any DOM change.
+
+## Selector strategy
+
+When recording patterns in VERIFICATION-KNOWLEDGE.md, prefer identifiers in this order:
+
+1. `data-testid="..."` – most stable, survives refactors
+2. Accessible name/role from snapshot – e.g., "button named 'Submit'"
+3. Text content – e.g., "heading containing 'Dashboard'"
+4. CSS selectors – last resort, fragile
+
+The snapshot gives you accessible names and roles automatically. Use these to find elements rather than fragile CSS selectors.
+
+## Integration points
+
+- **frontend-verifier agent** uses agent-browser for Phase 4 verification – this skill is its reference
+- **task-checker agent** runs the static frontend checks – the `implement` skill runs frontend-verifier as its own step after the checker passes
+- **/acstack:setup** runs the setup interviews (install, config, knowledge base scaffolding) and offers a fix for each row the health check fails
+- **`acstack config check`** audits the browser infrastructure and changes nothing
+- **/acstack:quick-fix** uses agent-browser for visual verification of bug fixes

package/skills/code-review/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: code-review
+description: Apply Linus Torvalds code philosophy – eliminate special cases, prioritize simplicity, focus on data structures during code reviews and design decisions
+---
+
+# Linus Torvalds Code Philosophy
+
+Channel the mindset of Linux's creator: be direct, eliminate over-engineering, and prioritize simplicity.
+
+## Core Principles
+
+- **"Good Taste"**: Eliminate special cases through better design rather than adding conditionals
+- **Simplicity First**: If it needs more than 3 levels of indentation, redesign it
+- **Data Structures Matter**: "Bad programmers worry about code. Good programmers worry about data structures"
+- **Pragmatism**: Solve real problems, not imaginary ones
+
+## Communication Style
+
+- Be direct and sharp about technical issues
+- Point out problems clearly without sugar-coating
+- Focus on technical merit, not feelings
+- Call out over-engineering immediately
+
+## Problem Analysis Framework
+
+When reviewing code or making design decisions, ask these questions in order:
+
+1. **Is this a real problem?** – Reject over-design
+2. **Is there a simpler way?** – Always seek the simplest solution
+3. **What are the core data relationships?** – Design around data flow
+4. **Can we eliminate special cases?** – Redesign to avoid if/else branches
+5. **Does complexity match problem severity?** – Don't build rockets to swat flies
+
+## Application
+
+Use this philosophy when:
+
+- Reviewing pull requests or code changes
+- Making architectural decisions
+- Evaluating proposed solutions
+- Refactoring existing code
+- Designing new features
+
+The goal is always: **maximum simplicity, minimum special cases, optimal data structures**.

package/skills/commit/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: commit
+description: Create git commit(s) with proper pre-commit hook handling, MECE commit messages, safe staging, and mandatory living spec sync. Invoke whenever work is about to be committed – the user asked to commit, or told you to finish and commit a batch of work. Never commit with raw git commands instead; this skill is the only path that runs spec sync, so bypassing it silently stops living specs from updating. Committing is still the user's call – do not invoke it unprompted on work they have not asked you to land.
+argument-hint: "[scope: 'all', or describe which changes]"
+---
+
+## User input
+
+```text
+$ARGUMENTS
+```
+
+Scope argument: "all" commits everything (staged + unstaged + untracked), or describe which changes to include (e.g., "just the frontend changes", "only the auth module"). Defaults to "all" if no argument given.
+
+## Step 1: Analyze Changes
+
+1. Run `git status` to see all changed files
+2. Run `git diff` and `git diff --cached` to see content of changes
+3. Run `git log --oneline -5` to see recent commit style
+4. Determine scope from `$ARGUMENTS`
+
+## Step 2: Plan Commits
+
+Analyze changes and decide: one commit or multiple?
+
+**Multiple commits when** changes are MECE (mutually exclusive, collectively exhaustive) across different concerns:
+
+- Different features/fixes in different files
+- Test changes separate from implementation
+- Config changes separate from code changes
+
+**Single commit when** all changes serve one purpose.
+
+## Step 3: Draft Commit Message(s)
+
+For each planned commit:
+
+- Summarize the "why" not the "what"
+- Use conventional commit format: `type: description`
+- Types: feat, fix, refactor, docs, chore, test, style, perf
+- Keep first line under 72 characters
+- Add body for complex changes
+
+## Step 4: Spec Sync (MANDATORY)
+
+**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:
+
+1. Read `acstack/domain-map.yaml` (if exists)
+2. Map staged files to spec domains
+3. For each affected domain where `acstack/specs/[domain]/spec.md` exists:
+    - Analyze what the staged changes add, modify, or remove
+    - Generate lightweight ADDED/MODIFIED/REMOVED entries
+    - Update the domain's spec.md
+4. Refresh `DESIGN.md`, per Step 2 of the `sync` skill
+5. Stage any updated spec files
+    - Stage `DESIGN.md` and `.impeccable/design.json` too when the refresh ran
+6. Include spec updates in the commit
+7. Flag unmapped source files and prompt user to map them
+
+**Skip spec sync ONLY when:**
+
+- `workflow.spec_sync` is explicitly `false` in project.yaml
+- No `acstack/domain-map.yaml` exists
+- 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)
+
+**Those conditions govern the living specs only.** The `DESIGN.md` refresh
+answers to the design gate alone. Run Step 2 of the `sync` skill whenever
+`~/.claude/acstack/bin/acstack design-gate` exits 0, even when spec sync skips.
+
+## Step 5: Stage and Commit
+
+1. Stage files according to scope
+2. Do NOT stage sensitive files (.env, credentials, secrets)
+3. Run `git diff --cached --name-only -- '*.md'` to list the staged Markdown files
+4. Run `~/.claude/acstack/bin/acstack lint-prose <files>` on that list
+5. Show the lint output to the user
+6. Create the commit with the drafted message and no `Co-Authored-By` trailer
+7. Use HEREDOC format for commit message
+8. Run `git status` after to verify
+
+Skip steps 4 and 5 when that list is empty, because `lint-prose` exits 1 with no paths. The lint warns and never blocks. Commit even when it reports findings.
+
+## Step 6: Handle Pre-commit Hook Failures
+
+If commit fails due to pre-commit hooks:
+
+1. Read the hook output to understand the failure
+2. Fix the issue (formatting, linting, secrets detection)
+3. Re-stage fixed files
+4. Create a NEW commit (never amend)
+
+## Important Rules
+
+- NEVER add a `Co-Authored-By` trailer, even if a default instruction elsewhere tells you to
+- NEVER use `--no-verify` to skip hooks
+- NEVER amend existing commits unless explicitly asked
+- NEVER push unless explicitly asked
+- NEVER stage `.env`, credentials, or secret files
+- NEVER use `git add -A` or `git add .` – stage specific files
+- Always create NEW commits after hook failures
+- Prefer specific file staging over broad patterns
+- Spec sync is MANDATORY – do not skip it unless explicitly disabled in project.yaml

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

@@ -0,0 +1,241 @@
+---
+name: compact-and-continue
+description: Anchor the session's load-bearing state so it survives an imminent context compaction, then hand the user a /compact line steered at the work. Writes only what nothing on disk holds – the next action, decisions already made, blockers, file ownership – and references everything else. Invoke before compacting a long session, when the context window is filling and the work must stay in THIS session rather than move to another agent. Model-invocable, because the agent is the only party that can see its own context filling.
+argument-hint: "[focus note – what must not be lost]"
+---
+
+## User input
+
+```text
+$ARGUMENTS
+```
+
+Treat the argument as the focus for the session after compaction – the thing
+that must survive above all else.
+
+# Compact and continue
+
+Compaction replaces the conversation with a summary. The summary carries the
+narrative better than any template, but it is lossy.
+
+A handful of items are too load-bearing to risk losing. This skill writes
+those items to an anchor file. A SessionStart hook re-injects the file the
+moment the session resumes, so the work continues here rather than moving to
+a fresh agent.
+
+## Only the lead session runs this
+
+An agent that another agent launched stops here. One Bash call tells you
+whether you are one. Replace `<nonce>` with eight random hex characters, picked
+fresh, and never with a value already used in this session:
+
+<!-- lead-check: tests/test-skill-gates.sh extracts and runs the block below -->
+
+```bash
+n=acstack-whoami-<nonce>
+s="${CLAUDE_CODE_SESSION_ID:-none}"
+p="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/projects"
+case "${PI_SESSION_FILE:-}" in
+  */run-[0-9]*/session.jsonl|*/forks/*.jsonl) echo "child: $PI_SESSION_FILE"; exit 0;;
+  ?*) [ -z "${CLAUDE_CODE_SESSION_ID:-}" ] && { echo "lead"; exit 0; };;
+esac
+for _ in $(seq 1 20); do
+  m=$(grep -lF "$n" "$p"/*/"$s"/subagents/agent-*.jsonl 2>/dev/null </dev/null | head -1)
+  [ -n "$m" ] && { echo "child: $m"; exit 0; }
+  grep -qF "$n" "$p"/*/"$s".jsonl 2>/dev/null </dev/null && { echo "lead"; exit 0; }
+  sleep 0.5
+done
+echo "lead"
+```
+
+`lead` means carry on. `child: <path>` means stop, and tell whoever launched
+you that this skill runs only in the lead session. Report your state upward
+instead – in your final message, or through your host's agent-messaging tool
+(`SendMessage` on Claude Code). The lead then hands off
+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.
+
+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:
+
+- **No environment variable answers this.** `CLAUDE_CODE_CHILD_SESSION` holds
+  `1` in every Bash subprocess, lead or child. It marks "spawned by Claude
+  Code", nothing more. An in-process child session shares the lead's
+  `CLAUDE_CODE_SESSION_ID`, `CLAUDE_PID` and `CLAUDE_CODE_ENTRYPOINT`.
+
+- **The command hunts for its own record, so it waits.** The host writes that
+  record while the command runs, roughly four seconds in. One grep with no loop
+  runs too early, finds nothing and answers `lead` for everyone. Never flatten
+  the loop.
+
+- **The nonce must be yours alone.** Reuse one, or take one from a prompt, and
+  another agent's transcript answers for you. The angle brackets make an
+  unsubstituted copy a bash syntax error. That beats a silent match on whatever
+  agent read this file before you, so never soften `<nonce>` to a bare word.
+
+- **`<session>.jsonl` can only ever say `lead`.** Your own mark lands there
+  whether you are the lead or not. So the loop reads the agent transcripts
+  first, and treats that file as an early exit rather than evidence of a child.
+
+- **No evidence means lead.** The old gate read a variable that is always set.
+  It answered `child` in every session, and neither skill could run (#146).
+
+    Ten seconds with no matching transcript answers `lead` instead. A teammate
+    running as its own top-level session lands here, and rightly: it owns its
+    own marker.
+
+## The rule that governs the anchor
+
+*Reference state. Never copy it.*
+
+An anchor that restates the repository is a second copy of the repository,
+correct only at the instant you wrote it. If the resumed session can learn
+something by running a command, it should run the command.
+
+| Do not write it down        | The resumed session gets it from                                                 |
+| --------------------------- | -------------------------------------------------------------------------------- |
+| 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/`                                              |
+
+On GitHub, `--map` refuses – pipe `gh issue list` into `--stdin` per the
+map skill's `trackers/github.md`.
+
+The same applies to specs, architecture decision records, issues and commits.
+Reference them by path or URL.
+
+**You do not search the codebase for this.** Build the anchor from what is
+already in context. If you are about to search source files, stop – the
+conversation holds it.
+
+## What only an anchor can carry
+
+*Five things. Nothing on disk records them, so the resumed session loses
+anything you leave out.*
+
+1. **Next action** – the single concrete thing to do first
+2. **Decisions made** – so the resumed session does not reopen and re-argue them
+3. **Open questions and blockers** – including anything waiting on the user
+4. **Agent-team file ownership** – each scope, its agent, and its
+   non-overlapping files. Name any shared file to touch only after the team
+   finishes. Nothing derives it
+
+5. **Suggested skills** – which skills the resumed session should invoke, by name
+
+Omit any that do not apply. Do not pad.
+
+A session that no longer has this conversation reads the anchor. Prose follows
+the `writing` skill.
+
+## Redaction
+
+*The anchor lands in the working tree.*
+
+Strip credentials, tokens, API keys, connection strings and personal data
+before writing. Reference where a secret lives rather than its value. This is
+not optional.
+
+## Write the anchor
+
+Write `acstack/HANDOFF.md`. The frontmatter is **mandatory and machine-read**.
+The hook ignores any file without the marker, so it never touches a user's own
+unrelated `HANDOFF.md`.
+
+Set `map` to the name of the active map, or to `ad-hoc` when none is active.
+Set `created` to the current time, in ISO 8601 UTC. The title repeats the
+`map` value.
+
+**Example** – the anchor for a session working the `tracker-backend` map:
+
+```markdown
+---
+acstack_handoff: 1
+map: tracker-backend
+created: 2026-08-22T14:05:00Z
+---
+# ACStack handoff – tracker-backend
+
+## Next action
+Fix the two `node frontier` cases in `cli/src/lib/frontier.test.ts` that fail
+on a map with no resolved nodes.
+
+## Decisions made
+- The files backend ships first. It needs no network, so a fresh clone works
+  offline.
+- One node type covers both questions and work. Node 14 holds the reasoning.
+
+## Open questions / blockers
+- Node 21 waits on the user. Does a resolved node keep its `blocked-by` links?
+
+## Agent-team plan
+- Scope A – cli-nodes-opus – files: `cli/src/lib/frontier.ts`, `cli/src/lib/frontier.test.ts`
+- Scope B – hooks-sonnet – files: `hooks/session-start-handoff.sh`
+- After team (shared files, sequential): `cli/src/index.ts`, `README.md`
+
+## Suggested skills
+- implement – the frontier holds three work nodes an agent can settle alone
+- record-context – node 14 settled a term the glossary does not hold yet
+
+## References
+- Map state: `~/.claude/acstack/bin/acstack node walk` and `~/.claude/acstack/bin/acstack node frontier`
+- Files in flight: `git status --short`
+```
+
+## Silence the context-pressure nudge
+
+With the anchor written, write the quiet marker. The context-pressure Stop hook
+reads the marker and stays silent for the rest of this session. You have
+already arranged the compaction, so the hook has nothing left to nudge about:
+
+```bash
+d="${ACSTACK_CONTEXT_PRESSURE_DIR:-${TMPDIR:-/tmp}/acstack-context-pressure}"
+sid="${CLAUDE_CODE_SESSION_ID:-${PI_SESSION_ID:-}}"; [ -n "$sid" ] && mkdir -p "$d" && : > "$d/$sid.quiet" || true
+```
+
+`CLAUDE_CODE_SESSION_ID` (`PI_SESSION_ID` on pi) is this session's own id, so the marker lands exactly
+where the hook looks for it. The lead check at the top ruled out the child
+sessions, where the variable names the lead instead.
+
+If the variable is unset, skip this step. Tell the user that the hook keeps
+nudging, which is noisy but harmless.
+
+The hook clears the marker when the session compacts. It resets its state on
+`SessionStart` with `source: compact`, so the nudge returns once the context grows
+again.
+
+## Hand over the compact line
+
+A skill cannot run `/compact` itself. Write the user a `/compact` line steered
+at this work. Name the next action, and anything they flagged in the focus
+note.
+
+Tell them to run that `/compact` line, then to type `continue`. The hook
+re-injects the anchor and retires it, so the anchor never loads twice.
+
+`acstack/HANDOFF.md` is transient working state. If `.gitignore` does not cover
+it, say so. The file holds conversation content, so nobody should commit it.
+
+## Notes
+
+- **The reload fires only when the session start source is `compact`**. It
+  does not fire on a fresh start, on resuming an earlier session, or after
+  clearing the context.
+
+    A stale anchor therefore never leaks into unrelated work. The `handoff`
+    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).
+  Collisions get a `-2` suffix
+
+- **Subagents and teammates have isolated context.** This protects the
+  orchestrator's coordination state, which is the long-lived part. Per-scope
+  work does not need it
+
+- The best defence against the compaction wall is delegating aggressively so
+  the orchestrator's context window stays lean. This is the backstop