space-architect 5.5.1 → 7.0.0

data/lib/space_architect/skill_installer.rb

@@ -46,7 +46,7 @@ module Space
         end
 
         def source_skills
-          source_root.children.select(&:directory?)
+          Space::Core::Paths.layout_children(source_root).select(&:directory?)
         end
 
         private
@@ -93,8 +93,8 @@ module Space
         def same_content?(source, dest)
           return false unless dest.directory?
 
-          source_files = Dir.glob("#{source}/**/*").reject { |f| File.directory?(f) }
-          dest_files = Dir.glob("#{dest}/**/*").reject { |f| File.directory?(f) }
+          source_files = Space::Core::Paths.content_tree(source).reject { |f| File.directory?(f) }
+          dest_files = Space::Core::Paths.content_tree(dest).reject { |f| File.directory?(f) }
 
           return false if source_files.length != dest_files.length
 

data/lib/space_architect/templates/iteration.md.erb

@@ -31,7 +31,9 @@ Write + commit: `architect section <%= @_name %> specification --from <file>`. -
   machine-readable declaration lives in the fenced ```lanes block below — the single
   frozen source of truth `architect freeze` records and `architect provision`
   materializes.
-- **Effort** — `think hard` … `ultrathink` per lane, with one line of why.
+- **Effort** — per lane, set at dispatch: `architect dispatch --effort <level>`,
+  translated + clamped to the lane's harness, with one line of why (the
+  escalation keywords `think hard` … `ultrathink` still work in-prompt).
 
 ```lanes
 # One entry per lane (1–4). The frozen out-of-bounds contract: `architect freeze`
@@ -39,17 +41,33 @@ Write + commit: `architect section <%= @_name %> specification --from <file>`. -
 # materializes the worktrees + lane branches. Remove the comment markers to activate.
 # - name: lane-a            # lane name (required)
 #   repo: my-repo           # target repo under repos/ (required)
-#   touch:                  # file globs this lane may write (required, non-empty)
-#     - lib/my_repo/**
+#   touch:                  # every file this lane may write, enumerated — no globs (required, non-empty)
+#     - lib/my_repo/foo.rb
+#     - lib/my_repo/bar.rb
 #     - test/my_repo_test.rb
 ```
 
 ## Acceptance Criteria
 
 <!-- PROOF. Write the prose conditions of correctness (AC1, AC2, …) that the
-architect judges against. Runnable checks live in the fenced ```gates block below
+architect judges against. Calibrate precision to the property (SKILL.md §4): a
+property criterion is bounded from the defect's side only — freeze a floor, not
+an equality; exactness is for criteria whose number is itself the deliverable.
+A presence-grep gate on prose is a tripwire, never the proof — its criterion
+should say which. Runnable checks live in the fenced ```gates block below
 (parsed at freeze time — absent or empty is allowed; malformed fails freeze).
-`architect freeze <%= @_name %>` commits this file and records its SHA as
+Pre-freeze check — snapshot: no count/name-set/byte-identity frozen at merely
+today's value; control: every baseline actually run this session; mechanism: no
+*how* where the *what* is the requirement; interface: every CLI surface the
+Specification names (verb, flag spelling, subcommand) executed once before it
+freezes; dry-run:
+`architect rehearse <%= @_name %>` — RED (clean non-zero) discriminates; GREEN
+is a declared regression guard or a gate that measures nothing; BROKEN is
+advisory (a correct RED can look broken — confirm it); EMPTY is no gates or an
+untouched placeholder.
+`architect freeze <%= @_name %>` needs a fresh rehearsal stamp — editing gates
+stales it; `--skip-rehearse REASON` records the skip. The stamp records that you
+looked, never that gates passed. Freeze commits this file and records its SHA as
 freeze_sha. Read-only afterward — any change to Grounds/Specification/Acceptance
 Criteria = automatic iteration FAIL. -->
 
@@ -60,12 +78,22 @@ Criteria = automatic iteration FAIL. -->
 
 ```gates
 # Each gate backs one prose AC above. Remove the comment markers to activate.
