acstack 0.48.3 → 0.49.0

package/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acstack-cli",
-  "version": "0.48.3",
+  "version": "0.49.0",
   "description": "CLI for the ACStack agentic coding stack",
   "type": "module",
   "license": "MIT",
@@ -9,7 +9,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/ac8318740/spechub.git",
+    "url": "git+https://github.com/ac8318740/acstack.git",
     "directory": "cli"
   },
   "bin": {
@@ -55,7 +55,7 @@
     "yaml": "^2.7.0",
     "zod": "^3.24.0"
   },
-  "homepage": "https://github.com/ac8318740/spechub/tree/main/cli",
+  "homepage": "https://github.com/ac8318740/acstack/tree/main/cli",
   "keywords": [
     "agentic-coding",
     "acstack",

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "acstack",
-  "version": "0.48.3",
+  "version": "0.49.0",
   "private": false,
   "description": "Agentic coding stack with first-class Claude Code and pi support: skills, orchestrator instructions, and verification agents.",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/ac8318740/spechub.git"
+    "url": "git+https://github.com/ac8318740/acstack.git"
   },
   "keywords": [
     "pi-package",

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/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.
@@ -186,9 +195,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