space-architect 5.5.0 → 6.0.0

data/lib/space_core/space_store.rb

@@ -53,7 +53,7 @@ module Space::Core
     def list
       return [] unless spaces_dir.directory?
 
-      spaces_dir.children.select(&:directory?).filter_map do |child|
+      Paths.layout_children(spaces_dir).select(&:directory?).filter_map do |child|
         Space.load(child)
       rescue NotFoundError, Error
         nil

data/lib/space_core/version.rb

@@ -2,6 +2,6 @@
 
 module Space
   module Core
-    VERSION = "5.5.0"
+    VERSION = "6.0.0"
   end
 end

data/lib/space_src/cli/sync.rb

@@ -43,6 +43,19 @@ module Space::Src
           # the next spawn. No-op when the log is missing or
           # under-threshold (sync tests in G4 stay green).
           rotate_plist_logs(paths)
+
+          # Resolved BEFORE the scoping block: the "scoping sync to:"
+          # notice below is prose, and must be suppressed in JSON mode
+          # for the same reason the summary line is. Resolution depends
+          # only on flags/env/out, so it is safe this early.
+          mode = UI::Mode.resolve(
+            flags: {plain: plain, json: json, no_color: no_color, quiet: quiet},
+            env: CLI.env,
+            out: out
+          )
+          # Every line of --json output must parse as one JSON object.
+          human = mode.format != :json
+
           if repo
             target = scope_target(repo)
             return fail_with(self, "invalid repo reference: #{repo.inspect} (expected host/owner/name)") if target.failure?
@@ -57,14 +70,9 @@ module Space::Src
             # exactly the G4 "other repo gets no state row" test
             # path, so we explicitly empty orgs here).
             config = Config::Store.with(config, repos: [found], orgs: [])
-            out.puts "scoping sync to: #{Repo::Helpers.format_ref(found)}"
+            out.puts "scoping sync to: #{Repo::Helpers.format_ref(found)}" if human
           end
 
-          mode = UI::Mode.resolve(
-            flags: {plain: plain, json: json, no_color: no_color, quiet: quiet},
-            env: CLI.env,
-            out: out
-          )
           reporter = if mode.format == :json
             UI::JsonReporter.new(out)
           elsif mode.animate
@@ -73,14 +81,19 @@ module Space::Src
             UI::PlainReporter.new(out, mode: mode)
           end
 
-          result = Space::Src::Sync::Engine.new(reporter: reporter).call(config: config, paths: paths)
+          # prune only on a full sweep. With --repo the config above was
+          # narrowed to one repo, so pruning would delete the state rows
+          # for every OTHER tracked repo.
+          result = Space::Src::Sync::Engine.new(reporter: reporter)
+            .call(config: config, paths: paths, prune: repo.nil?)
           if result.failure?
             return fail_with(self, "sync failed: #{format_failure(result.failure)}")
           end
 
-          new_state = result.success
-          n = new_state.repos.size
-          out.puts "synced #{n} repo(s)"
+          report = result.success
+          # JsonReporter already emits a run_finished event carrying the
+          # summary, so suppressing the prose line loses nothing.
+          out.puts "synced #{report.processed} repo(s)" if human
           CLI.record_outcome(Outcome.new(exit_code: 0))
         end
 

data/lib/space_src/cli.rb

@@ -69,6 +69,7 @@ module Space::Src
     def self.bare_query?(argv)
       return false if TOP_LEVEL_HELP.include?(argv)
       return false if VERSION_REQUEST.include?(argv)
+      # paths:exempt - Registry.get([]).children is a dry-cli command-tree node, not a filesystem path
       argv.length == 1 && !Registry.get([]).children.key?(argv[0])
     end
 

data/lib/space_src/cloner.rb

@@ -37,6 +37,7 @@ module Space::Src
       parts = name.split("/")
       case parts.length
       when 1
