acstack 0.0.0-stage → 0.47.0

package/skills/host/orca.md

@@ -0,0 +1,160 @@
+# Orca follow-up
+
+Read this file when the user declared Orca installed in Step 2.
+
+- `plugin_root` and the detection output come from Step 1 in `SKILL.md`
+- Step 5 in `SKILL.md` lists the exit codes both installers share
+
+### When you declared Orca installed
+
+**Register this repository.** Orca's `worktree create` fails with
+`repo_not_found` until you register the repository with Orca. Registration is a
+separate step, and it comes after the install rather than inside it. Register it
+now:
+
+```bash
+orca_bin="<orchestrator.orca_binary from the Step 1 detection output>"
+"$orca_bin" repo add --path "$(git rev-parse --show-toplevel)" --json
+```
+
+Fill the placeholder in from the detection output's
+`orchestrator.orca_binary`, an absolute path. Do not hardcode a name. The Linux
+executable is `orca-ide`, with `orca` as an alternative on some installs, so a
+hand-written name is right on only some machines.
+
+A `null` in that field means
+this machine has no Orca, so nothing needs registering. See "When Orca is not
+installed here" below instead.
+
+The command is idempotent, so it is safe to run when the repository is already
+registered. All Orca `--json` output is an envelope of the form
+`{id, ok, result|error, _meta}` – read `.ok` rather than assuming the command
+worked. Tell the user that Orca has no `repo rm` command, so registration only
+goes one way.
+
+Skip this step when the current directory is not inside a git repository, and
+say why rather than failing silently.
+
+**State the Claude settings rewrite**, whether or not the user asks about it.
+Word it plainly:
+
+> The first time Orca starts, it rewrites `~/.claude/settings.json`. It adds its
+> agent hook to 11 hook events: SessionStart, UserPromptSubmit, Stop,
+> StopFailure, SubagentStart, SubagentStop, TeammateIdle, PreToolUse,
+> PostToolUse, PostToolUseFailure and PermissionRequest. The hook does nothing
+> unless the `ORCA_PANE_KEY` environment variable holds a value, so it is inert
+> outside an Orca terminal. Orca keeps your original file at
+> `~/.claude/settings.json.bak`. Orca also writes `~/.orca/agent-hooks/` and
+> `~/.config/orca/`.
+
+Use the detection output to say whether this looks to have happened on this
+machine already (`claude_settings.orca_hooks_present`) and whether the backup
+exists (`claude_settings.backup_exists`). Word the first as evidence rather than
+as a finding. The check is a loose text search for the word "orca" anywhere in
+the settings file, so something unrelated can set it.
+
+Call out the combination worth a look: a settings file that mentions Orca with
+no `~/.claude/settings.json.bak` beside it may mean the original settings were
+never preserved. Tell the user to open the file and check before trusting it.
+Do not tell them they lost their settings – the evidence does not carry that.
+
+**When Orca is not installed here** – `orchestrator.orca_binary` is `null` –
+say that Orca is missing, and offer to install it.
+
+The installer is `install-orca.sh`, beside this file. Resolve its path the way
+Step 1 in `SKILL.md` resolves `detect-host.sh`, through `plugin_root`.
+
+Ask two things before you plan anything, in one call to the question tool (AskUserQuestion on Claude Code):
+
+1. The port the server listens on. Default it to 6768.
+2. The address a client pairs to. Pre-fill it from `tailscale ip -4` when Step 1
+   found Tailscale installed and logged in.
+
+Say where a pre-filled address came from, so the user can recognise it. Leave
+the pairing address out when Tailscale is missing or logged out.
+
+Then plan the install. Build one option list here and use it twice:
+
+```bash
+bash "$plugin_root/skills/host/install-orca.sh" --plan \
+  --port <port> --pairing-address <address> --mobile-pairing
+```
+
+`--mobile-pairing` gets a mobile-scoped pairing offer, which is what a phone
+needs. Run the plan and the apply with the same options.
+
+The script builds the unit text from the options. Three steps read their status
+from that text.
+
+A flag added after the plan therefore changes what runs. The plan is what the
+user approved.
+
+`--plan` writes nothing. It prints one numbered line per step, and each line
+ends in `[todo]` or `[skip: <reason>]`. Show that list to the user verbatim,
+every line of it.
+
+Then state the Claude settings rewrite, before the user approves anything.
+Orca's first start rewrites `~/.claude/settings.json` and keeps the original at
+`~/.claude/settings.json.bak`. Use the wording in the "State the Claude settings
+rewrite" block above, rather than a second version of it.
+
+Now put the whole step list in front of the user with the question tool, and let
+them decline. Declining is a real answer. Nothing runs, and this skill carries
+on to the report in Step 6 of `SKILL.md`.
+
+On approval, run the identical command with `--apply` in place of `--plan`:
+
+```bash
+bash "$plugin_root/skills/host/install-orca.sh" --apply \
+  --port <port> --pairing-address <address> --mobile-pairing
+```
+
+An apply line ends in `[done]` or `[skipped: <reason>]`. Every step is
+idempotent, so a second run repeats nothing it already did.
+
+What the install puts on the machine:
+
+- the AppImage – a single-file Linux application bundle – under
+  `~/.local/opt/orca/`
+
+- `orca-ide` and `orca` symlinks in `~/.local/bin`, so either name works
+- a systemd user unit at `~/.config/systemd/user/orca.service`, meaning a
+  background service owned by the user rather than by the system
+
+- `ORCA_TELEMETRY_DISABLED=1`, set in that unit
+
+The unit wraps the server in `/usr/bin/script -qec "..." /dev/null`. That is how
+the readiness JSON the server prints reaches the system journal. The install
+needs no root access for any of it.
+
+Two options cover a machine that cannot reach the default download.
+`--appimage-url URL` replaces that URL, which is
+`https://github.com/stablyai/orca/releases/latest/download/orca-linux.AppImage`.
+`--appimage-path PATH` takes a local file instead.
+
+The last step of the apply reads the journal itself and prints the pairing URL.
+The pairing URL is the link a client uses to connect to this Orca server. Give
+it to the user.
+
+That step skips in three cases.
+
+It skips when the apply neither started nor restarted the server, because an
+untouched server keeps the pairing URL it already had. It skips when the journal
+holds no readiness line yet, which happens when the server has started and has
+not printed its block. It skips when `journalctl` is missing, and prints this
+command instead.
+
+Run it yourself whenever a skip leaves the pairing URL unknown:
+
+```bash
+journalctl --user -u orca.service -n 100 --no-pager
+```
+
+`--mobile-pairing` stays in the unit. The script never removes it, so the server
+offers mobile pairing on every restart. Removing it is the user's own step, and
+it means editing the unit and restarting it:
+
+```bash
+${EDITOR:-nano} ~/.config/systemd/user/orca.service
+systemctl --user restart orca
+```

