acstack 0.0.0-stage → 0.47.0

package/cli/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "acstack-cli",
+  "version": "0.47.0",
+  "description": "CLI for the ACStack agentic coding stack",
+  "type": "module",
+  "license": "MIT",
+  "author": {
+    "name": "ac8318740"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ac8318740/spechub.git",
+    "directory": "cli"
+  },
+  "bin": {
+    "acstack": "./bin/acstack.js"
+  },
+  "files": [
+    "dist/index.js",
+    "bin/",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "npm run sync-version && node build.mjs",
+    "dev": "node build.mjs --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "test": "vitest run --pool=vmThreads",
+    "prepublishOnly": "npm run build",
+    "sync-version": "node scripts/sync-version.mjs"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.5",
+    "@types/node": "^22.0.0",
+    "chalk": "^5.4.0",
+    "commander": "^14.0.0",
+    "esbuild": "^0.24.0",
+    "eslint": "^9.39.5",
+    "fast-glob": "^3.3.0",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.67.0",
+    "vitest": "^3.0.0",
+    "yaml": "^2.7.0",
+    "zod": "^3.24.0"
+  },
+  "homepage": "https://github.com/ac8318740/spechub/tree/main/cli",
+  "keywords": [
+    "agentic-coding",
+    "acstack",
+    "planning",
+    "agent",
+    "claude",
+    "cli"
+  ]
+}

package/docs/adr/0001-ste-writing-standard.md

@@ -0,0 +1,16 @@
+# One plain-language writing standard based on ASD-STE100
+
+Every durable artifact an agent writes follows one standard. The standard lives in the `writing` skill and follows ASD-STE100 – Simplified Technical English, an aerospace standard for controlled technical writing. We adopt its rules: short sentences with a numeric cap, active voice, one instruction per sentence, one term for one meaning.
+
+We reject the "add voice" advice common in anti-AI-writing guides. Someone with no context reads the artifacts weeks later. Uniformity serves that reader better than personality.
+
+## Considered options
+
+- Adopt the Cursor `unslop` skill as is – a removal checklist plus "add soul" (first person, varied rhythm, deliberate imperfection). Rejected: removal framing tells an agent what not to do, and personality is noise in specs, ADRs and map nodes.
+- Keep the rules where they are today – restated in eight files in slightly different words. Rejected: they had already drifted, and no one could point at one file.
+
+## Consequences
+
+- The standard lives in one skill; every other skill points at it. Plugin prose must itself comply, so a sweep follows.
+- A deterministic lint, `acstack lint-prose`, checks what a grep can check. It warns and never blocks, because sentence-length heuristics misfire in tables and code.
+- The ASD-STE100 dictionary requires a license, so the plugin does not reproduce it; it ships its own short vocabulary table instead.

package/docs/adr/0002-version-gate-not-auto-bump.md

@@ -0,0 +1,35 @@
+# A PR gate enforces the version bump; CI never bumps it
+
+The Claude Code plugin cache is keyed by the version in
+`.claude-plugin/plugin.json`, so a merge to `main` that does not change the
+version is invisible to every installed copy. A pull request gate
+(`scripts/version-gate.sh`, run by the `version-gate` workflow) fails the check
+when a shipped path changed without a higher version, rather than CI bumping
+the version itself. The author decides the semver level, because deriving it
+from commit message prefixes is brittle and gets the level wrong exactly when
+it matters.
+
+## Considered options
+
+- **Auto-bump on push to `main`.** CI raises the patch version whenever shipped
+  files land. Removes the failure, but a feature or a breaking change ships as
+  a patch, and CI has to write to `main`.
+
+- **release-please.** Derives the level from Conventional Commit prefixes and
+  opens a release pull request. Correct only when every commit is labelled
+  correctly, which squashed merges and hand-written subjects do not guarantee.
+
+- **A pull request gate.** CI refuses the merge; a human sets the version.
+  Chosen.
+
+## Consequences
+
+- `main` needs branch protection with `version-gate` as a required status
+  check. Without it the gate is advisory.
+
+- A shipped change that genuinely should not roll out needs the `no-bump` label
+  on the pull request. A version that goes down fails even with the label.
+
+- Documentation-only paths are exempt, listed as `INERT_PATHS` in the script
+  and duplicated in CONTRIBUTING.md. The two lists have to be kept in sync by
+  hand.

