space-architect 5.5.1 → 7.0.0

data/skill/architect/dispatch.md

@@ -145,7 +145,12 @@ spec defect: kill the conflicting lane and re-spec; don't hand-resolve builder
 conflicts. It runs **no gates and makes no verdict** — `architect gate` streams
 the raw gate output for you to judge. `--teardown` deletes only the per-lane
 `lane/<iteration>-<lane>` branches and worktrees; it never deletes the
-`project/<slug>` branch.
+`project/<slug>` branch. Every destructive lane operation — `worktree remove`,
+`integrate --teardown`, and the re-point path of `provision --base` — refuses
+per lane when that lane's worktree still holds uncommitted work, untracked
+files included, because that's what a dispatched lane always holds; `--force`
+overrides and discards it. The `--lanes <passing-set>` integration path itself
+is unaffected — `integrate` commits each lane's work before tearing it down.
 
 Under the hood / manual fallback (one lane shown):
 
@@ -223,7 +228,7 @@ AC judgment into one later session.
 
 **Recipe:**
 
-Per iteration, freeze and dispatch as normal. In a fresh judging session, run
+Per iteration, rehearse, freeze, and dispatch as normal. In a fresh judging session, run
 post-flight, integrate, and gate — but **withhold `architect verdict`**:
 
 ```bash
@@ -261,6 +266,66 @@ rests on a foundation that a later KILL at N would revert. Accept this coupling
 only consciously, and always judge oldest-first so a KILL stops you before you
 compound it.
 
+### Long-running sweep (detached, two-phase)
+
+Use when a lane's own work *is* a long-running detached process — a 30–70
+minute sweep, migration, or batch run the lane must launch, let run
+unattended, and then audit once it exits. A metered builder session paying
+tokens to sit in a poll loop is the wrong instrument for that wait: split the
+lane across two builder sessions instead, one before the process runs and one
+after.
+
+**Recipe:**
+
+1. **Phase A — launch, prove liveness, stop deliberately.** The lane-prompt's
+   PHASE 2 tells the builder to launch the process detached (backgrounded and
+   redirected to a log file, survives the builder's own process exit), capture
+   its pid, prove it's alive with one command result (e.g. `ps -p <pid>` plus a
+   growing log tail — not an assertion), pre-structure the report with the
+   sections phase B will fill in, and end the session there — not mid-poll —
+   at:
+   ```
+   STATUS: SWEEP_RUNNING (pid <pid>, run dir <path>)
+   ```
+   `SWEEP_RUNNING` is the fixed token spec authors and architects grep for;
+   the pid and run dir ride in the same line because nothing else in the loop
+   captures them.
+
+2. **The wait belongs to the architect's harness, not the builder session.**
+   Between phase A and B, a process-exit monitor on the architect's side —
+   notification-driven, not a poll loop — watches for the pid to exit. A
+   builder session spends tokens to sit idle in a wait; the harness doesn't.
+   Do not dispatch a phase-B session, or resume one, until the process has
+   actually exited.
+
+3. **Phase B — resume and audit.** Once the process has exited, resume the
+   same lane worktree with `--continue` — the one sanctioned use of
+   `--continue` beyond same-lane follow-ups (see `## Operating guidance`
+   below) — and hand it the post-run audit as the new instruction:
+   ```bash
+   ( cd build/<id>-<lane>/wt && \
+     echo "The sweep at <run dir> (pid <pid>) has exited. Audit its output
+   against the spec's acceptance criteria, finish the report you
+   pre-structured in phase A, and end at STATUS: COMPLETE." \
+     | claude -p --continue --model <builder-model> \
+       --permission-mode acceptEdits \
+       --allowedTools 'Read,Edit,Write,Grep,Glob,Bash,WebSearch,WebFetch' \
+       --disallowedTools 'Bash(git commit:*),Bash(git push:*),Bash(git reset:*),Bash(git merge:*),Bash(git rebase:*),Bash(git checkout:*),Bash(git branch:*)' \
+       --output-format stream-json --verbose \
+       > build/<id>-<lane>/run-b.jsonl 2>&1 )
+   ```
+   Phase B runs the post-run audits the spec asked for, then finishes the
+   report at `STATUS: COMPLETE` (or `COMPLETE_WITH_CONCERNS`/`BLOCKED`, per the
+   template) exactly as any other lane would.
+
+**Invariant:** phase A never ends mid-poll or at a pending status of its own
+invention — it ends at `SWEEP_RUNNING` with the pid and run dir recorded, or
+it's indistinguishable from a lane that gave up. Spec authors: an in-lane
+"poll until it finishes" / "never end the session while it runs" instruction
+loses to the template's no-busy-wait clause below every time a builder holds
+both — write this two-phase shape into the lane spec instead of a poll
+instruction.
+
 ## Operating guidance
 
 - Background each lane as its own harness task and let the **per-lane