package/skills/host/questions.md

@@ -0,0 +1,163 @@
+# Host questions
+
+`SKILL.md` decides when to read this file: before asking the first question.
+It holds what each detection field is evidence for, and the exact wording of
+every question in Steps 2 and 3. `SKILL.md` defines each step.
+
+## Detection fields (Step 1)
+
+What it reports, and what each field is evidence for:
+
+| Field | Evidence for |
+| --- | --- |
+| `orchestrator.herdr_binary` | herdr is installed here (absolute path, or `null`) |
+| `orchestrator.orca_binary` | Orca is installed here – the executable is `orca-ide`, with `orca` as an alternative on some installs |
+| `orchestrator.hosting_this_session` | Which orchestrator's terminal pane this very session is running in, read from the variable each one exports: `ORCA_PANE_KEY` for Orca, `HERDR_ENV` for herdr |
+| `browser.agent_browser_binary` | The `agent-browser` command-line tool, which is what drives a browser during verification |
+| `browser.bridge_port_answers` | Something answered on local port 19988, which is where the Playwriter bridge – a reverse-SSH setup that lets an agent on this machine drive a real Chrome browser on the developer's own machine – forwards that browser's debugging port |
+| `browser.chromium_binaries` | Chromium-family browsers found on this machine, which is what headless verification launches |
+| `browser.display` | A graphical session exists (`DISPLAY` or `WAYLAND_DISPLAY` is set), without which nobody can watch a visible browser |
+| `preview.tailscale_binary`, `preview.tailscale_logged_in` | Tailscale is installed, and separately whether anyone has logged it in – an installed but logged-out Tailscale publishes nothing |
+| `element_picker.stagewise_binary` | `stagewise` is installed – an element picker, meaning a tool that lets the user click an element in the running app and hand the reference to an agent |
+| `orca_topology.serve_unit_active` | A user-level service named exactly `orca` is running, which is the shape of a machine serving Orca to a viewer elsewhere. The name is an assumption: whatever provisions the server picks it, and nothing pins it yet. A unit installed under any other name reads here as "no server". The topology recommendation below then comes out `local` when this machine has Orca, and stays empty when it does not |
+| `claude_settings.orca_hooks_present` | `~/.claude/settings.json` mentions Orca somewhere. The match is a loose, case-insensitive search for that word anywhere in the file, so an unrelated path or permission entry containing it counts too – this is evidence that Orca has wired its hooks in, not proof |
+| `claude_settings.backup_exists` | `~/.claude/settings.json.bak` exists |
+| `project.root`, `project.has_frontend` | The git repository the current directory sits in, and whether its `acstack/project.yaml` configures a frontend |
+
+Several sections also carry a `recommended` field. That is the script's
+mechanical reading of the evidence above it and nothing more. It is a starting
+point for a question, never an answer.
+
+## 2a. Orchestrators
+
+```json
+{
+  "question": "Is herdr installed on this machine?",
+  "header": "herdr",
+  "options": [
+    {"label": "yes", "description": "herdr is installed here. It owns terminal panes and creates worktrees under ~/.herdr/worktrees. <detected evidence, if any>"},
+    {"label": "no", "description": "herdr is not installed here. <detected evidence, if any>"}
+  ]
+}
+```
+
+```json
+{
+  "question": "Is Orca installed on this machine?",
+  "header": "Orca",
+  "options": [
+    {"label": "yes", "description": "Orca (stablyai/orca) is installed here. It owns panes and creates worktrees under ~/orca/workspaces. <detected evidence, if any>"},
+    {"label": "no", "description": "Orca is not installed here. <detected evidence, if any>"}
+  ]
+}
+```
+
+Fill each `<detected evidence, if any>` placeholder from the Step 1 detection
+output. Put the evidence into whichever option it supports, so the recommended
+answer is the one carrying it. Judge each orchestrator on its own fields only –
+herdr from `orchestrator.herdr_binary`, Orca from `orchestrator.orca_binary`,
+and both from `orchestrator.hosting_this_session`, which names at most one of
+them:
+
+- `orchestrator.hosting_this_session` names this orchestrator – recommend yes:
+  "detected: this session is running in a herdr pane", or the same sentence
+  about Orca.
+
+- Its binary is present – recommend yes: "detected: installed at `<path>`".
+  When the session is also running in its pane, say both facts.
+
+- Neither is true for it – recommend no: "not installed on this machine".
+
+Leave a placeholder out entirely when there is nothing to say about that option.
+
+## 2b. Browser-verification modes
+
+```json
+{
+  "question": "Which browser-verification modes work on this machine?",
+  "header": "Browser",
+  "multiSelect": true,
+  "options": [
+    {"label": "remote", "description": "Drive a real browser on your own machine over the Playwriter bridge. <detected: something answers on port 19988 | nothing is answering on port 19988>"},
+    {"label": "headless", "description": "Launch headless Chromium here – no window, no display needed. <detected: Chromium found at <path> | no Chromium-family browser found>"},
+    {"label": "local", "description": "Launch a visible browser here – needs a graphical display. <detected: browser and display both present | no graphical display>"},
+    {"label": "none of these", "description": "No browser verification works on this machine at all. This is an answer, not a skip: it declares all three modes false."}
+  ]
+}
+```
+
+A selected mode is `true`. An unselected mode is `false`.
+
+The fourth option exists because a multi-select gives the user no way to press
+"nothing". Choosing "none of these" writes all three axes –
+`host.browser.remote`, `host.browser.headless` and `host.browser.local` – as
+`false`. That is a declaration, not a skip: the user has said this machine
+cannot verify in a browser, and Step 4 writes it.
+
+If it comes back selected alongside a real mode, that is a contradiction; take
+the named modes as the answer and ignore it.
+
+The no-frontend branch below adds a fifth option, "Decide later". If that comes
+back selected alongside "none of these", those two are opposites: one writes all
+three axes `false`, the other writes nothing at all. Take "Decide later" as the
+answer and write nothing.
+
+An unset axis is recoverable. The next run of this skill asks again, and the
+health check says plainly that the axis is missing.
+
+A `false` written by mistake is not recoverable in the same way. It reads as a
+decision the user made, so nothing asks again and the machine quietly looks
+incapable.
+
+When to treat the question as required: the browser axes become required as soon
+as *any* project on this machine has a frontend. Nothing available here can see
+that.
+
+The detection output's `project.has_frontend` looks only at the git repository
+the current directory sits in. So it reports on that one project, and says
+nothing about the other checkouts on this machine.
+
+So read it as a floor, not as the whole answer:
+
+- `project.has_frontend` is true – ask with no escape. The modes have to be
+  declared.
+
+- It is false, or there is no ACStack project in the current directory at all –
+    still ask. The next project opened on this machine may well have a frontend,
+    and this skill runs once per machine.
+
+    Add a "Decide later" option, and state the consequence plainly. The three
+    `host.browser.*` axes stay unset. The health check
+    `~/.claude/acstack/bin/acstack config check` then fails the first time
+    anyone runs it in a project that has a frontend.
+
+## Step 3: The optional axes
+
+1. **Preview publishing** (`host.preview.tailscale_serve`) – whether
+    `tailscale serve` can publish this machine's dev server to the user's own
+    private network. Another device can then open it. Options: yes, no, skip.
+
+    Detection reports whether this machine has Tailscale
+    (`preview.tailscale_binary`). It reports separately whether anyone has
+    logged it in (`preview.tailscale_logged_in`). Put both facts in the option
+    descriptions, because an installed-but-logged-out Tailscale publishes
+    nothing.
+
+2. **Element picker** (`host.element_picker`) – the tool that lets the user
+    click an element in the running app. The user then hands that reference to
+    an agent. Options: `stagewise`, `orca-design-mode`, `none`, skip.
+
+    Say plainly that the config only records this axis. No skill changes its
+    behaviour on it yet, so a wrong answer costs nothing today.
+
+   Note that Orca's Design Mode needs the browser pane to render on the
+   developer's own machine. So it is only a real option when Orca runs there.
+
+3. **Orca topology** (`host.orca.topology`) – how Orca runs. Ask it only when
+    the user answered yes to Orca in Step 2 of `SKILL.md`. Gate it on that answer, not
+    on a config read, because nothing has written `host.orchestrators.orca` yet.
+
+    Local runs Orca as a desktop application on the developer's own machine.
+    Remote runs `orca serve` – Orca's headless server – on another machine, and
+    the user views it through a paired client application. Options: local,
+    remote, skip.

