acstack 0.48.5 → 0.49.1

package/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acstack-cli",
-  "version": "0.48.5",
+  "version": "0.49.1",
   "description": "CLI for the ACStack agentic coding stack",
   "type": "module",
   "license": "MIT",

package/package.json

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

package/skills/archive/SKILL.md

@@ -131,6 +131,9 @@ dispose – closed issues are already the archive.
 Also dispose of `acstack/handoffs/<name>/` if it exists. Consumed handoffs
 hold conversation content and should not outlive the map they served.
 
+Also dispose of `acstack/alignment-packs/<safe-map>/` if it exists. Alignment
+packs are local review artifacts. Step 3 already verified the durable residue.
+
 Delete the map's decision log, `<main checkout>/acstack/.decisions/<name>.tsv`,
 on either tracker. Step 3 already extracted what it held. Leave the directory
 and its `.gitignore` for the next map.

package/skills/grilling/SKILL.md

@@ -109,7 +109,8 @@ the tracker's `update` and `create` operations:
 
 2. Create a node for each new question the answer surfaced, with `answers`
    naming the node that surfaced it. Mark precise questions `open`; mark the
-   rest `fog`.
+   rest `fog`. If fog does not change the alignment artifact, write the
+   evidence or event that reopens it.
 
 3. Invoke the `record-context` skill for each resolution – it decides whether
    the decision earns an ADR, a glossary term, both, or neither.

package/skills/handoff/SKILL.md

@@ -146,8 +146,12 @@ conversation content, not project state, and must not be committable. Name it
 nothing), where `<slug>` names the work and `<timestamp>` stops two handoffs
 colliding.
 
-Its first line, above every heading, repeats the acknowledgement requirement
-verbatim, with `<this-file>` replaced by the file's own path:
+Use a file-writing tool when your harness has one. Otherwise use a quoted
+heredoc, `<<'EOF'`, so the shell does not expand the handoff text. An unquoted
+heredoc can run backticked commands inside the note.
+
+Its first line repeats the acknowledgement requirement verbatim, with
+`<this-file>` replaced by the file's own path:
 
 ```text
 Acknowledge before any other tool call. Run ~/.claude/acstack/bin/acstack handoff ack accept --file <this-file> "<one-line reason>", or ack decline --file <this-file> "<one-line reason>". The command writes <this-file>.ack, which the sender watches.
@@ -167,22 +171,19 @@ The launch prompt is a **single-line pointer at that file**, never the handoff
 text itself. `herdr agent start` rejects newlines and tabs in its arguments.
 
 ## Every prompt opens with an acknowledgement
-
 Every handoff prompt asks for the command.
 
 There are two prompts, because the two destinations must say different things.
 Use the matching one verbatim, and substitute only the handoff file path.
 
 Each one is a single line. `herdr agent start` rejects newlines and tabs in its
-arguments. So the instruction and the pointer at the handoff file share that one
-line.
+arguments, so the instruction and file pointer share that line.
 
-**Fresh agent** – one launched for this handoff, into a new pane, worktree or
-tab, or as a `--bg` session. Reading the handoff file is the one tool call
-allowed before the ack command. Every other tool call – a command, an edit, a
-subagent – leaves the acknowledgement still owed.
+**Fresh agent** – one launched for this handoff, into a new pane, worktree,
+tab, or `--bg` session. It may read the handoff file before the ack command.
+Every other tool call leaves the acknowledgement still owed.
 
-> Before any other tool call, acknowledge this handoff by running ~/.claude/acstack/bin/acstack handoff ack accept --file <handoff-file> "<one-line reason>", or ack decline --file <handoff-file> "<one-line reason>". You may read <handoff-file> first to judge whether the work suits you, and nothing else until the command has run – the sender watches for the file it writes and cannot report this work as yours until it exists. Then continue that work.
+> Before any other tool call, run ~/.claude/acstack/bin/acstack handoff ack accept --file <handoff-file> "<one-line reason>", or ack decline --file <handoff-file> "<one-line reason>". You may read <handoff-file> first. Then continue that work.
 
 **Agent already running** – one reached by cross-session message. Its variant
 of the opener is in [`running-agent.md`](running-agent.md).
@@ -208,12 +209,11 @@ Do not eyeball transcripts. The CLI watches for you:
   --session-id <id> --cwd <dir> --token <token> --turns <n>
 ```
 