package/docs/adr/0003-handoff-ack-command.md

@@ -0,0 +1,19 @@
+# Handoff acknowledgement is a CLI command, not a reply
+
+/acstack:handoff hands work to another agent and asks it to reply ACCEPT or DECLINE. The sender's watcher, `acstack handoff watch` (`cli/src/lib/ackwatch.ts`), grepped the receiver's transcript for that keyword, a convention an agent can drift from.
+
+The receiver now acknowledges by running `acstack handoff ack accept|decline --file <handoff-file> "<reason>"`. That command writes a sidecar `<handoff-file>.ack` file, which the watcher polls instead of the transcript.
+
+## Considered options
+
+- Wording only – tighten the ACCEPT/DECLINE prompt further. Rejected: it is still a convention, and the model can still drift from it.
+- Lenient transcript matching – match more patterns in the transcript. Rejected: it keeps the same drift risk.
+- A PreToolUse hook that blocks work until the sidecar exists – the only hard guarantee. Rejected for now: scoping the hook to handoff-launched sessions is separate work. Revisit if this failure recurs.
+
+## Consequences
+
+- The receiver can still read the handoff file first. It must run the ack command before any other tool use.
+- The watcher gains an **engaged** outcome. Engaged means no acknowledgement, but a tool call after the anchor read the handoff file or used Agent, Edit, Write, or Bash.
+- The sender sends one nudge after `ack_turns` turns, then restarts the watcher.
+- A final engaged outcome is reported as "proceeding, unacknowledged." The sender never relaunches the work elsewhere. Two agents on the same files is the one failure file ownership exists to prevent.
+- The transcript keyword match stays as a fallback, labelled `via: text`. It never writes the sidecar.

package/docs/adr/0004-dev-setup-per-host.md

@@ -0,0 +1,13 @@
+# Dev setup is declared per host, not per project
+
+A dev setup – the machine-level tools an ACStack session runs inside, such as which agent orchestrator hosts the terminal panes and git worktrees and which browser-verification modes work – is recorded in the ACStack CLI's global config (`~/.config/acstack/config.json`, keys under `host.*`), not in the project's `acstack/project.yaml`. The same repository is opened on several machines with different setups, so a per-project value would have to be wrong on all but one of them.
+
+## Considered options
+
+- `acstack/project.yaml`, like `frontend.browser.mode` – shareable and checked in, but forces one answer across every machine that opens the repo.
+- Host-level global config, with project.yaml keeping only a preference where one makes sense – chosen.
+- Both layers, with the project able to constrain the host – deferred; add only if a real conflict appears.
+
+## Consequences
+
+Skills that change behaviour on the dev setup read the global config first and then check the runtime environment to see what is actually active. The project's `frontend.browser.mode` becomes a preference resolved against what the host declares available. Host setup cannot be committed with the repo, so a fresh machine needs `/acstack:host` before worktree and browser skills behave fully.

package/docs/adr/0005-two-orchestrators-per-host.md