@@ -273,13 +338,28 @@ compound it.
   <builder-model>`). A floating alias (a bare "latest"/tier tag) drifts to
   whatever ships next — fine interactively, but automations pin the full id so a
   model bump can't silently change builder behavior mid-project.
-- Effort = thinking budget. Claude Code has no per-invocation effort flag the
-  way Codex exposed `model_reasoning_effort`; the builder sets thinking depth
-  **in the block** via the escalation keywords (`think` < `think hard` <
-  `think harder` < `ultrathink`), or you floor it with the `MAX_THINKING_TOKENS`
-  env var on the dispatch. Default unattended builder work to a high budget
-  (open the block with "Think harder…"); downgrade a routine,
-  tightly-specified lane to "think hard" (record which and why in the spec).
+- Effort = thinking budget. Set it per dispatch: `architect dispatch --effort
+  <level>` (aliases `--thinking`/`--reasoning`) accepts
+  `off`/`minimal`/`low`/`medium`/`high`/`xhigh`/`max` and translates it to the
+  lane's harness — `claude-code` passes `low`…`max` straight through to its own
+  `--effort` flag, unclamped (`minimal` clamps to `low`; `off` omits the flag).
+  The escalation keywords (`think` < `think hard` < `think harder` <
+  `ultrathink`) and the `MAX_THINKING_TOKENS` env var still raise depth from
+  inside the block. Default unattended builder work to a high budget; downgrade
+  a routine, tightly-specified lane (record which and why in the spec).
+- **Tool grant.** The default `--allowedTools` list is overridable per dispatch:
+  `--allowed-tools <list>` replaces it, `--append-allowed-tools <list>` appends
+  to it. The same is settable in the frozen lane declaration's ` ```lanes ` block
+  — `allowed_tools:` (replaces) / `append_allowed_tools:` (appends) — so a lane
+  that needs an MCP or other non-default tool is granted it reviewably, judged
+  like every other lane boundary, rather than buried in a shell invocation. The
+  CLI flag wins over the lane's yaml key when both are given, and dispatch
+  reports which source resolved. This exists because `claude -p` **denies** a
+  tool not on the allow list rather than prompting for it — a lane missing a
+  needed grant doesn't error, it silently can't use the tool and files a
+  confident, dataless report instead. `--disallowedTools`/`DISALLOWED_TOOLS`
+  (the builder-never-commits deny rules above) has no override route, by design
+  — hard rule 7 depends on it staying fixed.
 - **Builders never commit, and the architect verifies it.** Claude Code has no
   sandbox to make `.git` read-only, so this is enforced by the deny rules at
   dispatch *and* checked after the run: before integrating a lane, confirm
@@ -340,7 +420,10 @@ builders toward the repo's existing test fixtures over hand-rolled long-running
 harnesses, and when a gate needs a runtime that can't run unattended
 (interactive prompts, servers without a timeout), have the builder record the
 exact failure as a disagreement/blocker and verify what it can — gate verdicts
-are architect-run anyway (hard rule 4). Write the gate file anticipating this.
+are architect-run anyway (hard rule 4). Write the gate file anticipating this —
+`architect rehearse` runs the drafted gates pre-freeze, so an unattended-hostile
+gate surfaces as **BROKEN** while still editable (advisory: a correct RED can
+look broken).
 
 ## Manual alternative (human-driven)
 
@@ -365,7 +448,11 @@ PHASE 1 — Treat the shared contracts (schemas/interfaces) named in the spec,
 and the repo's existing public interfaces, as FROZEN: do not change them —
 other lanes depend on them. You have no access to the space's architecture/
 directory; the architect owns it. The ACCEPTANCE CRITERIA below are frozen —
-verify your work against them; never weaken or work around them.
+verify your work against them; never weaken or work around them. If an AC's
+letter can only be satisfied by making the artifact worse than the property the
+AC asserts, build the right thing and raise the conflict in your report — name
+the AC, the conflict, and the evidence. This is not permission to skip work or
+weaken a criterion: the conflict is reported, never silently resolved.
 
 PHASE 2 — Build YOUR LANE ONLY: exactly the files listed in BOUNDARIES. You
 are one of several parallel lane agents working in isolated worktrees; files
@@ -384,14 +471,24 @@ running the acceptance criteria's gate commands and record the verbatim output.
 git write command (commit/add/branch/reset/checkout) — the architect commits
 and merges after verification, and verifies you made no commits. Do NOT delete
 lock files or escalate privileges if a command fails; record the exact error
-and continue. Give every potentially long command an explicit timeout; if a
+and continue. Do NOT use `run_in_background` (or shell `&`) for your own work —
+this process terminates when you end your turn and reaps its own children, so
+backgrounded work is SIGTERMed and its output lost while the run still exits
+0; run long commands serially in the foreground instead. Give every
+potentially long command an explicit timeout; if a
 runtime will not start unattended (interactive prompt, server with no timeout),
 record the exact failure in your report and route around it — never busy-wait
-or retry in a loop. When done, write your report to the scratch file given to
+or retry in a loop. The one sanctioned exception is a deliberate wait on a
+detached process this lane itself launched: end that phase at
+`STATUS: SWEEP_RUNNING` (pid + run dir) per `### Long-running sweep` in
+dispatch.md, instead of polling for it to finish — this clause still forbids
+retry loops and sitting on an unattended runtime with no timeout. When done, write your report to the scratch file given to
 you, build/<id>-<lane>/report.md (an absolute path outside your worktree),
 with RAW results only — tables, numbers, command output — no interpretation, no
 "promising". Every status claim must be backed by a command result from this
-run. Keep the report compact — tables and numbers, not prose. End it with
+run. Keep the report compact — tables and numbers, not prose. Do not title the
+report — the architect's tooling supplies the `### <lane>` heading when it
+transcribes; keep any headings inside the report at `###` or deeper. End it with
 exactly one status line: STATUS: COMPLETE | COMPLETE_WITH_CONCERNS (list them)
 | BLOCKED (exact blocker + what you tried). Verdicts belong to the architect
 and the human. Persist until your lane is fully handled end-to-end; do not stop

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: space-architect
 version: !ruby/object:Gem::Version
-  version: 5.5.1
+  version: 7.0.0
 platform: ruby
 authors:
 - Eric Jacobs
@@ -361,6 +361,7 @@ files:
 - lib/space_src/state/store.rb
 - lib/space_src/sync/engine.rb
 - lib/space_src/sync/repo_plan.rb
+- lib/space_src/sync/report.rb
 - lib/space_src/ui/interactive_reporter.rb
 - lib/space_src/ui/json_reporter.rb
 - lib/space_src/ui/mode.rb