@zalom/plastic 1.0.0-beta.2 → 1.0.0-beta.3

package/agents/plastic-brainstorming.md

@@ -27,7 +27,15 @@ When dispatched in auto mode you receive the standard Plastic spawn preamble (fr
 2. Read the intent file, its `## Links`, and related code or docs
 3. Research with the adaptive budget the enforcer set (simple 2-3, medium 5-8, complex 10-15 steps)
 4. Produce (output handoff): an enriched `## Context` plus `### Decisions` with rationale
-5. Log autonomous calls in `## Insights` with the `(autonomous)` marker, then report for gating
+5. Log autonomous calls in `## Insights` with the `(autonomous)` marker, then report for gating (see `## Completion Report`)
+
+## Completion Report
+
+END your turn with a structured completion report as your final message, per the spawn preamble's `REPORT_CONTRACT` and `skills/auto/references/agent-report-contract.md`. Do not finish silently. Carry the common envelope (role, intent id, stage, status, artifacts written, verification, checklist deltas, deviations, blockers) plus the brainstorming payload:
+
+- Decisions recorded in `### Decisions`, each with its one-line rationale
+- Context enriched: what was researched and the key findings
+- Open questions resolved, and any deliberately left for the spec
 
 ## Constraints
 

package/agents/plastic-executor.md

@@ -28,6 +28,16 @@ When dispatched in auto mode you receive the standard Plastic spawn preamble (fr
 3. Edit project code (the gate is open now that plan and checklist exist)
 4. Run the full suite, iterate to zero failures and zero errors
 5. Produce (output handoff): the code changes, a checked-off `checklist.md`, and `## Insights`
+6. Report for gating (see `## Completion Report`); the enforcer reviews the work at the final gate
+
+## Completion Report
+
+END your turn with a structured completion report as your final message, per the spawn preamble's `REPORT_CONTRACT` and `skills/auto/references/agent-report-contract.md`. Do not finish silently. Carry the common envelope (role, intent id, stage, status, artifacts written, verification, checklist deltas, deviations, blockers) plus the executor payload:
+
+- Actions implemented this turn, mapped to checklist items checked off (checked / total)
+- A summary of the code changed (files and the shape of the change)
+- Test result: the full-suite command and its pass / fail counts
+- Insights appended, with the `(autonomous)` marker
 
 ## Constraints
 

package/agents/plastic-planner.md

@@ -27,7 +27,17 @@ When dispatched in auto mode you receive the standard Plastic spawn preamble (fr
 2. Read `spec.md` and the plan/checklist templates; match their FORM
 3. Write `plan.md`, the `actions/` directory, and `checklist.md` into the intent directory
 4. Produce (output handoff): `plan.md` plus `actions/` plus `checklist.md`
-5. Report for gating; the enforcer verifies plan and checklist exist before Exec is allowed
+5. Report for gating (see `## Completion Report`); the enforcer verifies plan and checklist exist before Exec is allowed
+
+## Completion Report
+
+END your turn with a structured completion report as your final message, per the spawn preamble's `REPORT_CONTRACT` and `skills/auto/references/agent-report-contract.md`. Do not finish silently. Carry the common envelope (role, intent id, stage, status, artifacts written, verification, checklist deltas, deviations, blockers) plus the planner payload, which EXPLAINS THE PLAN BACK TO THE ORCHESTRATOR:
+
+- The ordered actions, one line each: what the action does and how it is verified
+- Decomposition rationale: why this order, and why the actions are independent
+- Checklist coverage: the item count, and that every action plus suite-green is covered
+
+The plan is an argument; the orchestrator gates on whether that argument is sound before any code is written, so make the report make that case.
 
 ## Constraints
 

package/agents/plastic-spec-specialist.md

@@ -27,7 +27,15 @@ When dispatched in auto mode you receive the standard Plastic spawn preamble (fr
 2. Read the spec template (`templates/spec.md`) and match its FORM exactly
 3. Write `spec.md` into the intent directory, resolving the decisions into a coherent approach
 4. Produce (output handoff): a complete `spec.md`
-5. Report for gating; the enforcer checks the spec against its exit criteria before How begins
+5. Report for gating (see `## Completion Report`); the enforcer checks the spec against its exit criteria before How begins
+
+## Completion Report
+
+END your turn with a structured completion report as your final message, per the spawn preamble's `REPORT_CONTRACT` and `skills/auto/references/agent-report-contract.md`. Do not finish silently. Carry the common envelope (role, intent id, stage, status, artifacts written, verification, checklist deltas, deviations, blockers) plus the spec payload:
+
+- The spec sections produced (Problem, Goals, Non-Goals, Approach, Decisions, Acceptance Criteria)
+- How the recorded decisions resolved into the chosen approach
+- The acceptance-criteria count, so the planner knows the surface to cover
 
 ## Constraints
 

package/package.json

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

package/scripts/agent-report

@@ -0,0 +1,142 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# agent-report - deterministic filesystem-derived completion report (intent 74).
+#
+# The auto-mode report contract is decision-shaped (the spawn preamble's
+# REPORT_CONTRACT plus the role prompts ask every dispatched agent to END with a
+# structured completion report). Because child-agent honor is best-effort across
+# harnesses (Tier B/C, docs/reference/harness-adapters.md), the contract is never a
+# hard block. This script is the always-a-report fallback: when a dispatched agent
+# returns no usable report, the enforcer runs it to synthesize one from the intent
+# directory, so the handoff account always exists.
+#
+# Like scripts/spawn-preamble, 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.
+#
+# Usage:
+#   agent-report <intent_dir> [--role ROLE]
+#
+# Exit codes: 0 (report emitted), 2 (usage).
+
+require_relative "lib/bridge"
+
+def parse_args(argv)
+  role = nil
+  positional = []
+  i = 0
+  while i < argv.length
+    case argv[i]
+    when "--role"
+      role = argv[i + 1]
+      i += 2
+    else
+      positional << argv[i]
+      i += 1
+    end
+  end
+  [positional.first, role]
+end
+
+# Read the intent file frontmatter via the same path spawn-preamble uses, so the
+# id/intent we report match what the rest of Plastic sees. 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: prefer the last non-empty savepoint line (the ledger encodes the
+# furthest-reached milestone), else the file-derived stage. Same logic as
+# spawn-preamble's current_stage.
+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
+
+# checklist.md checked/total: count GFM task-list items. Returns "n/a" when there
+# is no checklist (a checklist is only meaningful from How onward).
+def checklist_progress(intent_dir)
+  path = File.join(intent_dir, "checklist.md")
+  return "n/a" unless Bridge.stage_file_present?(path)
+
+  lines = File.readlines(path)
+  total = lines.count { |l| l =~ /^\s*- \[[ xX]\]/ }
+  checked = lines.count { |l| l =~ /^\s*- \[[xX]\]/ }
+  return "n/a" if total.zero?
+
+  "#{checked}/#{total}"
+end
+
+# The outcome line: first content line under outcome.md's "## Summary" (or the first
+# non-heading content line), else a placeholder. Pure read of the intent dir.
+def outcome_line(intent_dir)
+  path = File.join(intent_dir, "outcome.md")
+  return "(no outcome yet)" unless Bridge.stage_file_present?(path)
+
+  lines = File.readlines(path).map(&:rstrip)
+  start = lines.index { |l| l.strip.downcase == "## summary" }
+  scan = start ? lines[(start + 1)..] : lines
+  (scan || []).each do |l|
+    s = l.strip
+    next if s.empty? || s.start_with?("#") || s.start_with?("<!--")
+    return s
+  end
+  "(no outcome yet)"
+end
+
+intent_dir_arg, role = parse_args(ARGV)
+
+if intent_dir_arg.nil? || intent_dir_arg.empty?
+  warn "usage: agent-report <intent_dir> [--role ROLE]"
+  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)
+role_label = (role && !role.empty?) ? role : stage
+artifacts = Bridge.has_files(intent_dir)
+artifacts_str = artifacts.empty? ? "(none)" : artifacts.join(", ")
+
+lines = []
+lines << "=== Plastic agent report (synthesized) ==="
+lines << "Intent: #{id} - #{intent_name}"
+lines << "Stage: #{stage}"
+lines << "Role: #{role_label}"
+lines << "Status: synthesized (filesystem-derived; no agent-authored report)"
+lines << "Artifacts present: #{artifacts_str}"
+lines << "Checklist: #{checklist_progress(intent_dir)}"
+lines << "Outcome: #{outcome_line(intent_dir)}"
+lines << "=== end report ==="
+
+puts lines.join("\n")

package/scripts/spawn-preamble

@@ -29,7 +29,22 @@ require_relative "lib/bridge"
 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."
+  "Your primary output is valid lifecycle artifacts; you close with a structured report about them."
+
+# Verbatim completion-report contract (intent 74). Kept as one constant so the
+# contract doc (skills/auto/references/agent-report-contract.md), the role prompts,
+# and the test assert against the exact same string. SINGLE SOURCE OF TRUTH for the
+# report wording: the work output is lifecycle artifacts, the final message is a
+# structured report about them. Both are required and they do not contradict.
+REPORT_CONTRACT =
+  "Before you finish, END your turn with a structured completion report as your " \
+  "FINAL MESSAGE (your return value), not a side-channel file. Do not go idle or " \
+  "finish silently. The report carries a common envelope: role, intent id, stage, " \
+  "status (delivered or blocked), artifacts written, verification or tests run, " \
+  "checklist deltas, deviations from spec, and blockers or handoff notes; plus a " \
+  "role-specific payload that fulfils your place in the What, Why, How, Exec cycle " \
+  "(for example the planner explains the plan back to the orchestrator). See " \
+  "skills/auto/references/agent-report-contract.md for the per-role format."
 
 def parse_args(argv)
   role = nil
@@ -116,6 +131,8 @@ lines << "Current stage: #{stage}"
 lines << "Cycle step / role: #{cycle}"
 lines << ""
 lines << HONOR_INSTRUCTION
+lines << ""
+lines << REPORT_CONTRACT
 lines << "=== end preamble ==="
 
 puts lines.join("\n")

package/skills/auto/SKILL.md

@@ -68,6 +68,8 @@ Dispatch rule: sequential, one specialist per stage on one branch (the deliverab
 
 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`).
 
+Completion report (require-then-synthesize): every dispatched specialist MUST end with a structured completion report as its final message. The preamble's `REPORT_CONTRACT` injects this and the role prompts carry the per-role format (see `references/agent-report-contract.md`). Because child-agent honor is best-effort across harnesses, this is decision-shaping, not a hard block. When a specialist returns no usable report (it went idle, emitted only a bare ping, or its message was lost to a mid-run interjection), run `scripts/agent-report <intent_dir> --role <role>` to synthesize a deterministic filesystem-derived report so the handoff account always exists. Use the agent-authored report when present, the synthesized one otherwise.
+
 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

@@ -61,6 +61,26 @@ and not hallucinate intents or stages. This is the standard L2 live-state mechan
 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.
 
+### Completion Reports
+
+Every dispatched specialist ends its turn with a structured completion report as its final
+message (its return value), so the agent that did the work is the one that accounts for it. The
+report carries a common envelope plus a role-specific payload that fulfils the agent's place in
+the cycle; the planner explains the plan back to the orchestrator, the executor reports what was
+built and the test result, and so on. The format lives in `references/agent-report-contract.md`,
+and the verbatim instruction is injected once via the spawn preamble's `REPORT_CONTRACT`
+constant, which the role prompts reproduce.
+
+Enforcement is require-report then synthesize-fallback. The preamble and prompts make the report
+mandatory (decision-shaping), but child-agent honor is best-effort across harnesses (Tier B/C),
+so it is never a hard block. When a specialist returns no usable report, the enforcer runs
+`scripts/agent-report <intent_dir> --role <role>`, a pure function of the intent dir (no network,
+clock, or randomness, mirroring `spawn-preamble`) that emits a filesystem-derived report from the
+savepoint, the artifacts present, the checklist checked/total, and the outcome line. A handoff
+account therefore always exists: agent-authored when present, deterministically reconstructed
+otherwise. This structures the finish notification only; in-flight observations stay in
+`## Insights`, no progress chatter is added.
+
 ### Gate Ownership
 
 The enforcer arms and verifies the lifecycle gate, then gates every stage transition.

package/skills/auto/references/agent-report-contract.md

@@ -0,0 +1,86 @@
+# Agent Completion Report Contract
+
+Every agent dispatched by the auto-mode enforcer MUST end its turn with a structured
+completion report. This doc defines that report: one common envelope plus a per-role payload.
+It is the format the `REPORT_CONTRACT` constant in `scripts/spawn-preamble` points at, the
+role prompts (`agents/plastic-*.md`) reproduce, and the deterministic fallback
+(`scripts/agent-report`) approximates. Keep all four in agreement; the constant in
+`scripts/spawn-preamble` is the single source of truth for the injected wording.
+
+## Purpose
+
+The report is the agent's FINAL MESSAGE (its return value), not a side-channel file. Every
+harness hands a spawned agent's final text back to the dispatcher, so the final message is the
+one carrier that works everywhere (decision D1). The report structures the FINISH notification
+only. In-flight observations still go in `## Insights`; the report does not add progress chatter
+(decision D5). An agent that finishes correct artifacts but goes idle without a report has not
+completed its handoff: the agent that did the work is the cheapest, most accurate source of the
+account.
+
+## Common envelope
+
+Every role report, whatever the stage, carries these fields:
+
+- **Role**: which specialist produced this (brainstorming, spec, planner, executor, reviewer).
+- **Intent id and stage**: the active intent id and the cycle stage just completed.
+- **Status**: `delivered` or `blocked`.
+- **Artifacts written**: the files produced or changed (store paths, and project paths for the
+  executor).
+- **Verification / tests run**: the command run and its result, or `n/a` for stages that write
+  no code.
+- **Checklist deltas**: which checklist items this turn checked off (executor), or `n/a`.
+- **Deviations from spec**: anything done differently from the spec or plan, and why, or `none`.
+- **Blockers / handoff notes**: what the next stage must watch for, or `none`.
+
+## Per-role payload
+
+Each role appends a payload that fulfils its place in the What, Why, How, Exec cycle (decision
+D2). The payload is what makes the report useful to the orchestrator beyond the envelope.
+
+### brainstorming (Why exploration)
+- Decisions recorded in `### Decisions`, each with its one-line rationale.
+- Context enriched: what was researched and the key findings.
+- Open questions resolved, and any deliberately left for the spec.
+
+### spec-specialist (Why to How boundary)
+- Spec sections produced (Problem, Goals, Non-Goals, Approach, Decisions, Acceptance Criteria).
+- How the recorded decisions resolved into the chosen approach.
+- Acceptance-criteria count, so the planner knows the surface to cover.
+
+### planner (How): worked exemplar
+The planner report EXPLAINS THE PLAN BACK TO THE ORCHESTRATOR. It carries:
+- The ordered actions, one line each: what the action does and how it is verified.
+- Decomposition rationale: why this order, and why the actions are independent.
+- Checklist coverage: item count and that every action plus suite-green is covered.
+This is the exemplar because the plan is an argument, and the orchestrator gates on whether that
+argument is sound before any code is written.
+
+### executor (Exec)
+- Actions implemented this turn, mapped to checklist items checked off (checked / total).
+- A summary of the code changed (files and the shape of the change).
+- Test result: the full-suite command and its pass / fail counts.
+- Insights appended, with the `(autonomous)` marker.
+
+### final reviewer (final gate)
+- Verdict: `pass` or `blockers found`.
+- Each acceptance criterion checked, with the evidence that confirms or refutes it.
+- Gaps or risks found, ranked, with a recommended disposition.
+
+## Fallback: always a report
+
+Decision-shaping (the preamble plus these prompts) makes the report mandatory, but child-agent
+honor is best-effort across harnesses (Tier B/C in `docs/reference/harness-adapters.md`), so the
+contract is never a hard block (decision D3). When a dispatched agent returns no usable report
+(it went idle, emitted only a bare ping, or its message was lost to a mid-run interjection), the
+enforcer synthesizes one:
+
+```
+scripts/agent-report <intent_dir> --role <role>
+```
+
+`scripts/agent-report` is a pure function of the intent directory (no network, clock, or
+randomness, mirroring `scripts/spawn-preamble`): it reads the current stage from the savepoint
+ledger, the lifecycle artifacts present, the checklist checked / total, and the `## Outcome`
+line, and emits a filesystem-derived report labelled `synthesized`. So a handoff account always
+exists: authored by the agent when possible, reconstructed deterministically when not. This
+formalizes the by-hand reconstruction the orchestrator did while delivering intent 68.