+# `cmd` paths resolve against the REPO TREE; `cwd` is relative to the SPACE
+# ROOT. The judge-time remap is asymmetric: a `cwd` under repos/<repo> is
+# remapped into the lane worktree, one outside it passes through unchanged.
+# End a multi-step `cmd` with `echo SENTINEL` + `stdout_match`: /bin/sh (the
+# gate runner's shell) has no `set -e`, so an early branch can exit 0 — the
+# sentinel proves the command reached its end.
+# Draft, then run `architect rehearse <%= @_name %>` — before the freeze, while
+# a bad gate still costs nothing.
 # - id: suite-green        # unique slug within the iteration (required)
 #   ac: AC1                # which prose AC this gate backs (required)
-#   cwd: repos/my-repo     # run dir, relative to space root (optional; consumed by I03)
-#   cmd: bundle exec rake test  # shell command (required, non-empty)
+#   cwd: repos/my-repo     # run dir, space-root-relative (optional)
+#   cmd: |-                # block style by default — a plain scalar breaks on `: `
+#     bundle exec rake test && echo SUITE_OK
 #   expect:                # at least one of: exit_code, stdout_match, threshold
 #     exit_code: 0
+#     stdout_match: SUITE_OK
 ```
 
 ## Builder Prompt

data/lib/space_core/cli/help.rb

@@ -90,6 +90,7 @@ module Space::Core::CLI
     # members within a group, ordered by the declared order), with undeclared
     # children (namespaces) trailing in the default group.
     def grouped_listing(result)
+      # paths:exempt - result.children is a dry-cli command-tree node, not a filesystem path
       decorated = result.children.filter_map do |name, node|
         [name, node, phase_of(node)] unless node.hidden
       end
@@ -150,6 +151,7 @@ module Space::Core::CLI
     end
 
     def banner(node)
+      # paths:exempt - node.children? is a dry-cli command-tree predicate, not a filesystem path
       if node.command && node.leaf? && node.children?
         " [ARGUMENT|SUBCOMMAND]"
       elsif node.leaf?

data/lib/space_core/commands.rb

@@ -8,7 +8,7 @@ module Space::Core
     # "--flag" boundaries, continuation lines indented two spaces. Commands
     # without "--" flags are returned unchanged.
     def wrap(command)
-      parts = command.split(/(?= --)/)
+      parts = split_at_flag_boundaries(command)
       return command if parts.size <= 1
 
       parts.each_with_index.map do |part, i|
@@ -16,5 +16,36 @@ module Space::Core
         i < parts.size - 1 ? "#{segment} \\" : segment
       end.join("\n")
     end
+
+    # Same split points as command.split(/(?= --)/), but blind to " --" that
+    # falls inside a single- or double-quoted flag value, so a --title
+    # containing " -- " isn't torn apart mid-argument.
+    def split_at_flag_boundaries(command)
+      parts = []
+      start = 0
+      in_squote = false
+      in_dquote = false
+      escaped = false
+      command.each_char.with_index do |ch, i|
+        if escaped
+          escaped = false
+          next
+        end
+        case ch
+        # A backslash escapes the next character outside quotes and inside
+        # double quotes, but is a literal character inside single quotes.
+        when "\\" then escaped = true unless in_squote
+        when "'" then in_squote = !in_squote unless in_dquote
+        when '"' then in_dquote = !in_dquote unless in_squote
+        when " "
+          if !in_squote && !in_dquote && command[i + 1, 2] == "--"
+            parts << command[start...i]
+            start = i
+          end
+        end
+      end
+      parts << command[start..]
+      parts
+    end
   end
 end

data/lib/space_core/paths.rb

@@ -1,9 +1,44 @@
 # frozen_string_literal: true
 
+require "pathname"
+
 module Space::Core
   module Paths
+    # paths:exempt-file - the shared module itself — this is the one home the guard defends
     module_function
 
+    # Flags for matching a changed path against a lane's touch_set globs.
+    # PATHNAME keeps a single `*` from crossing `/`; EXTGLOB enables `{a,b}`;
+    # DOTMATCH lets a glob reach dotfile segments, so a `dir/**` touch set covers
+    # `dir/.github/workflows/ci.yml` — the standard deliverable for a lane preparing
+    # a directory to become a repo root.
+    TOUCH_FNM = File::FNM_PATHNAME | File::FNM_EXTGLOB | File::FNM_DOTMATCH
+
+    # Every path beneath root, at every depth: files, directories, dotfiles, and
+    # dot-directory contents all included. `File::FNM_DOTMATCH` is what makes
+    # dotfiles visible to `Dir.glob`, but it also emits a bogus `root/.`
+    # self-entry — that trap is absorbed here so no callsite has to know about it.
+    # Returns Array<String> — Dir.glob's native return shape.
+    def content_tree(root)
+      Dir.glob(File.join(root.to_s, "**", "*"), File::FNM_DOTMATCH).reject { |p| File.basename(p) == "." }
+    end
+
+    # The direct children of a fixed-depth structured directory layout (one
+    # entry per iteration/skill/lane/space) where a leading dot never names a
+    # real layout member — only tooling junk (.git, .DS_Store). Excludes them.
+    # Returns Array<Pathname> — Pathname#children's native return shape.
+    def layout_children(dir)
+      Pathname.new(dir).children.reject { |c| c.basename.to_s.start_with?(".") }
+    end
+
+    # Does a single touch_set glob match path? A trailing `dir/**` is matched
+    # twice: bare (PATHNAME stops it at direct children) and as `dir/**/*`,
+    # whose whole-component `**/` does cross `/`.
+    def touch_match?(glob, path)
+      File.fnmatch(glob, path, TOUCH_FNM) ||
+        (glob.end_with?("/**") && File.fnmatch("#{glob}/*", path, TOUCH_FNM))
+    end
+
     def contract(path, env: ENV)
       value = path.to_s
       home  = XDG.home(env: env)

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.1"
+    VERSION = "7.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
@@ -265,26 +277,43 @@ contract, self-contained:
   its **target repo + file-touch set, checked for overlap**: name the repo
   (`repos/<repo>`) and every file each lane may touch. The machine-readable
   declaration lives in a fenced ` ```lanes ` block in the Specification — one