+        # paths:exempt - layout intent (checkout resolution by depth); space_src is deliberately independent of space_core and must not require it
         candidates = Dir.glob(File.join(@base_dir, "*", "*", name))
         case candidates.length
         when 0 then Failure("#{name.inspect} not found under base_dir #{@base_dir}")
@@ -45,6 +46,7 @@ module Space::Src
         end
       when 2
         owner, repo_name = parts
+        # paths:exempt - layout intent (checkout resolution by depth); space_src is deliberately independent of space_core and must not require it
         candidates = Dir.glob(File.join(@base_dir, "*", owner, repo_name))
         case candidates.length
         when 0 then Failure("#{name.inspect} not found under base_dir #{@base_dir}")

data/lib/space_src/nav.rb

@@ -16,6 +16,7 @@ module Space::Src
     def self.scan(base_dir)
       pattern = File.join(base_dir, "*", "*", "*")
       prefix = base_dir.chomp("/") + "/"
+      # paths:exempt - layout intent (depth-3 checkout scan); space_src is deliberately independent of space_core and must not require it
       Dir.glob(pattern).filter_map do |path|
         next unless File.directory?(path)
         relative = path.delete_prefix(prefix)

data/lib/space_src/sync/engine.rb

@@ -13,6 +13,7 @@ require "space_src/state/store"
 require "space_src/state/lock"
 require "space_src/paths"
 require "space_src/sync/repo_plan"
+require "space_src/sync/report"
 require "space_src/ui/reporter"
 
 module Space::Src
@@ -79,8 +80,18 @@ module Space::Src
       # Runs one sync pass.
       # @param config [Config::Config] the validated config struct
       # @param paths  [Paths]         the XDG paths object
-      # @return [Dry::Monads::Result<State::Store::State>]
-      def call(config:, paths:)
+      # @param prune  [Boolean] drop state rows for repos this run did
+      #   not see. Only the CALLER can know whether `config` is the
+      #   complete tracked set or a scoped subset — the engine cannot
+      #   tell "user tracks one repo" from "user passed --repo" — so
+      #   this is never inferred here. Defaults to false: never delete
+      #   unless explicitly told to. Even when true, pruning is skipped
+      #   if any org listing failed (see below).
+      # @return [Dry::Monads::Result<Report>] the merged state plus the
+      #   count of repos this run processed. The two are distinct: state
+      #   accumulates every repo ever synced, `processed` is this run's
+      #   work (see Sync::Report).
+      def call(config:, paths:, prune: false)
         Sync do |task|
           semaphore = Async::Semaphore.new(config.concurrency, parent: task)
           barrier = Async::Barrier.new
@@ -147,12 +158,24 @@ module Space::Src
               @reporter.run_finished(summary)
 
               # Phase 4: assemble new state, write once.
-              new_state = build_new_state(state, results, org_records)
+              #
+              # A failed org listing means `discovered` is missing that
+              # org's repos through no fault of the user's config, so
+              # pruning would delete every row for a whole org on a
+              # transient forge outage. Only prune when the run saw the
+              # complete picture.
+              listings_complete = org_records.each_value.none?(&:last_error)
+              new_state = build_new_state(
+                state, results, org_records, prune: prune && listings_complete
+              )
               write_result = State::Store.write(paths.state_file, new_state)
               if write_result.failure?
                 write_result
               else
-                Dry::Monads::Success(new_state)
+                # results.size, not new_state.repos.size — the latter is
+                # the accumulated state file and would report every repo
+                # ever synced (553 on a scoped one-repo run).
+                Dry::Monads::Success(Report.new(state: new_state, processed: results.size))
               end
             ensure
               @reporter.detach
@@ -161,7 +184,11 @@ module Space::Src
 
           if lock_result == State::Lock::NOT_ACQUIRED
             warn "src: skipped — another sync in progress"
-            Dry::Monads::Success(State::Store.load(paths.state_file).success)
+            # Nothing ran, so processed is 0 — the state is returned only
+            # so callers still get a usable snapshot.
+            Dry::Monads::Success(
+              Report.new(state: State::Store.load(paths.state_file).success, processed: 0)
+            )
           else
             lock_result
           end
