space-architect 9.8.0 → 9.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2a29d0c5688ed96e02a49a159385f508a845714e1741577384f6a6369a1fbb7e
-  data.tar.gz: 2b46a7ffee6ee544c9f5e30b7926f4ee5d541d81032be53617cec19f5e519bfd
+  metadata.gz: bf5117e5de28d8f40811d45561c37ccd7852a1dc27758af06f08cc565aa90b65
+  data.tar.gz: 9c5fe91d46305b83d8f0fe3f17a689238ad6e81d620f95009b96c9f74da38b14
 SHA512:
-  metadata.gz: d418323e0ef3c26cfdf2ca7d06aac9fcec9da1d74c8ccbb0a339cc5f0e85eaf9838ab5bf380f7949f28d30a416e7d5b2a0c9043e1fe74d3659ffbfaf5d764641
-  data.tar.gz: 6fdbc0e2e89a34ff61f661202fb04e0f452a5f2b096db28b2dfd0a3adf41e6b9194a82b62253e2e1d4e9647886244d0ff0e38339d898726b93d8bcebc207800f
+  metadata.gz: 4698ad55f2c91d9a71fd996ad3523c6155aefad548c2ac9dba8a1f51bc115f2cfdad0223cc0353aefda83eed5c874625b02a58fc2b065feb124adaf0202c0674
+  data.tar.gz: d031b8fc81071a4c8a68892d07af6f8b4b0bf0c458a605c437fb513dd982fd7f79afb8cae8ee82bdd6281e5bd05cbdad8bb2c22edaa07f753e7a6a73e1fd9b14

data/CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [9.9.0] - 2026-10-30
+
+### Added
+
+- **`architect ping` (I11)** — phase pings for driver-mode loops: `architect
+  ping ITERATION PHASE` emits an iteration phase transition (spec-launched,
+  builders-settled, judge-running) to the configured space server via the I16
+  emission surface. Vocabulary-first validation (unknown phase = 422-style
+  error naming the set), `--note` rides along, `--space` overrides the cwd
+  walk, and an unconfigured emission stack is inert — one inform line, exit 0.
+  A ping never gates the loop: every failure mode is one line.
+
+### Changed
+
+- **Narration cadence (I11)** — shipped skills and docs carry the three-kind
+  cadence: narrations are exactly verdict-landed, exception, and
+  plan-complete; builders-settled and judge-settled stop being narration
+  kinds (the driver pings those transitions instead). Back-to-back rule:
+  when two narration-worthy events are back-to-back, one narration lands —
+  the more-final kind absorbs the earlier. dispatch.md's narrator contract
+  now asks for composed prose (situates the project, the iteration's place,
+  what happened and what it means), never transcribed STATUS lines, run ids,
+  or gate vectors.
+
 ## [9.8.0] - 2026-10-30
 
 ### Removed

data/lib/space_architect/cli/architect.rb

@@ -904,6 +904,59 @@ module Space::Architect
         end
       end
 
+      # I11: the phase ping — one small "where is the loop now" POST per
+      # playbook step; the between-command currency that lets narrations stay
+      # rare prose. An automated playbook step, deliberately quieter than
+      # emit: unconfigured is one inert stdout line; a POST failure NEVER
+      # fails the command (exit 0 — the Emitter's single stderr line is the
+      # whole report); the token never appears in any output. Writes nothing
+      # to disk — a ping is a fact about the loop, not a loop step, so the
+      # entry lookup is read-only (no ArchitectProject mutation).
+      class Ping < BaseCommand
+        desc "POST one phase ping for an iteration (spec-launched/builders-settled/judge-running; best-effort — never fails the loop step)"
+        phase 53, "Project"
+        argument :iteration, required: true,  desc: "Iteration name"
+        argument :phase,     required: true,  desc: "Phase ping kind: spec-launched, builders-settled, or judge-running"
+        option   :space,     default: nil,    desc: "Space identifier (default: $PWD)"
+        option   :note,      default: nil,    desc: "Optional note carried in the ping payload (nil/empty omitted)"
+
+        def call(iteration:, phase:, space: nil, note: nil, **opts)
+          setup_terminal(**opts.slice(:color, :colors))
+          handle_errors do
+            # Vocabulary is validated BEFORE space resolution — a typo'd phase
+            # must name the known set, not space-resolution noise.
+            unless IterationEmission::PHASE_KINDS.include?(phase)
+              raise Space::Core::Error,
+                "unknown phase '#{phase}' — one of: #{IterationEmission::PHASE_KINDS.join(', ')}"
+            end
+
+            render(store.find(space)) do |sp|
+              # Read-only slice of the space.yaml iteration record — the exact
+              # entry lookup and error text of ArchitectProject#slice_entry,
+              # mirrored here rather than instantiated: the ping path never
+              # mutates anything on disk (a ping is a fact, not a loop step).
+              entry = ((sp.data["project"] || {})["iterations"] || []).find { |s| s["name"] == iteration }
+              unless entry
+                raise Space::Core::Error,
+                  "Iteration '#{iteration}' not recorded in space.yaml — run `architect new #{iteration}` first"
+              end
+
+              emitter = IterationEmission.emitter_for(sp)
+              if emitter
+                res = emitter.post("phase", IterationEmission.build_phase(
+                  ordinal: entry["ordinal"], name: entry["name"], kind: phase, note: note))
+                # res nil: the Emitter already printed its one stderr line —
+                # a failed ping stays off stdout and never fails the step.
+                terminal.say "pinged #{iteration} #{phase} → #{res[:status]}" if res
+              else
+                terminal.say "emission off (unconfigured)"
+              end
+              CLI.record_outcome(Outcome.new(exit_code: 0))
+            end
+          end
+        end
+      end
+
       # Pretty-print a pi agent run.jsonl as it streams — the ported runlog
       # printer. No space resolution: the stream is the whole input.
       class Runlog < BaseCommand