@@ -0,0 +1,25 @@
+# Two orchestrators coexist on one host, and a checkout's path names its owner
+
+An orchestrator is a tool that hosts agent terminal panes and git worktrees. Both herdr and Orca are orchestrators, and one host – a single developer machine – may run both at once.
+
+The host config declares each one as installed or not, at `host.orchestrators.herdr` and `host.orchestrators.orca`. A developer with both installed should not have to pick one, and the session environment already says which tool hosts a session.
+
+A session lives in the host that launched it and never moves. To continue work from the other host, open a new Claude session in the same checkout – one git worktree directory – from that host. ACStack's `/acstack:handoff` stays what it is, a handoff of a full context window.
+
+A checkout's path root names its owner. Orca owns `~/orca/workspaces/<repo>/`. Everything under herdr's worktree root, `~/.herdr/worktrees/<repo>/` by default, is herdr's.
+
+Any other path belongs to plain git. The session's host creates a checkout, and the owner removes it. The worktree skills check `orca worktree ps --json` and `herdr worktree list` before every removal, because neither tool sees the other's sessions.
+
+Orca lists herdr checkouts, and the paired phone lists them, once the repo's "show in worktree list" switch is on in the desktop app. No CLI sets it, so `/acstack:host` tells the user to.
+
+## Considered options
+
+- One declared orchestrator per host, the earlier `host.orchestrator` enum. Rejected: it forces a choice the developer does not want to make.
+- A feature that moves a running session to the other host. Rejected: neither tool offers one, and a new session in the same checkout reaches the same place.
+- Either tool removes any checkout. Rejected on pilot evidence from 2026-08-23: Orca's `rm` refuses a path outside its own root, and herdr's `remove` deletes any directory and keeps the branch.
+
+## Consequences
+
+The `teardown-worktree` skill picks the removal command from the checkout's path root, not from the session's host. It deletes the branch itself for a herdr checkout.
+
+The `new-worktree` skill never passes a path that crosses roots. A config that still sets the old `host.orchestrator` key fails `config check`, and `/acstack:host` re-declares both booleans.

package/docs/adr/0006-document-opener-service.md

@@ -0,0 +1,89 @@
+# A document opener service on the laptop, separate from the Playwriter bridge
+
+`acstack-open` sends a rendered page to the opener, a small HTTP service on
+the user's laptop. The opener stores the page and serves it back on an
+address only the laptop can reach (the loopback interface). It then hands
+that address to the user's default browser.
+
+The Playwriter bridge stays as it is, and it no longer shows a document to a
+person.
+
+A page renders on a development virtual machine, which has no browser of its
+own. The virtual machine already reaches the laptop through the bridge.
+
+The bridge is a Chrome extension plus a relay, meaning a small process on the
+laptop that the extension connects to. It lets an agent drive a real browser
+over the Chrome DevTools Protocol (CDP). Reusing it to show a page to a person
+looked like the cheaper answer.
+
+The two do not collapse into one. The bridge attaches one tab at a time, and
+only after someone clicks the extension icon. That click **arms** the tab.
+
+The bridge also drives a dedicated Chrome profile rather than the user's
+default browser. So it cannot satisfy "open this in my normal browser" at all,
+and every document through it costs an arming click first.
+
+The bridge exists so an agent can *drive* a browser. The opener exists so a
+person can *see* a page.
+
+## Considered options
+
+**Drive the existing bridge**. Rejected. Arming the bridge takes one click
+per tab, inside a separate Chrome profile.
+
+Rewriting a live page over CDP also detaches the extension outright. The
+bridge then stays down until the user arms it again by hand.
+
+**Forward a port and serve from the virtual machine**. Rejected. The user's
+terminal would open an address that a forwarded port carries back to a server
+on the virtual machine.
+
+The reverse tunnel the bridge already maintains runs the wrong way, so this
+needs a second forward. That forward comes from a `LocalForward` line in the
+user's own SSH host block, and nothing in setup writes it. The page also dies
+when the server on the virtual machine stops, which is the common case when a
+session ends.
+
+**Print a clickable hyperlink in the terminal**. Kept as the fallback, not as
+the answer.
+
+The terminal already prints one today. It costs a deliberate click for every
+single document. The requirement was to read one document after another
+without ceremony.
+
+**Open the document in the editor instead of a browser**. Rejected.
+
+The user is moving away from an editor-hosted terminal toward a plain one.
+The user asked specifically for the default browser.
+
+## Consequences
+
+A second always-on service now runs on the laptop, and every virtual machine
+gets one more tunnel task to carry it. This is deliberate.
+
+Setup already registers the relay and its tunnels as self-healing scheduled
+tasks. The opener inherits that machinery, its deployment, and its
+restart-on-change behaviour rather than inventing any.
+
+The opener gets its own tunnel rather than a second forward on the bridge's
+connection. `tunnel.ps1` passes `ExitOnForwardFailure=yes`, so one wedged
+port fails the whole `ssh` session. A stuck opener port would take the bridge
+down with it.
+
+The virtual machine can now ask the opener to restart the relay and to
+restart the tunnels. Those are two recovery actions the virtual machine could
+not perform before, and a human had to paste both into a shell. Arming stays
+manual, because it is behaviour of a third-party extension and nothing on
+either side can click it.
+
+The opener stores rendered documents on the laptop. They outlive the session
+that produced them. That is what makes a page still work after the virtual
+machine goes away.
+
+The opener prunes the store after a week.
+
+The service accepts a document and puts it on the user's screen, so a shared
+secret called the opener token guards it. Setup generates that token and
+copies it to the virtual machine. Loopback binding alone is not enough,
+because the reverse tunnel makes the port reachable by anything running on
+the virtual machine.

