@zalom/plastic 1.0.0-alpha.34 → 1.0.0-alpha.35

package/agents/plastic-brainstorming.md

@@ -12,6 +12,8 @@ model: inherit
 
 You are the Plastic Brainstorming specialist. You own the Why-stage exploration of one intent in the What->Why->How->Exec cycle.
 
+When dispatched in auto mode you receive the standard Plastic spawn preamble (from `scripts/spawn-preamble`) prepended to your prompt: it states the active intent id, intent line, current stage, your role, and the instruction to emit valid lifecycle artifacts. Honor it as your live state; do not re-derive or contradict it.
+
 ## Your Responsibilities
 
 1. **Explore the problem** — read the intent's `## Intent` and `## Context`, the linked intents, and the relevant code

package/agents/plastic-executor.md

@@ -12,6 +12,8 @@ model: inherit
 
 You are the Plastic Executor. You own the Exec stage of the What->Why->How->Exec cycle.
 
+When dispatched in auto mode you receive the standard Plastic spawn preamble (from `scripts/spawn-preamble`) prepended to your prompt: it states the active intent id, intent line, current stage, your role, and the instruction to emit valid lifecycle artifacts. Honor it as your live state; do not re-derive or contradict it.
+
 ## Your Responsibilities
 
 1. **Implement the actions** — make the code changes for each action in order

package/agents/plastic-planner.md

@@ -12,6 +12,8 @@ model: inherit
 
 You are the Plastic Planner. You own the How stage of the What->Why->How->Exec cycle.
 
+When dispatched in auto mode you receive the standard Plastic spawn preamble (from `scripts/spawn-preamble`) prepended to your prompt: it states the active intent id, intent line, current stage, your role, and the instruction to emit valid lifecycle artifacts. Honor it as your live state; do not re-derive or contradict it.
+
 ## Your Responsibilities
 
 1. **Decompose the spec** — break the approach into ordered, independent actions

package/agents/plastic-spec-specialist.md

@@ -12,6 +12,8 @@ model: inherit
 
 You are the Plastic Spec Specialist. You own the Why-to-How boundary in the What->Why->How->Exec cycle.
 