-**Run the watcher in the background.** This session has stopped working on the
-task, but it must not lock up. The user can keep talking to it while the handoff
-lands, and the harness surfaces the watcher's exit on its own. Never sit in a
+**Run the watcher in the background.** The user can keep talking while the
+handoff lands. The harness surfaces the watcher's exit. Never sit in a
 foreground wait.
 
-[`watch.md`](watch.md) gives every flag, `--fresh` among them. When the watcher
+[`watch.md`](watch.md) gives every flag, including `--fresh`. When the watcher
 exits, read [`outcomes.md`](outcomes.md) for what its result means.
 
 ## Silence the context-pressure nudge

package/skills/handoff/launch-herdr.md

@@ -170,15 +170,26 @@ blocked state instead of polling by hand:
 herdr agent wait <name> --until blocked --timeout <ms>
 ```
 
-On `blocked`, accept the dialog with `herdr agent send-keys <name> enter`. Then
-re-check by waiting for the session to start working:
+At the trust dialog, `agent_not_ready` means the session has not reached the
+prompt yet. Wait again or read `herdr agent get <name>` before sending keys.
+A `blocked` result means the trust dialog is ready.
+
+On `blocked`, accept the dialog with:
+
+```bash
+herdr agent send-keys <name> down
+herdr agent send-keys <name> enter
+```
+
+Then re-check by waiting for the session to start working:
 
 ```bash
 herdr agent wait <name> --until working --timeout <ms>
 ```
 
-If either wait times out, read the agent's current state directly with
-`herdr agent get <name>` rather than guessing.
+If either wait times out, or the agent reports `blocked` after the keys, read the
+agent's current state directly with `herdr agent get <name>` rather than
+guessing.
 
 Throughout this section `<name>` is the pane ID instead, whenever the launch
 timed out – see *When `agent start` times out*, above.

package/skills/implement/SKILL.md

@@ -44,6 +44,15 @@ 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.
 
+Before claiming one, check whether the map is ready to build from:
+
+- If any `fog` node changes the alignment artifact, stop and point the user at
+  `/acstack:map`.
+- If `workflow.alignment_packs.approval_gate` is true and no reviewer approved
+  the alignment artifact, stop and point the user at `/acstack:map`.
+- If a `fog` node needs later evidence and does not change the artifact, leave
+  it on the map with its reopening trigger.
+
 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.
@@ -104,6 +113,11 @@ over the relevant code. Use `Explore` on Claude Code and `scout` on pi.
 Use as many as there are distinct places to look, not a fixed count. Act on
 what they find.
 
+Downstream pipeline subagents start fresh. Pass the source, test, and doc paths
+you already discovered into each test-writer, task-executor, task-checker, audit,
+polish, and verifier prompt. Tell them to read those paths directly instead of
+searching the codebase again.
+
 ### 5. Execute within the claim
 
 The pipeline's state lives inside the claim, not on the node. For each
@@ -186,9 +200,11 @@ 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>`).
-
+- Classify anything the work surfaced:
+    - Agent-clearable fog gets research, tests, or a throwaway prototype.
+    - Design-changing fog becomes a `hitl` node and returns to `/acstack:map`.
+    - Local fog that does not change the artifact stays inside the claim notes.
+- Rebuild or rerun the alignment review when the work changes the artifact.
 - Recompute the frontier – resolutions unblock nodes.
 
 ### 7. Build verification

package/skills/map/SKILL.md

@@ -20,12 +20,8 @@ Nodes live behind a pluggable tracker. A backend declares four operations –
 create, read, update, list. ACStack builds everything else from those four:
 frontier, claim, resolve and walk.
 
-Two backends ship, each declared in this skill's directory:
-
-| Backend | Doc | When |
-| ------- | --- | ---- |
-| GitHub issues | `trackers/github.md` | first choice when `gh` holds a login for the repo's GitHub remote |
-| Files | `trackers/files.md` | the fallback – no auth, offline, any remote |
+Two backends ship in this skill's directory: `trackers/github.md` for repos
+with GitHub auth, and `trackers/files.md` as the fallback.
 
 `workflow.maps.tracker` in `acstack/project.yaml` (`github` or `files`) records
 the project's choice. If the key names a backend, read the matching doc and use
@@ -34,7 +30,6 @@ you first write the map's nodes down.
 
 Recommend `github` when the repo qualifies, `files` otherwise. Confirm the
 choice with the user. Then write the key, so later sessions need not re-decide.
-
 ## Which mode
 
 One command runs two modes, and what already exists picks between them. Check