package/skills/host/report.md

@@ -0,0 +1,42 @@
+# Host report
+
+Read this file at Step 6, once you have written every answer and run every follow-up.
+
+Close with a block in this shape – aligned labels, one line per axis, skipped
+axes shown as `(unset – skipped)`:
+
+```
+## Host Declared
+
+Orchestrators: herdr [true|false], orca [true|false]
+Browser:       remote [true|false], headless [true|false], local [true|false]
+Preview:       [true | false | (unset – skipped)]
+Picker:        [stagewise | orca-design-mode | none | (unset – skipped)]
+Orca topology: [local | remote | (unset – skipped) | not applicable]
+Config:        [the path `acstack config path` printed]
+
+Not automated yet: [what still has to be done by hand – logging in to Tailscale,
+connecting the Playwriter bridge, pairing a client to Orca, turning on "Show in
+worktree list" – or "nothing".]
+
+Next: [run /acstack:setup in a project, or `~/.claude/acstack/bin/acstack config
+check` to health-check what was just declared against this machine and against
+the project in the current directory.]
+```
+
+The last item on that list is easy to miss. "Show in worktree list" is a
+per-repository setting in the Orca desktop application.
+
+Turning it on is what puts herdr checkouts on a phone. The user turns it on once
+for each repository.
+
+Get the `Config:` line by running the command, not by writing the usual path in:
+
+```bash
+~/.claude/acstack/bin/acstack config path
+```
+
+`~/.config/acstack/config.json` is only where the file lands by default. Setting
+the `XDG_CONFIG_HOME` environment variable moves it. On a machine that sets that
+variable, a hardcoded path in the report would point at a file that does not
+exist.