@@ -1498,6 +1551,7 @@ Space::Architect::CLI::Registry.register "install-agents",   Space::Architect::C
 Space::Architect::CLI::Registry.register "runlog",          Space::Architect::CLI::Architect::Runlog
 Space::Architect::CLI::Registry.register "looplog",         Space::Architect::CLI::Architect::Looplog
 Space::Architect::CLI::Registry.register "emit",           Space::Architect::CLI::Architect::Emit
+Space::Architect::CLI::Registry.register "ping",           Space::Architect::CLI::Architect::Ping
 Space::Architect::CLI::Registry.register "bug-report",     Space::Architect::CLI::Architect::BugReport
 Space::Architect::CLI::Registry.register "cost",           Space::Architect::CLI::Architect::Cost
 Space::Architect::CLI::Registry.register "brief" do |b|

data/lib/space_architect/iteration_emission.rb

@@ -14,6 +14,10 @@ module Space::Architect
   # ```rulings block parser. ArchitectProject's five hook call sites guard
   # through `emitter&.post` inside a rescue-all belt; nothing here may ever
   # raise into a loop command or change its exit code, stdout, or commits.
+  # I11 extends the same layer additively: the phase mouth (a fifth server
+  # mouth) and the `architect ping` payload — one small "where is the loop
+  # now" fact per playbook step, the between-command currency that lets
+  # narrations stay rare prose.
   module IterationEmission
     # Frozen tuning (mirrors the spec; session-sink pins its own constants the
     # same way): per attempt 2s open / 5s read, at most 2 attempts, retry on
@@ -22,13 +26,20 @@ module Space::Architect
     READ_TIMEOUT = 5
     MAX_ATTEMPTS = 2
 
-    # The four server mouths (I15, frozen): POST <host>/iterations/ingest/<mouth>.
-    MOUTHS = %w[freeze lane verdict integration].freeze
+    # The server mouths (I15's four frozen; I11 appends the fifth): POST
+    # <host>/iterations/ingest/<mouth>.
+    MOUTHS = %w[freeze lane verdict integration phase].freeze
 
     # Iteration/lane status vocabularies (frozen): nothing else is emitted.
     ITERATION_STATUSES = %w[frozen integrated].freeze
     LANE_STATUSES      = %w[complete integrated].freeze
 
+    # The phase-ping vocabulary (I11, CLI-frozen): nothing else pings. Sibling
+    # of the narration kinds — narrations stay rare prose at verdict-landed
+    # (+ exception, plan-complete); these pings carry the between-command
+    # "where is the loop now" currency.
+    PHASE_KINDS = %w[spec-launched builders-settled judge-running].freeze
+
     # The space-slug rule (architect_project.rb :1642), with the emission-layer
     # fallback: space.data["id"] when the title is absent or slugifies empty.
     def self.slug_for(space)
@@ -269,6 +280,18 @@ module Space::Architect
       }
     end
 
+    # One phase ping (I11, the phase mouth): the iteration identity plus where
+    # the loop stands. The iteration hash carries ONLY ordinal + name — the
+    # mouth's other iteration keys belong to the other mouths and the ping
+    # path never sends them. note rides when given; nil/empty is omitted
+    # entirely (compact_scalars discipline).
+    def self.build_phase(ordinal:, name:, kind:, note: nil)
+      {
+        "iteration" => compact_scalars("ordinal" => ordinal, "name" => name),
+        "phase" => compact_scalars("kind" => kind, "note" => note)
+      }
+    end
+
     # ---- the ```rulings block (S3) ------------------------------------------
     #
     # A fenced YAML block inside the ## Verdict body — the ```gates/```lanes