@@ -45,10 +40,8 @@ If `$ARGUMENTS` names a map, or exactly one exists, work its frontier – the
 nodes ready to work now. If none exists, chart. If several exist and
 `$ARGUMENTS` does not pick one, ask.
 
-There are no tiers and no complexity judgement.
-
-One question is a small map or no map at all. Fifty questions is a long
-effort. Nothing declares which.
+There are no tiers. One question is a small map or no map. Fifty questions is
+still one map.
 
 ## Charting
 
@@ -71,18 +64,18 @@ effort. Nothing declares which.
    sharp. The test is whether you can *state* the question precisely, not
    whether you can answer it.
 
-### Progressive materialisation
+5. **Classify fog.** Read `alignment.md`. Blocking fog changes the alignment
+   artifact. Deferred fog does not.
 
-The machinery appears only when it has to persist. After the opening grill:
-
-- **No fog surfaced** – the way was already clear. No map. Say so and proceed
-  to the work.
+### Progressive materialisation
 
-- **At most one session's worth** – settle it in conversation. Invoke
-  `record-context` on each decision. No map – there is nothing to resume.
+The machinery appears only when it must persist. After the opening grill:
 
-- **More than one session's worth** – materialise the map and work the
-  frontier across sessions.
+- **No fog surfaced** – say so and proceed to the work
+- **At most one session's worth** – settle it in conversation and invoke
+  `record-context` on each decision
+- **More than one session's worth** – materialise the map and work the frontier
+  across sessions
 
 The test is mechanical. Will the fog outlive this session?
 
@@ -148,6 +141,8 @@ operation. First the root:
   diagrams below. A parent draws its subtree, so nothing can draw one earlier.
   The root is a parent too, and it draws the whole map.
 
+- Apply `alignment.md` after diagrams are current. Build the artifact, run the
+  review gate, and start implementation only after approval.
 - On the files backend, suggest adding `acstack/maps/` to `.gitignore`
   (`trackers/files.md` gives the reason).
 
@@ -208,10 +203,12 @@ the list, marked `skip: <reason>`.
 5. **After every resolution**, in order:
     - Invoke `record-context`
     - Create nodes for anything the resolution surfaced
+    - Classify new fog by whether it changes the alignment artifact
     - Create the critique node when the resolved node changed the frontend,
       per `frontend.md`
     - Regenerate the diagram on the resolved node's parent (see Regenerating
       diagrams)
+    - Rebuild or rerun the alignment review when the artifact changes
     - Recompute the frontier
 
     The regeneration comes after the new nodes exist. A surfaced node hangs
@@ -238,10 +235,13 @@ diagram).
 
 ## Done
 
-The map clears when the frontier is empty and no fog remains. The durable
-residue is what the map leaves behind – the living specs through commit-time
-sync, the ADRs and glossary entries through `record-context`. You have already
-extracted it along the way.
+The map clears when the frontier is empty and no fog remains. Deferred fog can
+let implementation start, but archive still needs an answer or an out-of-scope
+resolution.
+
+The durable residue is what the map leaves behind – the living specs through
+commit-time sync, the ADRs and glossary entries through `record-context`. You
+have already extracted it along the way.
 
 Report what the map settled. Point at anything the map left `out-of-scope`.
 

package/skills/map/alignment.md

@@ -0,0 +1,38 @@
+# Alignment review
+
+The alignment artifact is the human-readable end-state view that the CLI renders from the map.
+
+## Fog classes
+
+- Blocking fog changes the artifact
+- Deferred fog needs later evidence, or sits below the level the artifact must settle
+- Clear blocking fog before implementation starts
+- Leave deferred fog on the map with the evidence or event that reopens it
+- Never defer fog because asking feels inconvenient
+
+## Review gate
+
+Build the artifact after diagrams are current:
+
+```bash
+~/.claude/acstack/bin/acstack map --map <name>
+```
+
+The artifact is disposable. The map remains the source of truth.
+
+Run the review before implementation when `workflow.alignment_packs.approval_gate` is true:
+
+```bash
+~/.claude/acstack/bin/acstack align-viewer --map <name>
+```
+
+If the review requests changes, read the feedback file the command prints.
+Update the map, regenerate the diagrams, and rerun the review.
+
+Start implementation only after the reviewer approves the artifact, or after the project disables the approval gate.
+
+## New fog during implementation
+
+- If new fog changes the artifact, return to `/acstack:map`
+- If new fog does not change the artifact, keep working with a local note
+- Rebuild or rerun the review when implementation changes the artifact