package/skills/implement/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: implement
+description: Execute implementation work via the TDD pipeline (test-writer -> task-executor -> task-checker). A map is a stored graph of question and work nodes. Claims afk nodes – away from keyboard, meaning nodes an agent settles alone – from the map frontier, the nodes ready to be worked now, when a map exists; runs the same discipline directly on the request when none does. A unit of work carries its own size – one node is a quick change, forty is a long effort, and nothing declares which. Invoke whenever the way is clear and something needs building, changing or extending, however small. Use quick-fix instead when something is broken and needs a root cause found, and map instead when decisions still need settling before anyone can build.
+argument-hint: "[map name, or the request to implement]"
+---
+
+## User input
+
+```text
+$ARGUMENTS
+```
+
+## What this skill does
+
+Implements work under the TDD pipeline. The unit of work is a map node when a
+map exists, and the request itself when none does – same discipline either
+way. Progress lives on the tracker as claims and resolutions; there is no
+checkbox file to maintain.
+
+## Steps
+
+Before step 1, copy the eight step headings below into your todo list word
+for word. They go ahead of any task-specific items. A step you skip stays in
+the list, marked `skip: <reason>`.
+
+When step 5 runs on a node, copy its eight numbered steps the same way.
+
+### 1. Find the work
+
+Check the configured tracker for maps (`workflow.maps.tracker` in
+`acstack/project.yaml`; the map skill's `trackers/` docs declare the
+operations – files backend shown below).
+
+**A map exists** (or `$ARGUMENTS` names one):
+
+```bash
+~/.claude/acstack/bin/acstack node frontier --map <name> --mode afk --json
+```
+
+On the github backend `--map` refuses – pipe `gh issue list` into `node
+frontier --stdin` instead (see the map skill's `trackers/github.md`).
+
+These are the workable nodes: open, unblocked, and containing no decision.
+Pull them regardless of depth – work can hang anywhere, including straight
+off the root.
+
+If the frontier holds only `hitl` nodes – human in the loop, meaning a
+person must answer them – stop and point the user at `/acstack:map`. Those
+need a human, not a pipeline.
+
+**No map**: the request in `$ARGUMENTS` is the work item. Same discipline,
+no tracker writes. This is the whole quick path – a small change is just a
+small unit of work, and nothing has to declare it small.
+
+### 2. Read project configuration
+
+Read `acstack/project.yaml` for build/test/lint commands and directory paths.
+
+### 3. Create feature branch
+
+Branch from the default branch, named after the map (or a short slug of the
+request). If the branch already exists, ask the user whether to continue on
+it or start fresh.
+
+### 4. Orient, then claim
+
+With a map, orient once per session before claiming:
+
+```bash
+~/.claude/acstack/bin/acstack node walk --map <name>
+```
+
+On the github backend, pipe `gh issue list` into `node walk --stdin` instead
+(see the map skill's `trackers/github.md`).
+
+The walk prints the map in one pass: the root and pinned nodes in full,
+everything else as a one-line gist.
+
+The root holds the destination. Pinned nodes hold standing preferences –
+style rules and constraints that apply to the whole effort.
+
+The resolved chain above a work node – the already-answered questions it
+hangs off, followed up to the root – carries its why. Read that chain before
+touching code.
+
+Also check `node list --map <name> --status claimed`. A claim marks a node
+as work in progress. One left behind by a dead session hides its node from
+the frontier forever.
+
+If a claim exists and you know of no other session working it, ask the
+user and release it (`--status open`).
+
+Claim each node as you start it:
+
+```bash
+~/.claude/acstack/bin/acstack node update <id> --map <name> --status claimed
+```
+
+Nodes describe behaviour, not paths. **Resolve paths at claim time**.
+
+Before any code change, dispatch parallel explorer subagents over the
+relevant code. Use as many as there are distinct places to look, not a fixed
+count. Act on what they find.
+
+### 5. Execute within the claim
+
+The pipeline's state lives inside the claim, not on the node. For each
+claimed node (or the bare request), run the Implementation discipline to
+completion:
+
+1. **test-writer subagent** – tests from the node's behaviour description.
+   Under strict they must all fail before step 2 runs. Skip step 1 for pure
+   config or setup work with no testable behaviour.
+
+2. **task-executor subagent** – make the tests pass. Executor CANNOT modify
+   test files.
+
+3. **Format** – run `commands.format` over the files the work touched. A
+   `null` value means this project has no format step.
+
+    Report a non-zero exit. It never counts as a failed implementation.
+
+4. **task-checker subagent** – verify the build compiles, lints, and
+   typechecks. Verify tests pass, the full suite passes, and test count >=
+   baseline. Also check the mock audit, TDD isolation, and integration
+   wired.
+
+    When `acstack/project.yaml` configures `frontend` and frontend files
+    changed, the checker also runs the frontend build, lint, and unit
+    tests.
+
+5. **`/impeccable audit`** – report design findings on the changed frontend
+   files. Steps 5 to 7 run only when three conditions hold: the design gate
+   is on, `acstack/project.yaml` configures `frontend`, and frontend files
+   changed.
+
+6. **`/impeccable polish`** – fix the same files, from the audit findings.
+
+7. **task-checker subagent, second run** – verify the code polish changed.
+
+    Read `design-pass.md` before steps 5 to 7. It holds who types the
+    commands, how to read the gate, and what polish must leave alone.
+
+8. **frontend-verifier subagent** – verify the UI in a browser. The
+   verifier runs after the second checker passes, only when
+   `acstack/project.yaml` configures `frontend`, frontend files changed,
+   and `workflow.frontend_verification` is true.
+
+`workflow.tdd.strict: false`, relaxed TDD, runs step 2 before step 1 and
+skips nothing. Read `relaxed-tdd.md` when the project sets it. It holds how
+the test-writer and the checker's gate change.
+
+If either checker run fails, route back to the executor with the feedback.
+If the work stalls or the session must stop mid-node, release the claim
+(`--status open`). The node is plainly open again, and you need no phase
+breadcrumb.
+
+**Decision log**: on afk nodes, append one row per decision point to
+`<main checkout>/acstack/.decisions/<name>.tsv`. A decision point is a fork chosen, a
+unit verified, a revert, or a blocker.
+
+Read `decision-log.md` before the first row. It holds how to find the main
+checkout, the columns, and the `.gitignore` the directory needs.
+
+**Parallelism**: afk nodes run unlimited and in parallel. When 2+ frontier
+nodes touch non-overlapping files, launch an agent team where each teammate
+owns one node and its file set. Otherwise, or on a host without agent teams,
+work them sequentially.
+
+### 6. Resolve
+
+When the checker passes, resolve the node in one call:
+
+```bash
+~/.claude/acstack/bin/acstack node update <id> --map <name> --status resolved \
+  --append-body "## Answer
+
+<what was built, which files, what the tests pin down>"
+```
+
+Write the `## Answer` text per the `writing` skill.
+
+With no map, skip the tracker write – still invoke `record-context` when a
+decision landed. With a map, then:
+
+- Invoke `record-context` – implementation decisions can earn ADRs too.
+- Create nodes for anything the work surfaced (a question found mid-build is
+  `hitl`, `--answers <this node>`).
+
+- Recompute the frontier – resolutions unblock nodes.
+
+### 7. Build verification
+
+After each node (and before ending the session), run the commands from
+`acstack/project.yaml`: build, full test suite, lint and typecheck. All must
+pass before claiming the next node.
+
+### 8. Completion
+
+Stop when the afk frontier is empty, or when only `hitl` nodes remain (hand
+those to `/acstack:map`). With no map, stop when the checker passes and Step
+7 verification is green.
+
+Report: nodes resolved, tests passing, lines added/removed. Remind the user:
+`/acstack:commit` to commit – spec sync extracts the durable record from the
+diff.
+
+## Key rules
+
+- **TDD pipeline is mandatory** – test-writer -> task-executor ->
+  task-checker -> frontend-verifier (frontend only). Only pure config work
+  skips the test-writer.
+  `workflow.tdd.strict: false` reorders the first two and skips neither.
+
+    With the design gate on, the audit and polish pass and a second
+    task-checker run sit between the first checker and the verifier
+
+- **Executors CANNOT modify test files** – if tests are wrong, report it.
+- **The tracker is the progress record** – claim on start, resolve on pass,
+  release on stall. No checkbox files, no phase fields.
+
+- **Explore before writing** – parallel explorer subagents over the relevant
+  code, sized to the node, before any edit.
+
+- **Resume is a query** – picking up where you left off means asking the
+  tracker what is workable now, not reconstructing history. A fresh session
+  runs the frontier query and continues. Never re-read an effort end to end
+  to find where it stopped.
+
+- **Do NOT commit or push** – the user manages git via `/acstack:commit`.

package/skills/implement/decision-log.md

@@ -0,0 +1,62 @@
+# The decision log
+
+An afk run has no human watching it. The decision log is how that human later
+sees what the agent chose, and why. Read this file before you write the first
+row.
+
+## When to write a row
+
+Write one row per decision point, never one per action:
+
+- **A fork chosen** – two ways to build something, and you picked one
+- **A unit verified** – a node's checker passed, or a build verification went green
+- **A revert** – you undid work, and the row names what triggered it
+- **A blocker** – something stopped the node, and the row names it
+
+Running a test, reading a file, or dispatching a subagent is an action. It
+gets no row.
+
+## Where the log lives
+
+The log is one file per map, in the main checkout:
+`<main checkout>/acstack/.decisions/<name>.tsv`. The `<name>` is the map name
+you pass to `--map`.
+
+Write it in the main checkout, never in a worktree. Removing a worktree
+deletes its gitignored files, so a log there vanishes before `archive` reads
+it. Find the main checkout from any worktree:
+
+```bash
+main=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")
+```
+
+Nobody commits the log. When you first create the `acstack/.decisions/`
+directory, write `.gitignore` inside it, containing a single line:
+
+```text
+*
+```
+
+## What a row holds
+
+A row is one tab-separated line with six columns, in this order:
+
+| Column | Holds |
+| --- | --- |
+| `ts` | the time, in ISO 8601 |
+| `node` | the node id |
+| `decision` | what you chose, verified, reverted, or hit |
+| `why` | the reason, in one short phrase |
+| `evidence` | a pointer: a commit SHA, a `file:line`, or a path |
+| `result` | what happened next |
+
+- **Evidence is a pointer, never prose**, so a reader can follow it to the proof
+- **Keep tabs and newlines out of every field**, because each one breaks the row
+
+## Append only
+
+Never edit or delete a row. A wrong call gets a new row that supersedes it,
+and its `why` names the row it replaces.
+
+`/acstack:archive` reads the log before it closes the map. It hands lasting
+decisions to `record-context`, then deletes the log file.