@@ -445,8 +472,20 @@ module Space::Src
       # run's per-repo outcomes + the org records. Failures get a
       # status: error row so every processed repo has a state entry
       # (gate G8).
-      def build_new_state(prev, results, org_records)
-        repos = prev.repos.dup
+      #
+      # With prune: false (the default) rows for repos this run did not
+      # process are carried over untouched — that is what keeps a scoped
+      # `sync --repo` from deleting every other repo's state.
+      #
+      # With prune: true the carry-over is dropped, so the new state
+      # holds exactly the repos this run processed and rows for repos
+      # removed from config stop accumulating. Starting from an empty
+      # hash is equivalent to selecting the processed keys out of prev:
+      # every repo in the sweep contributes exactly one result tuple
+      # (process_one's rescue guarantees one even on an unhandled
+      # raise), so each gets a fresh row in the merge below.
+      def build_new_state(prev, results, org_records, prune: false)
+        repos = prune ? {} : prev.repos.dup
         results.each do |key, repo, error|
           repos[key] = (repo || State::Store::Repo.new(
             default_branch: nil,

data/lib/space_src/sync/report.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Space::Src
+  module Sync
+    # What one sync pass did.
+    #
+    # `state` is the merged whole-state that gets written to disk: it
+    # carries a row for every repo ever synced, because build_new_state
+    # starts from the previous state and merges this run's outcomes into
+    # it. `processed` counts only the repos this run actually touched.
+    #
+    # The two diverge whenever the run is scoped (`sync --repo`) or the
+    # state file already holds rows from earlier runs — which is why
+    # callers wanting "how many repos did this run handle?" must read
+    # `processed` and never `state.repos.size`.
+    Report = Data.define(:state, :processed)
+  end
+end

data/lib/space_src.rb

@@ -25,6 +25,7 @@ require "space_src/scm/git"
 require "space_src/forge/client"
 require "space_src/forge/github"
 require "space_src/sync/repo_plan"
+require "space_src/sync/report"
 require "space_src/sync/engine"
 require "space_src/config/duration"
 require "space_src/log_rotator"

data/skill/architect/SKILL.md

@@ -170,8 +170,20 @@ re-prints them, or `git show <freeze-sha>:architecture/I<NN>-<name>.md`). For ea
 gate: run the gate command yourself — `architect gate <iteration>` runs the
 frozen gate commands in the resolved repo/worktree and streams raw output (it is a
 runner, never a judge), or run them by hand — then compare the output against the
-verbatim frozen text → **PASS / FAIL / INVALID** (INVALID = not measured the way
-the gate specifies). Check `git diff <freeze-sha> HEAD --
+verbatim frozen text → **PASS / FAIL / INVALID**. The line between the failing
+two is the mechanism. **FAIL**: the instrument measured exactly what the gate
+says, and the answer was wrong. **INVALID**: the instrument did not measure what
+the prose AC asserts — a quoting error, a `2>&1` capturing unrelated stderr, a
+command that dies in the runner's shell. INVALID is a legitimate, expected
+outcome, not a loop failure: prove the property directly with evidence gathered
+this session, and carry the corrected gate into the next iteration's freeze
+rather than leaving the defect to recur. It is never a loosening route — a
+threshold the results simply missed is FAIL, however near. A lane that raised a
+**letter-versus-spirit conflict** (per the lane-prompt clause: it built the AC's
+stated property rather than degrade the artifact to fit its letter, and reported
+the conflict with evidence) has done its job — the defect is the criterion's
+authoring (§4), and the lane is not penalized for it; rule on the conflict like
+any disagreement. Check `git diff <freeze-sha> HEAD --
 architecture/I<NN>-<name>.md` — any change to Grounds/Specification/Acceptance
 Criteria lines is an automatic FAIL.
 Gate-pass is necessary, not sufficient: read the diff against the
@@ -267,10 +279,21 @@ contract, self-contained:
   declaration lives in a fenced ` ```lanes ` block in the Specification — one
   entry per lane (`name`, `repo`, `touch` globs) — the single frozen source of
   truth `architect freeze` records into `space.yaml` and `architect provision`
-  materializes. The touch-set now lives *with* the frozen spec by design: it
-  closes the drift where a `worktree add --touch` flag could diverge from the
-  spec's intent. The scaffold ships a commented ` ```lanes ` stub in the
-  Specification (see `templates/iteration.md.erb`) — uncomment it. Lanes in
+  materializes. The same boundary is stated twice more — the lane-prompt's
+  may-touch list, and the scope gate that checks the lane's diff at judge
+  time — and all three must be one exhaustive enumeration: every file listed,
+  no glob standing in for the list; the scope gate's pattern is that
+  enumeration exactly; the prompt's list is generated from it. Consistency is
+  not completeness — three statements drawn from one too-narrow search agree
+  and are wrong together — so before freezing a criterion that requires an
+  identifier to change name, grep the whole repo for it and confirm every hit
+  falls inside some lane's touch set; `architect rehearse` reports this
+  asymmetry, so the check is read, not remembered. Either defect surfaces
+  only after the freeze, where hard rule 3 forbids widening the declaration:
+  `integrate` refuses a correct lane, or the stray hit breaks a file no lane
+  may legally fix. The scaffold ships a
+  commented ` ```lanes ` stub in the Specification (see
+  `templates/iteration.md.erb`) — uncomment it. Lanes in
   *different* repos are inherently disjoint; same-repo lanes with any file
   overlap run as one. Each lane gets its own objective, output format, and
   boundaries. Most
@@ -281,10 +304,11 @@ contract, self-contained:
   **serial deferred judgment** (iterations run to gates-green with `architect
   verdict` withheld; one later batch session judges each against its own frozen
   AC — see `### Serial deferred judgment`).
-- **Effort call** — thinking budget set in the lane-prompt via the escalation
-  keywords (`think hard` … `ultrathink`); default unattended builder work high,
-  downgrade a routine, tightly-specified lane (record which and why). Claude
-  Code has no per-invocation effort flag — see `dispatch.md`.
+- **Effort call** — thinking budget set per dispatch with `architect dispatch
+  --effort <level>`, translated and clamped to the lane's harness (the
+  escalation keywords `think hard` … `ultrathink` still work in-prompt);
+  default unattended builder work high, downgrade a routine, tightly-specified
+  lane (record which and why). Levels and mechanics: `dispatch.md`.
 
 **Spike (probe) iterations.** When the open question is too uncertain for a
 build — the repo can't answer it and routine API-verification won't resolve it