+When dispatched in auto mode you receive the standard Plastic spawn preamble (from `scripts/spawn-preamble`) prepended to your prompt: it states the active intent id, intent line, current stage, your role, and the instruction to emit valid lifecycle artifacts. Honor it as your live state; do not re-derive or contradict it.
+
 ## Your Responsibilities
 
 1. **Consolidate the Why** — turn the enriched `## Context` and `### Decisions` into one spec

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zalom/plastic",
-  "version": "1.0.0-alpha.34",
+  "version": "1.0.0-alpha.35",
   "description": "Intent-driven idea development system for AI coding agents",
   "type": "module",
   "bin": {

package/scripts/hook-gate-check

@@ -8,6 +8,7 @@
 
 require "json"
 require_relative "lib/bridge"
+require_relative "lib/intent_validator"
 
 file_path = ARGV[0]
 exit 0 unless file_path && !file_path.empty?
@@ -28,6 +29,24 @@ if intent_dir_abs
   end
 end
 
+# --- Artifact-validity backstop (intent 4a1c1) ---
+# When the written file IS the intent file itself (the `<id>--<slug>.md` directly
+# inside `store/<id>--<slug>/`), run IntentValidator on it. This is headless-safe:
+# it depends only on the file path and disk, never on a bridge or session. In the
+# PostToolUse model the write has already happened, so we cannot prevent it; the
+# loud non-zero exit + stderr is the rejection signal. NOT for spec.md/plan.md/
+# checklist.md/outcome.md/savepoint.md — those are validated by the stage gates.
+if intent_dir_abs && File.basename(file_path_abs) == File.basename(Bridge.intent_file(intent_dir_abs))
+  result = IntentValidator.validate(intent_dir_abs)
+  unless result[:ok]
+    warn "PLASTIC ARTIFACT INVALID — #{File.basename(file_path_abs)} is not born complete:"
+    result[:missing].each { |field| warn "  missing required field: #{field}" }
+    result[:errors].each { |error| warn "  #{error}" }
+    warn "Fix the frontmatter; the intent is not valid until every required field is present and sources/chain are well-formed."
+    exit 1
+  end
+end
+
 # --- Find bridge file ---
 bridge_data = Bridge.discover_bridge(session: session, cwd: Dir.pwd)
 

package/scripts/lib/installer_core.rb

@@ -208,6 +208,7 @@ class InstallerCore
       "scripts/qmd-sync" => "scripts/qmd-sync",
       "scripts/lib/intent_validator.rb" => "scripts/lib/intent_validator.rb",
       "scripts/validate-intent" => "scripts/validate-intent",
+      "scripts/spawn-preamble" => "scripts/spawn-preamble",
       "scripts/lib/store_provisioning.rb" => "scripts/lib/store_provisioning.rb",
       "scripts/provision-project-store" => "scripts/provision-project-store",
       "scripts/lib/installer_core.rb" => "scripts/lib/installer_core.rb",

package/scripts/spawn-preamble

@@ -0,0 +1,121 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# spawn-preamble — deterministic live-state injection for spawned agents
+# (intent 4a1c1, agent harness foundation).
+#
+# Emits a preamble block built ONLY from filesystem state for a single intent
+# directory. It is a PURE function of the intent dir: no network, no randomness,
+# no wall-clock reads. Two runs over the same on-disk state produce byte-identical
+# output. This is the authoritative L2 (live-state) mechanism for harnesses whose
+# spawned sub-agents do not inherit a top-level session event (see
+# docs/reference/harness-adapters.md).
+#
+# Usage:
+#   spawn-preamble <intent_dir> [--role ROLE] [--step STEP]
+#
+# The preamble reports the active intent (id + intent line from frontmatter), the
+# current lifecycle stage (last savepoint line if present, else derived from which
+# lifecycle files exist), the cycle role/step (from --role/--step, else the
+# derived stage), and an imperative honoring instruction.
+#
+# Exit codes: 0 (preamble emitted), 2 (usage).
+
+require_relative "lib/bridge"
+
+# Verbatim honoring instruction. Kept as one constant so the contract doc and the
+# test assert against the exact same string.
+HONOR_INSTRUCTION =
+  "You are operating inside Plastic. Use it as your operating scaffold. " \
+  "Emit VALID lifecycle artifacts; do not hallucinate intents or stages. " \
+  "Your output is a deliverable, not a message."
+
+def parse_args(argv)
+  role = nil
+  step = nil
+  positional = []
+  i = 0
+  while i < argv.length
+    case argv[i]
+    when "--role"
+      role = argv[i + 1]
+      i += 2
+    when "--step"
+      step = argv[i + 1]
+      i += 2
+    else
+      positional << argv[i]
+      i += 1
+    end
+  end
+  [positional.first, role, step]
+end
+
+# Read the intent file frontmatter via the same parser the validator uses, so the
+# id/intent we report match what the rest of Plastic sees. Returns a Hash (possibly
+# empty) — never raises.
+def frontmatter_for(intent_dir)
+  ifile = Bridge.intent_file(intent_dir)
+  return {} unless File.exist?(ifile)
+
+  content = File.read(ifile)
+  return {} unless content.start_with?("---")
+
+  parts = content.split("---", 3)
+  return {} if parts.length < 3
+
+  require "yaml"
+  require "date"
+  require "time"
+  YAML.safe_load(parts[1], permitted_classes: [Date, Time]) || {}
+rescue StandardError
+  {}
+end
+
+# Current stage label. Prefer the last non-empty line of savepoint.md (the ledger
+# already encodes the furthest-reached milestone). Fall back to the file-derived
+# stage when there is no ledger.
+STAGE_LABELS = {
+  "what" => "What", "why" => "Why", "how" => "How",
+  "exec" => "Exec", "done" => "Done"
+}.freeze
+
+def current_stage(intent_dir)
+  ledger = File.join(intent_dir, Bridge::SAVEPOINT_FILE)
+  if File.exist?(ledger)
+    last = File.read(ledger).each_line.map(&:strip).reject(&:empty?).last
+    return last if last
+  end
+  STAGE_LABELS.fetch(Bridge.derive_stage(intent_dir), Bridge.derive_stage(intent_dir))
+end
+
+intent_dir_arg, role, step = parse_args(ARGV)
+
+if intent_dir_arg.nil? || intent_dir_arg.empty?
+  warn "usage: spawn-preamble <intent_dir> [--role ROLE] [--step STEP]"
+  exit 2
+end
+
+intent_dir = File.expand_path(intent_dir_arg)
+
+fm = frontmatter_for(intent_dir)
+id = fm["id"].to_s.strip
+intent_name = fm["intent"].to_s.strip
+id = "(unknown)" if id.empty?
+intent_name = "(unknown)" if intent_name.empty?
+
+stage = current_stage(intent_dir)
+cycle = role || step || stage
+
+lines = []
+lines << "=== Plastic spawn preamble ==="
+lines << "Store: #{intent_dir}"
+lines << "Active intent: #{id} - #{intent_name}"
+lines << "Current stage: #{stage}"
+lines << "Cycle step / role: #{cycle}"
+lines << ""
+lines << HONOR_INSTRUCTION
+lines << "=== end preamble ==="
+
+puts lines.join("\n")

package/skills/auto/SKILL.md

@@ -66,6 +66,8 @@ Roster (one role per cycle stage):
 
 Dispatch rule: sequential, one specialist per stage on one branch (the deliverables share files). Gate each deliverable against the stage's exit criteria before handing off. The How and Exec phases below default to Plastic's native dispatch (`plastic-executing-plan`) and delegate to the superpowers skills only when they are available or the user asks; do not restate the phase mechanics here.
 
+Spawn preamble (live-state injection): before dispatching any specialist, run `scripts/spawn-preamble <intent_dir> --role <role>` and PREPEND its output to that specialist's prompt. The preamble is a deterministic, filesystem-only snapshot of the active intent (id, intent line, current stage) plus the honoring instruction, so every spawned agent boots with accurate live state instead of guessing. This is the authoritative L2 mechanism for harnesses whose sub-agents do not inherit a top-level session event (see `docs/reference/harness-adapters.md`).
+
 Final-gate review: dispatch an independent reviewer subagent at the final gate only, not as a standing role.
 
 Headless manual gate: when running headless or in the background, enforce gates manually and do not rely on hooks, because `CLAUDE_SESSION_ID` may be unset (this ties to the arm-gate fallback above).

package/skills/auto/references/agent-architecture.md

@@ -48,6 +48,19 @@ The chain: intent `## Intent` / `## Context`, then enriched `## Context` plus
 `### Decisions`, then `spec.md`, then `plan.md` plus `actions/` plus `checklist.md`,
 then the code changes plus a checked-off checklist plus `## Insights`.
 
+### Spawn Preamble (L2 live-state injection)
+
+Every dispatched specialist is booted with a spawn preamble: the enforcer runs
+`scripts/spawn-preamble <intent_dir> --role <role>` and prepends its output to the
+specialist's prompt. The preamble is a pure function of the intent directory on disk
+(no network, no clock, no randomness), so it is deterministic and rebuildable. It
+carries the active intent id and intent line, the current lifecycle stage (the last
+savepoint line, else stage derived from which lifecycle files exist), the cycle
+role, and the honoring instruction that the agent must emit valid lifecycle artifacts
+and not hallucinate intents or stages. This is the standard L2 live-state mechanism
+for harnesses whose spawned sub-agents do not inherit the top-level session event. See
+`docs/reference/harness-adapters.md` for how it slots into the per-harness contract.
+
 ### Gate Ownership
 
 The enforcer arms and verifies the lifecycle gate, then gates every stage transition.