-  entry per lane (`name`, `repo`, `touch` globs) — the single frozen source of
+  entry per lane (`name`, `repo`, `touch` globs; optionally `allowed_tools`/
+  `append_allowed_tools` to replace/extend the lane's builder tool grant — see
+  `dispatch.md`) — 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
   iterations are one lane — fan out only when the work is genuinely parallel (a
-  cross-repo project often is). Two first-class patterns — runnable recipes in `dispatch.md`: **parallel +
+  cross-repo project often is). Three first-class patterns — runnable recipes in `dispatch.md`: **parallel +
   fast-follow** (disjoint lanes integrate first; a fast-follow lane off
-  `project/<slug>` carries the seam — see `### Parallel + fast-follow`) and
+  `project/<slug>` carries the seam — see `### Parallel + fast-follow`),
   **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`.
+  AC — see `### Serial deferred judgment`), and **long-running sweep** (a lane
+  launches its own long detached process, ends its session at a sanctioned
+  pending status, and a later session in the same worktree audits it once it
+  exits — see `### Long-running sweep` in `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 +336,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 +402,17 @@ 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.
+  fenced ` ```lanes ` block (§4): `name`, `repo`, `touch` globs, and optionally
+  `allowed_tools`/`append_allowed_tools`.
+- **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
@@ -406,7 +494,10 @@ only the per-lane `lane/<iteration>-<lane>` branches and worktrees, never the
 project branch. Update the iteration index in `architecture/ARCHITECT.md`
 (recording the `project/<slug>` branch), remove the provisioned worktrees
 (`architect integrate … --teardown`, or `architect worktree remove <iteration>
-<lane>`), and commit the space.
+<lane>`), and commit the space. Both refuse per lane when its worktree still
+holds uncommitted work — untracked files included; `--force` overrides and
+discards it. The `--lanes` integration path itself is unaffected, since
+`integrate` commits each lane's work before teardown.
 
 **Run the frozen gates cold** — `architect gate <iteration>` runs the frozen
 gate commands against the integration tree and streams raw output (a runner, not