@@ -307,7 +331,61 @@ through the normal builder/lane machinery.
 Then write the **Acceptance Criteria** section — prose conditions (AC1, AC2, …)
 that the architect judges against, followed by a fenced ` ```gates ` block of
 runnable checks (each gate carries `id`, `ac`, `cmd`, and `expect`; `cwd` is
-optional) — and run `architect freeze <name>`. What must be frozen before
+optional). Calibrate each criterion's precision to the property it asserts —
+R4 ("grade the outcome, not the path") applied at authoring time, the only time
+it can be applied, because a frozen criterion is never loosened after results.
+Two kinds of criterion, two calibrations:
+
+- A criterion asserting a **property that must hold** is bounded from one side
+  only — the side the defect is on — freezing a floor, not an equality, so an
+  addition or change the lane discovers stays legal. "Exactly eight runtime
+  dependencies" freezes today's snapshot and outlaws the ninth a transitive
+  need later forces; the property it stood in for was "declares everything it
+  requires."
+- A criterion whose **number is itself the deliverable** may be exact — there
+  the precision is the point (a touch-set boundary, a wire-format constant).
+
+Writing the first kind as the second is the defect: it leaves the lane no
+sanctioned path except degrading the artifact to fit the number.
+
+Say, too, what each gate proves: a presence-grep gate on prose is a
+**tripwire**, never the proof — it shows a keyword landed, not that the thing
+works — and its criterion should say which it is, leaving the substance
+architect-read.
+
+**Pre-freeze check** — run against the drafted AC in the minutes before
+`architect freeze`, while a bad criterion still costs nothing:
+
+- **snapshot** — no AC or gate hard-codes a count, name-set, or byte-identity
+  that is merely what was known at freeze time;
+- **control** — every baseline or regression claim had its control actually run
+  in this session, not recalled or assumed;
+- **mechanism** — no AC names a *how* (an API signature, a helper, a file
+  layout) where the *what* is the requirement, such that a better shape the
+  lane discovers would be forbidden;
+- **interface** — any CLI surface a Specification names — a verb, a flag
+  spelling, a subcommand — is executed once before it is frozen: a frozen
+  interface is only safe if it is implementable, which is the assumption
+  every code/prose lane split rests on. No verb backs this item yet — unlike
+  dry-run, it is a discipline run by hand;
+- **dry-run** — `architect rehearse <name>`: it runs the drafted gates from
+  the working tree through the same execution path `architect gate` uses
+  (`/bin/sh`, same run-dir resolution, same evaluator) and classifies each —
+  **RED**, a clean non-zero: the gate discriminates, the healthy pre-freeze
+  result; **GREEN**, passes on base: a declared regression guard, or a gate
+  that measures nothing; **BROKEN**, a 127 / syntax error / timeout —
+  advisory, because a correct RED can look broken (`grep -q x` on a file the
+  lane will write exits 2): the tool names the suspicion, you confirm;
+  **EMPTY**, no gates or an untouched placeholder. `--record` emits a
+  paste-able provenance block for the AC preamble. It reports; which GREENs
+  are guards and which are defects stays your call.
+
+Then run `architect freeze <name>`. Freeze requires a fresh rehearsal stamp —
+`rehearse` records one in `space.yaml`, keyed to the gates block's content, so
+editing a gate afterward stales it; `architect freeze --skip-rehearse REASON`
+(non-empty, recorded) is the escape valve. The stamp records that you looked,
+never that gates passed — an all-RED and an all-GREEN run stamp identically.
+What must be frozen before
 dispatch is the Acceptance Criteria: `architect freeze` lints the gates block
 (absent or empty gates is allowed but warns; malformed fails), commits any
 pending content in the frozen region (Grounds/Specification/Acceptance Criteria)
@@ -319,12 +397,16 @@ once a frozen section changed afterward.
 
 ### 5. Dispatch (one fresh `claude -p` per lane, worktree-isolated)
 
-Per the mechanics in `dispatch.md`. The lane lifecycle is **declare → freeze →
-provision → write prompts → dispatch** — every lane gets a worktree; there is no
-dispatch-in-the-checkout path:
+Per the mechanics in `dispatch.md`. The lane lifecycle is **declare → rehearse
+→ freeze → provision → write prompts → dispatch** — every lane gets a worktree;
+there is no dispatch-in-the-checkout path:
 
 - **Declare** — at spec time, each lane is one entry in the Specification's
   fenced ` ```lanes ` block (§4): `name`, `repo`, `touch` globs.
+- **Rehearse** — `architect rehearse <iteration>` dry-runs the drafted gates
+  from the working tree (§4's pre-freeze check), resolving its run dir from the
+  drafted ` ```lanes ` block, and stamps `space.yaml`; `freeze` refuses without
+  a fresh stamp.
 - **Freeze** — `architect freeze` parses that block and records each lane
   (name, repo, touch_set) into `space.yaml`.
 - **Provision** — `architect provision <iteration>` materializes every declared

data/skill/architect/dispatch.md

@@ -223,7 +223,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
@@ -273,13 +273,15 @@ 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).
 - **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 +342,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 +370,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 +393,20 @@ 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
 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.0
+  version: 6.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