package/docs/adr/0007-lead-check-reads-the-transcript.md

@@ -0,0 +1,87 @@
+# A session's own transcript decides lead or child, not the environment
+
+The `handoff` and `compact-and-continue` skills run only in a **lead session**,
+because both write state the lead alone owns. An agent decides which it is by
+planting a random mark in its own transcript and then asking which transcript
+holds it.
+
+A hit under `~/.claude/projects/<project>/<session>/subagents/` means the agent
+is a subagent or a teammate. No environment variable takes part in that
+decision.
+
+The first version read `CLAUDE_CODE_CHILD_SESSION` instead. Claude Code sets
+that variable to `1` in the environment of every Bash tool subprocess, in every
+session. So the check was true unconditionally, and both skills refused to run
+everywhere (#146).
+
+The variable marks "spawned by Claude Code", and nothing finer.
+
+## Considered options
+
+- **A different environment variable.** Measured on Claude Code 2.1.241, an
+  in-process subagent and an in-process teammate both report the lead's exact
+  `CLAUDE_CODE_SESSION_ID`, `CLAUDE_PID` and `CLAUDE_CODE_ENTRYPOINT`. A child
+  runs inside the lead's own process, so no variable separates them. Ruled out
+  by measurement, not by preference.
+
+- **Drop the check and let a child run the skills.** Simplest, and wrong. A
+  child shares the lead's `CLAUDE_CODE_SESSION_ID`, so a child's quiet marker
+  silences a context-pressure nudge the lead still needs, and a child's
+  `acstack/HANDOFF.md` overwrites the lead's anchor.
+
+- **Read `taskKind` from the agent's `.meta.json`.** The host does write one
+  beside each agent transcript, naming `in_process_teammate` for a teammate and
+  omitting `taskKind` for a plain subagent. An agent cannot tell which of those
+  files is its own, so the file answers a question nobody can ask.
+
+- **Plant a mark, then find it.** Chosen. The mark is unique per agent, so the
+  answer is the agent's own and never a sibling's.
+
+## Consequences
+
+- The command polls for up to ten seconds rather than grepping once. The host
+  writes the record carrying a command while that command still runs, roughly
+  four seconds in.
+
+    A single grep therefore runs too early, finds nothing and answers
+    `lead` for everyone. A lead usually exits in about four seconds, as
+    soon as its own record lands.
+
+- The check reads a Claude Code internal layout that no public contract
+  describes. A host that renames the `subagents/` directory, or files agent
+  transcripts elsewhere, turns every child into a `lead` verdict.
+
+- Absence of evidence reads as `lead`. A host that persists no transcript
+  leaves the command empty-handed, and the skill proceeds. Failing closed is
+  what produced #146, so the failure now falls on the side that keeps the
+  skills runnable.
+
+- The agent transcripts alone decide. An agent's own mark reaches
+  `<session>.jsonl` whether it leads or not. So the loop reads that file only
+  as an early exit for a lead, never as evidence of a child.
+
+- The nonce placeholder stays angle-bracketed. `n=acstack-whoami-<nonce>` is a
+  bash syntax error, so an agent that pastes the block without substituting
+  fails loudly. A bare token would run instead. It would match every transcript
+  in the session that had already read the skill file, so the command would
+  answer `child` to a real lead.
+
+- The agent still chooses the nonce, and a language model samples randomness
+  badly. Two agents in one session that pick the same eight characters read
+  each other's transcripts. Generating the nonce at runtime cannot fix that.
+
+    The mark has to sit in the command text for the command to find it. A
+    value computed at runtime reaches the transcript only after the command
+    ends.
+
+- Both skills carry their own copy of the block, rather than calling a shared
+  script. `skills/new-worktree/detect-orchestrator.sh` shows the repo has that
+  pattern. No home exists for a script two skills share, though.
+
+    The repo also already repeats the context-pressure path expression in
+    three places. `tests/test-skill-gates.sh` asserts the two copies match
+    byte for byte. That assertion is what makes the duplication safe to keep.
+
+- `tests/test-skill-gates.sh` extracts the command from each `SKILL.md` and
+  runs it against fixture transcript layouts. The fixtures encode the layout
+  above, so they need revisiting whenever the host changes it.

package/docs/adr/0008-cli-audits-skill-interviews.md

@@ -0,0 +1,37 @@
+# The CLI audits, the skill interviews
+
+`acstack config check` is the only health check in ACStack. It reports what is
+wrong with a machine and a project. It changes nothing.
+
+`/acstack:setup` reads that report, then asks the user what to do about each
+failure. The skill writes the answers. Neither one does the other's job.
+
+The check reads `~/.claude/settings.json` and the two project settings files,
+even though Claude Code owns them and ACStack does not. A health check with a
+row it cannot see is a health check nobody can trust.
+
+## Considered options
+
+ACStack had two commands named `check`.
+
+The CLI's audited the host axes. The config skill's audited the project's
+infrastructure in prose. Neither called the other, and a user could not tell
+them apart by name.
+
+Leaving the split in place keeps ACStack's CLI reading only ACStack's own
+files. It also lets the two audits drift apart. It leaves the project half
+untestable, because continuous integration cannot run prose in a skill body.
+
+## Consequences
+
+The check grows a `--json` output, so the skill maps a failing row to the fix
+it offers. That output is an interface. Renaming a row identifier breaks the
+skill silently, so the row identifiers need tests.
+
+Every audit rule now lives in TypeScript and gets tested. No skill re-probes
+the machine with its own shell commands.
+
+A user who wants one setting changed runs `acstack config set <key> <value>`
+and answers no questions. The full key reference lives in
+`docs/config-reference.md`, because seventeen keys carry more nuance than a
+help string holds.

package/docs/adr/0009-verify-the-write-not-the-writer.md

@@ -0,0 +1,51 @@
+# The config writer verifies its result instead of predicting it
+
+`acstack config set` writes a key into `acstack/project.yaml` by splicing the
+new value over the old value's bytes, so a hand-edited file keeps its comments
+and its spacing. Before writing, it parses what it built and compares that data
+against what the YAML document interface would have produced. The two must
+agree, or the write falls back to the document interface.
+
+The writer verifies that fallback the same way. It parses the emitted text and
+compares it against the same data. A write neither path can verify refuses with
+exit 1 and leaves the file byte for byte as it was.
+
+The comparison covers the whole file, not the key that changed.
+
+## Considered options
+
+The first version predicted safety with guards on the node it was replacing.
+Three rounds of that shipped four ways to corrupt a user's file, each behind a
+green success message and exit code 0.
+
+A folded or literal block scalar's byte range runs past its trailing newline,
+so the splice ate the line break and destroyed the following key. An existing
+empty value has a zero-width range, so the write produced `test:npm test`.
+
+A new value spanning lines landed at column zero. A scalar inside a flow
+collection passed every guard, and a value holding a comma truncated the key
+and invented a second one beside it.
+
+Each guard was correct. Each author read the node and not the context around
+it. A user would have found the fifth shape.
+
+## Consequences
+
+The writer costs one extra parse per write, which nobody running a command by
+hand will notice.
+
+A key-only comparison passes every test in the suite and every input a 2020
+case sweep could reach. The writer compares the whole file anyway. Narrowing it
+means arguing about shapes nobody has constructed yet, and that argument has
+already been wrong four times.
+
+Do not narrow it to the changed key on the grounds that no test covers the
+difference. No test can.
+
+The document interface was the trusted baseline until a fifth shape broke it. A
+whitespace-only value over a block scalar with a sibling key after it emitted a
+content line no parser reads back. The value returned as the empty string,
+behind exit 0.
+
+The splice refused that write correctly and handed it to a fallback nobody
+checked. The writer checks both paths now.

package/docs/adr/0010-promote-dev-to-main-by-fast-forward.md

@@ -0,0 +1,115 @@
+# A labelled workflow fast-forwards main to dev, and nobody merges
+
+ACStack promotes `dev` to `main` by fast-forward. Open a pull request with base
+`main` and head `dev`. Review it, then add the `promote-to-main` label.
+`.github/workflows/promote.yml` checks six preconditions and moves
+`refs/heads/main` to the commit the pull request carries.
+
+GitHub then closes the pull request as merged on its own. `main` reaches every
+commit on `dev`, which is what GitHub reads as merged. The workflow pushes with
+`GITHUB_TOKEN`, so no credential sits at rest in this repository.
+
+GitHub offers no fast-forward merge. Its three options are a merge commit, a
+squash, and a rebase. Each one writes a commit to `main` that `dev` can never
+contain, and that commit forces a back-merge afterwards.
+
+Commits `ee41411` and `04602c7` are the last two the old flow cost. The open
+question was how to stop a person merging into `main`. `GITHUB_TOKEN` bypasses
+nothing, which rules out the usual answer.
+
+## Considered options
+
+A GitHub App can hold a bypass on a ruleset, so an App blocks the Merge button
+outright. We rejected it for two reasons. Its private key would sit in a
+repository secret and need rotating by hand, and this repository has one person
+in it.
+
+We rejected a fine-grained personal access token for two other reasons. It
+expires silently. Its bypass would also come from the owner's admin role, which
+leaves the Merge button open to the very person the rule binds.
+
+We chose `GITHUB_TOKEN`. Nothing sits in a secret, the token expires when the
+job ends, and GitHub scopes it to this repository.
+
+That choice rules out a bypass, so the block comes from somewhere else. It comes
+from a required check that no ordinary pull request ever gets: `promotion-gate`.
+Only `promote.yml` creates it.
+
+A pull request into `main` without the label is missing that check and cannot
+merge. `enforce_admins` extends that to admins. The workflow posts the check
+green immediately before it moves the ref, then flips it to failed if the push
+does not land.
+
+A personal repository could not have taken the App route anyway. The rulesets
+API rejects the GitHub Actions integration as a bypass actor. Classic branch
+protection rejects a bypass list outright.
+
+Both errors came from this repository, and `promote.yml` quotes both messages.
+
+## Consequences
+
+`main` stays an ancestor of `dev` by construction. The next promotion therefore
+fast-forwards too, and nothing is ever stranded on `main`.
+
+Three things follow as rules rather than preferences. No merge commit, squash,
+or rebase onto `main`. No cherry-pick onto `main`, since a new SHA makes the two
+graphs diverge for good.
+
+No back-merge of `main` into `dev` either. A fast-forward strands nothing there.
+
+The Merge button works for about a second per promotion. That is the gap between
+`promotion-gate` going green and the ref moving, inside a run an admin
+triggered. Pressing it there writes a merge commit to `main`, and the
+fast-forward then refuses and says so.
+
+The gate step therefore sits as late in the job as it can. Every new
+precondition belongs above it.
+
+A push made with `GITHUB_TOKEN` starts no workflow runs. `tag-release.yml` would
+never fire, and a promotion would tag nothing. `promote.yml` dispatches it
+explicitly through `workflow_dispatch`. GitHub documents that event as always
+creating a run.
+
+Nothing enforces that coupling. Add any future workflow that triggers on a push
+to `main` to the dispatch step by hand.
+
+`tag-release.yml` no longer compares `HEAD` against `HEAD~1`. A fast-forward
+carries every commit `dev` collected, so `HEAD~1` is the second-newest `dev`
+commit rather than `main`'s previous tip.
+
+Most of those commits leave the version alone, so the old comparison would read
+"unchanged" and skip the tag. The workflow now tags whatever version `main`
+holds, unless that tag already exists.
+
+The label that starts a promotion used to sabotage it. `version-gate.yml`
+triggers on `labeled` and `unlabeled`, so adding `promote-to-main` started a
+fresh `version-gate` run on the same commit.
+
+That run is pending while the promotion reads the checks and pushes, and branch
+protection refuses a push whose required check is pending. Removing and re-adding
+the label fired the gate twice more, so the advice for a stuck promotion made it
+permanent.
+
+`version-gate.yml` now skips every label event except `no-bump`. That is the one
+label which changes its verdict. A skipped job reports as passing, so the earlier
+green run still stands.
+
+`promote.yml` also waits up to ten minutes on a pending or absent check, rather
+than refusing it.
+
+The close step looks the gate up by name on the commit, not by the id the open
+step captured. A `POST` can land while `gh` still exits non-zero on a dropped
+response read. Trusting that id would leave the gate green and the pull request
+mergeable by hand.
+
+One hole stays open. A runner killed between the gate opening and the ref moving
+leaves `promotion-gate` green with no job left to close it. Close the pull
+request, or set that check run to `failure` by hand.
+
+An admin can still turn branch protection off in the repository settings. No
+configuration prevents that on any plan. This decision makes merging into `main`
+impossible, not repository administration.
+
+`promote.yml` names five CI checks by their `name:` values in `ci.yml`,
+`tests.yml`, and `version-gate.yml`. Rename a job in one place without the
+other, and every promotion blocks. The workflow says so when it happens.

package/docs/adr/0011-node-header-is-the-edge-encoding.md

@@ -0,0 +1,20 @@
+# The node body header is the authoritative edge encoding on GitHub
+
+Every map node on the GitHub tracker opens its body with one header line. It names the node's map, its root, its `answers` parent, its `blocked-by` ids, and its short `label`. Every composed query reads its edges from that line.
+
+The tracker still writes GitHub's native sub-issue and dependency links. Those links drive GitHub's own interface, and no query reads them.
+
+The header costs one `gh issue list` call to read the whole graph, because `body` is one of the fields that command returns.
+
+## Considered options
+
+- Read the edges from GitHub's native links. Rejected: the parent needs a GraphQL query and the blockers need a REST call, both per issue. A forty-node map would spend eighty calls on every frontier recompute.
+- Drop the native links and keep only the header. Rejected: the links render a map inside GitHub's own issue interface. That is half the reason to pick this tracker.
+- Give the files backend the same header. Rejected: its frontmatter already holds `answers` and `blocked-by`, and its directory name is the map. A header there would copy data the CLI owns, free to drift from it.
+
+## Consequences
+
+- One edge lives in two places on GitHub. The tracker doc states the dual write as a single step, for adding an edge and for removing one. A write that updates one copy alone leaves the two out of step.
+- A degraded remote, meaning one where GitHub's link features are off, now loses only the link interface. Every query keeps working. The tracker needs no second encoding and no per-map choice between them.
+- A reader landing on an issue from a notification sees which map it belongs to and what sits above it. The issue title alone never told them.
+- The two backends no longer share one body shape. A header line on GitHub, frontmatter on files.

package/docs/adr/0012-node-kind-is-a-closed-set-of-five.md

@@ -0,0 +1,31 @@
+# A map node's kind is a closed set of five
+
+A map node carries one `kind`. It is one of `destination`, `notes`, `decision`, `research`, or `work`.
+
+The CLI enforces the set with a zod enum. It rejects anything else at create, at update, and on reading a stored file. Before this, `kind` was free text that the CLI called advisory only.
+
+The five split in two. `destination` and `notes` are records rather than questions. `decision`, `research`, and `work` are things still to settle.
+
+The two records resolve differently. `notes` resolves the moment someone writes it. `destination` is the root, and it carries no status of its own.
+
+The root's state follows its subtree. It stays open while any node below it still needs work. `archive` resolves it when the map clears.
+
+Each has one test.
+
+- `destination` is the root, one per map
+- `notes` holds no question, and it binds every other node
+- `decision` has two or more defensible answers
+- `research` has one findable answer
+- `work` ends in a diff
+
+## Considered options
+
+- Keep `kind` free text and let the generated legend list only the kinds a map happens to contain. Rejected: `kind` now picks a node's shape in the map diagram, and an unknown value has no drawing.
+- Fix a set of six, to leave one slot spare. Rejected: every candidate sixth landed inside an existing kind. A bug is `work`, a spike is `research`, and a glossary term is a `decision` about what a word means.
+
+## Consequences
+
+- Five kinds map to five distinct mermaid shapes, so shape carries kind and the other channels are free for status, mode, and the frontier.
+- Every node must name a kind, and nothing can clear it. A node with no kind has no shape, so the field cannot be optional.
+- The enum rejects any map still carrying an older kind such as `grilling` or `task`. That is acceptable, because nodes are transient working state a map throws away at archive.
+- `kind` and `mode` will agree most of the time, and the disagreements are the point. A `decision` node marked `afk` draws as a dashed rhombus, which is an agent about to settle something that was the human's.

package/docs/adr/0013-the-diagram-renderer-is-pure.md

@@ -0,0 +1,23 @@
+# The diagram renderer takes nodes in and never calls gh
+
+`acstack node diagram` reads nodes and writes mermaid. It reads them from disk for a named map, or as JSON on stdin. It makes no network call and needs no authentication.
+
+On the GitHub backend the agent runs the pipe itself:
+
+```bash
+gh issue list --label "map:<name>" --state all --limit 500 \
+  --json number,title,body,state,stateReason,labels,url \
+  | acstack node diagram --stdin
+```
+
+## Considered options
+
+- Have the CLI run `gh issue list` itself behind a `--tracker github` flag. Rejected: the invocation would then live in both `cli/src/` and `skills/map/trackers/github.md`, and this repository's own rule is that one fact gets one home. It is also nicer for the agent, which is the whole case for it.
+- Give the CLI a real GitHub backend that speaks to the API. Rejected: far larger than this effort needs, and it would put authentication inside a renderer.
+
+## Consequences
+
+- The renderer's tests are JSON fixtures. No subprocess, no network, no token, and 59 tests run in the same suite as everything else.
+- Both backends reach one rendering path. One line branches on the backend, and the specification demands it: a node id wraps in an anchor when the node carries a URL.
+- The agent runs two commands instead of one. `skills/map/trackers/github.md` states the pipe verbatim, so nobody composes it from memory.
+- The CLI gained `readStdin`, because `readFileSync(0, 'utf-8')` fails with EAGAIN when a parent process hands over a non-blocking fd 0. An agent harness does exactly that.