data/lib/space_architect/version.rb

@@ -2,6 +2,6 @@
 
 module Space
   module Architect
-    VERSION = "9.8.0"
+    VERSION = "9.9.0"
   end
 end

data/skill/architect/SKILL.md

@@ -84,8 +84,10 @@ the space durable across sessions:
   `build/<id>-<lane>/run.jsonl`).
 - **judge** — a fresh session that runs the cold gates and rules per-AC
   verdicts; nobody grades their own work.
-- **narrator** — writes one `notes/narrative-*` best-effort update per
-  settled loop event; facts only, never a gate.
+- **narrator** — writes rare prose: one best-effort `notes/narrative-*` per
+  iteration at verdict-landed (plus exception, plan-complete), written for a
+  human whose context went stale; never a gate — the between-command currency
+  is `architect ping` phase pings.
 
 **The workspace**
 

data/skill/architect-discuss/SKILL.md

@@ -56,7 +56,7 @@ project — loads them.
 | **spec** | subagent | one iteration's Grounds/Specification/Acceptance Criteria; rehearses; freezes; writes the `notes/spec-digest-*` handoff |
 | **builder** | subagent per lane | implementation in the lane worktree; raw-results report; never commits |
 | **judge** | subagent, fresh session | mechanical post-flight, cold gates, per-AC verdicts, PHASE 0 rulings, integration |
-| **narrator** | subagent | one `notes/narrative-*` file per settled loop event — facts only, never a gate |
+| **narrator** | subagent | rare prose: one `notes/narrative-*` file per iteration at verdict-landed (plus exception, plan-complete), written for a human whose context went stale — never a gate; the between-command currency is `architect ping` phase pings |
 
 ## Visibility while a loop runs
 

data/skill/architect-discuss/dispatch.md

@@ -11,7 +11,9 @@ completion wakes, not `architect dispatch` headless runs. Per iteration:
    ENTRY verbatim. Writes Grounds/Specification/Acceptance Criteria via
    `architect section`, rehearses, freezes, assembles each lane's prompt in a
    scratch file, records the scratch paths in its report, and writes the
-   `notes/spec-digest-*` handoff. `timeoutMs` 3600000 (1h).
+   `notes/spec-digest-*` handoff. `timeoutMs` 3600000 (1h). Once the spec
+   spawn is confirmed running, ping the phase — best-effort bash, never a
+   gate: `architect ping <iteration> spec-launched || true`.
 2. **provision** — the driver runs `architect provision <iteration>` via
    bash; the CLI materializes every declared lane's worktree + lane branch.
 3. **prompt copy** — the driver copies each spec-assembled scratch prompt
@@ -20,14 +22,18 @@ completion wakes, not `architect dispatch` headless runs. Per iteration:
 4. **builder per lane** — agent `architect-builder`, cwd = that lane's
    worktree, task = read `build/<id>-<lane>/prompt.md` before anything else.
    `timeoutMs` 7200000 (2h). The lane-prompt template below is the contract
-   the spec assembles against.
+   the spec assembles against. When every builder is tended to completion,
+   ping the phase — best-effort bash, never a gate:
+   `architect ping <iteration> builders-settled || true`.
 5. **judge** — agent `architect-judge`, cwd = the space root, task = judge the
    iteration by id. `timeoutMs` 7200000 (2h). The judge is a fresh session —
    §1 fresh-session judgment holds structurally: the judge session never
-   dispatched or built anything.
-6. **narrator** — one `architect-narrator` spawn per settled event
-   (builders-settled, judge-settled, verdict-landed, exception, plan-complete),
-   `timeoutMs` 300000 (5m), best-effort, never a gate on the loop.
+   dispatched or built anything. Once the judge spawn is confirmed running,
+   ping the phase — best-effort bash, never a gate:
+   `architect ping <iteration> judge-running || true`.
+6. **narrator** — one `architect-narrator` spawn per narration
+   (verdict-landed, exception, plan-complete), `timeoutMs` 300000 (5m),
+   best-effort, never a gate on the loop.
 
 Spawn contract (all paths): every spawn pins its model explicitly
 (provider/id[:thinking]) and carries an explicit `timeoutMs` — never the

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: space-architect
 version: !ruby/object:Gem::Version
-  version: 9.8.0
+  version: 9.9.0
 platform: ruby
 authors:
 - Eric Jacobs