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

package/PLASTIC.md

@@ -35,15 +35,21 @@ Identity and knowledge graph only. Nothing operational.
 ---
 id: "4a1"
 intent: "Short description of the desire"
-sources: ["4a"]        # backward links — what influenced this
-chain: ["4a1a"]        # forward links — what this spawned
+sources: ["4a"]        # direct ascendants: intents this was created from
+chain: ["4a1a"]        # forward: what this spawned and related successors
 created: 2026-05-29
 author: human          # human | agent-name
 tags: [plastic, architecture]
 ---
 ```
 
-- `sources` + `chain` form the double-linked knowledge graph (Folgezettel)
+- `sources` (formative, must-load, acyclic) and `chain` (forward + relational, lighter,
+  may cycle) form the directed knowledge graph. Reciprocity is one-directional: every
+  `sources` edge has a reciprocal `chain` entry (I1), but `chain` may carry relational
+  entries with no reciprocal `sources` (I2), so the graph is not strictly symmetric.
+- Context contract: load `sources` strongly (they are what the intent was built from);
+  traverse `chain` lightly for discovery. See
+  docs/concepts/how-plastic-sources-and-chains-intents.md for the full model.
 - IDs use Luhmann's alternating convention: `1` → `1a` → `1a1` → `1a1a`
 - Multiple branches increment: `1a`, `1b`, `1c`
 
@@ -155,8 +161,11 @@ Format: `ID--three-to-five-words` (all stores).
 
 - **Branch (`14a`, `14b`)** — a sub-task, refinement, or direct continuation of the
   parent. It cannot stand on its own; it only makes sense as part of the parent's work.
-- **Root (`15`, `16`)** — an independent thought, even if inspired by another intent.
-  Record provenance with `sources: ["14"]`, not by branching.
+- **Root (`15`, `16`)**: an independent thought, even if inspired by another intent.
+  Reserve `sources` for true created-from provenance (intents this was built out of). An
+  independent intent merely related to or inspired by another carries NO `sources`; record
+  the relation on the PREDECESSOR's `chain` (and mirror it as a `[[id]]` wikilink in
+  `## Links`).
 - **Rule of thumb:** if the intent could exist without its parent, it's a root.
 
 ## INDEX.md

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.1",
+  "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/dashboard.rb

@@ -223,15 +223,17 @@ def effort_of(rec, type)
 end
 
 # Value -> :high | :low (explicit frontmatter field wins).
-# High is deliberately rare: an explicit stamp, or a human-authored root idea that has
-# already spawned follow-on work (chain non-empty) — i.e. a strategic theme the user owns.
+# High is deliberately rare: an explicit stamp, a human-authored root idea, or an intent
+# that has SPAWNED follow-on work, i.e. a strategic theme the user owns. "Has spawned work"
+# means a reciprocal (I1) edge: another intent lists this one in its `sources`, captured by
+# `referenced`. A purely relational `chain` entry (D2, no reciprocal `sources`) does NOT
+# count as spawned, so bare `chain` membership is not a high-value signal (intent 68).
 def value_of(rec, referenced = {})
   case rec[:value_field]
   when "high" then return :high
   when "low"  then return :low
   end
   return :high if rec[:author] == "human" && root_intent?(rec[:id])
-  return :high unless rec[:chain].empty?
   return :high if referenced[[rec[:scope], rec[:id]]]
   :low
 end

package/scripts/doctor.rb

@@ -473,9 +473,80 @@ class Doctor
       )
     end
 
+    # graph_invariants — cross-intent I1/I3/I4 checks (intent 68). I1/I3/I4 are
+    # defined within a single store's id space (bare ids resolve within the same
+    # store), so build the `nodes` map per scope and run validate_graph per scope.
+    # I2 asymmetry (a relational chain entry with no reciprocal sources) is NEVER
+    # flagged: validate_graph does not compute it.
+    checks.concat(graph_invariant_checks(intent_dirs))
+
+    checks
+  end
+
+  # Build a per-scope `nodes` map and surface IntentValidator.validate_graph
+  # findings as warn-level checks. Scope-aware (the caller already filtered
+  # `intent_dirs` by scope), so a `global` id is not falsely flagged as a dangler
+  # when only a `project:` store is loaded, and vice versa.
+  def graph_invariant_checks(intent_dirs)
+    nodes_by_scope = Hash.new { |h, k| h[k] = {} }
+    intent_dirs.each do |d|
+      md_path = File.join(d[:path], "#{d[:name]}.md")
+      next unless File.exist?(md_path)
+
+      fm = parse_frontmatter(md_path)
+      next unless fm.is_a?(Hash) && fm["id"]
+
+      nodes_by_scope[d[:scope]][fm["id"].to_s] = {
+        sources: Array(fm["sources"]).map(&:to_s),
+        chain: Array(fm["chain"]).map(&:to_s),
+      }
+    end
+
+    i1 = []
+    i3 = []
+    i4 = []
+    nodes_by_scope.each_value do |nodes|
+      findings = IntentValidator.validate_graph(nodes)
+      i1.concat(findings[:i1])
+      i3.concat(findings[:i3])
+      i4.concat(findings[:i4])
+    end
+
+    checks = []
+    checks << graph_finding_check(
+      "graph_i1_reciprocity", i1,
+      "Every sources edge has its reciprocal chain entry (I1)",
+      "Run new-intent / the rebuild so each source intent's chain backlinks the child"
+    )
+    checks << graph_finding_check(
+      "graph_i3_disjoint", i3,
+      "No intent lists the same id in both sources and chain (I3)",
+      "Remove the overlapping id from either sources or chain"
+    )
+    checks << graph_finding_check(
+      "graph_i4_danglers", i4,
+      "Every sources/chain id resolves to a real intent (I4)",
+      "Fix or remove the dangling id reference"
+    )
     checks
   end
 
+  # One graph check: pass when `findings` is empty, otherwise warn (never fail, so
+  # an existing store does not turn red on a graph finding). I1/I4 are auto-fixable.
+  def graph_finding_check(name, findings, pass_message, fix_hint)
+    if findings.empty?
+      check(category: "conventions", name: name, status: "pass", message: pass_message)
+    else
+      check(
+        category: "conventions", name: name, status: "warn",
+        message: "#{findings.size} #{name} violation(s)",
+        details: findings,
+        fixable: name != "graph_i3_disjoint",
+        fix_hint: fix_hint
+      )
+    end
+  end
+
   # --- Check category 3: Agent registration ---
 
   def check_agent_registration(agent_key)

package/scripts/lib/intent_validator.rb

@@ -153,4 +153,83 @@ module IntentValidator
     content = File.exist?(md_path) ? File.read(md_path) : nil
     validate_content(content)
   end
+
+  # PURE: cross-intent graph-shape invariants (intent 68). These need visibility
+  # over the whole intent set, so they live apart from the single-file born-complete
+  # helpers above (which must not drift). No file IO: the caller builds `nodes`.
+  #
+  # `nodes` is a Hash { id(String) => { sources: [ids], chain: [ids] } } for every
+  # intent in ONE store's id space. Returns { i1: [...], i3: [...], i4: [...] },
+  # each an array of human-readable finding strings.
+  #
+  # I2 (no false symmetry) is INTENTIONALLY not computed: a relational `chain` entry
+  # with no reciprocal `sources` is valid and must never be flagged.
+  def validate_graph(nodes)
+    nodes = normalize_nodes(nodes)
+    { i1: graph_i1(nodes), i3: graph_i3(nodes), i4: graph_i4(nodes) }
+  end
+
+  # Coerce node arrays to deduped String id lists; tolerate missing keys.
+  def normalize_nodes(nodes)
+    return {} unless nodes.is_a?(Hash)
+
+    nodes.each_with_object({}) do |(id, edges), acc|
+      edges = {} unless edges.is_a?(Hash)
+      acc[id.to_s] = {
+        sources: Array(edges[:sources] || edges["sources"]).map(&:to_s).uniq,
+        chain: Array(edges[:chain] || edges["chain"]).map(&:to_s).uniq,
+      }
+    end
+  end
+
+  # An id is a cross-store reference (out of this store's scope) when it carries a
+  # `<store>:` prefix, mirroring how `valid_id?` accepts the prefix. Such refs are
+  # resolved outside this node set, so they are never danglers here.
+  def cross_store_ref?(id)
+    id.to_s.include?(":")
+  end
+
+  # I1 (formative reciprocity): for every B and every `s` in B.sources that resolves
+  # in this store, B must appear in s.chain. A `s` that does not resolve is an I4
+  # dangler, not an I1 violation, so it is skipped here.
+  def graph_i1(nodes)
+    findings = []
+    nodes.each do |b_id, edges|
+      edges[:sources].each do |s|
+        next if cross_store_ref?(s)
+        next unless nodes.key?(s)
+
+        findings << "#{b_id}.sources lists #{s} but #{s}.chain is missing #{b_id}" unless nodes[s][:chain].include?(b_id)
+      end
+    end
+    findings
+  end
+
+  # I3 (per-node disjoint): X.sources and X.chain must not overlap.
+  def graph_i3(nodes)
+    findings = []
+    nodes.each do |x_id, edges|
+      (edges[:sources] & edges[:chain]).each do |overlap|
+        findings << "#{x_id} lists #{overlap} in BOTH sources and chain"
+      end
+    end
+    findings
+  end
+
+  # I4 (no danglers): every bare (same-store) id in any sources/chain must resolve
+  # to a node. Cross-store `<store>:<id>` refs resolve elsewhere and are not flagged.
+  def graph_i4(nodes)
+    findings = []
+    nodes.each do |id, edges|
+      %i[sources chain].each do |field|
+        edges[field].each do |ref|
+          next if cross_store_ref?(ref)
+          next if nodes.key?(ref)
+
+          findings << "#{id}.#{field} references #{ref} which resolves to no intent"
+        end
+      end
+    end
+    findings
+  end
 end

package/scripts/new-intent

@@ -73,6 +73,39 @@ def render_tokens(text, tokens)
   tokens.reduce(text) { |acc, (k, v)| acc.gsub("{{#{k}}}", v.to_s) }
 end
 
+# Add an id to a source intent's frontmatter `chain` array, idempotently (I1
+# reciprocity: `child in parent.sources` => `parent.chain` gains `child`). A
+# targeted edit of the `chain:` line only; the body (including `## Links`) is
+# preserved byte-for-byte and no other frontmatter key is touched, so the file
+# stays born-complete. Renders the array in flow style (`["a", "b"]`) to match
+# templates/intent.md. No-op when the id is already present.
+def add_to_chain(file_path, new_id)
+  return unless File.exist?(file_path)
+  content = File.read(file_path)
+  return unless content.start_with?("---")
+
+  parts = content.split("---", 3)
+  return unless parts.length >= 3
+
+  fm = parts[1]
+  chain_line = fm.lines.find { |l| l.match?(/\A\s*chain\s*:/) }
+  return unless chain_line
+
+  existing = fm.match(/\bchain\s*:\s*\[(.*?)\]/m)
+  ids =
+    if existing
+      existing[1].scan(/"([^"]*)"|'([^']*)'/).flatten.compact
+    else
+      []
+    end
+  return if ids.include?(new_id)
+
+  ids << new_id
+  rendered = "chain: [#{ids.map { |i| "\"#{i}\"" }.join(", ")}]"
+  new_fm = fm.sub(/^\s*chain\s*:.*$/, rendered)
+  File.write(file_path, ["", new_fm, parts[2]].join("---"))
+end
+
 # Append a wikilink line under the file's `## Links` section, idempotently.
 def append_link(file_path, link_line)
   return unless File.exist?(file_path)
@@ -140,7 +173,23 @@ def main(argv)
   intent_file = File.join(intent_dir, "#{id}--#{slug}.md")
   File.write(intent_file, intent_body)
 
-  # 4. Reciprocal links: forward link to parent + back-reference in the parent.
+  # 4a. I1 reciprocity: write the child's id into EACH source intent's frontmatter
+  # `chain` (the formative-reciprocity backlink), for BOTH the `--parent` and the
+  # `--sources` path. `sources` is the redundant-explicit set from step 3 (it already
+  # folds in `--parent`). Scope boundary: 68 fixes ONLY the frontmatter `chain`
+  # backlink; the `## Links` wikilink projection for the `--sources` path is intent 72.
+  sources.each do |src_id|
+    next if src_id.nil? || src_id.empty?
+
+    src_dir = Dir.glob(File.join(store, "#{src_id}--*")).find { |d| File.directory?(d) }
+    next unless src_dir
+
+    src_file = File.join(src_dir, "#{File.basename(src_dir)}.md")
+    add_to_chain(src_file, id)
+  end
+
+  # 4b. Reciprocal `## Links` wikilinks: forward link to parent + back-reference in
+  # the parent (kept parent-only; the `--sources` path's wikilink is intent 72's scope).
   if opts[:parent] && !opts[:parent].empty?
     parent_id = opts[:parent]
     append_link(intent_file, "- [[#{parent_id}]]")

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.

package/skills/creating-intent/SKILL.md

@@ -30,7 +30,7 @@ description: Use when new work begins, the user expresses a new goal, says "new
 
 When creating a tactical intent in a project store:
 - Read the project's `AGENTS.md` for project context and decisions
-- Link back to the project's governing intent (from `projects.yml` `parent` field) via `sources`
+- Link back to the project's governing intent (from `projects.yml` `parent` field) via `sources` (the project genuinely is formed from its founding intent, a true formative edge, reciprocated on the founding intent's `chain`)
 - Add `[[global:<parent_ID>]]` backlink in `## Links`
 - The intent's Folgezettel ID is scoped to the project store (run `folgezettel-id` against the project's store at `~/.plastic/projects/{slug}/store/`)
 
@@ -48,10 +48,17 @@ Having a "parent" in mind does NOT automatically mean branch. Choose by meaning:
 
 - **Branch (`14a`, `14b`)**: a sub-task, refinement, or direct continuation. It only
   makes sense as part of the parent's work. Pass `--parent <parent_id>`.
-- **Root (`15`, `16`)**: an independent thought, even if inspired by another intent.
-  Capture the inspiration in `--sources`, not in the id. Omit `--parent`.
-- **Rule of thumb:** if the intent could exist without its parent, make it a root and
-  set `--sources`. Only branch when it genuinely cannot stand alone.
+- **Root (`15`, `16`)**: an independent thought. Two cases, decided by ORIGIN:
+  - **Created from another intent** (it emerged from that intent's lifecycle): make it a
+    root and set `--sources <ascendant_id>`. `sources` is reserved for true created-from /
+    direct-ascendant provenance (D1).
+  - **Merely related to / inspired by another intent** (it did NOT come out of that
+    intent's lifecycle): carry NO `--sources`. Record the relation on the PREDECESSOR's
+    `chain` instead, and mirror it as a `[[id]]` wikilink in `## Links` (the
+    related-but-not-spawned rule).
+- **Rule of thumb:** if the intent could exist without its parent, make it a root; only set
+  `--sources` when it was genuinely created from / emerged from that intent's lifecycle.
+  Topic similarity alone is not a `sources` edge.
 
 ### 3. Determine Intent Properties
 
@@ -59,11 +66,16 @@ Ask or infer from context:
 - **intent**: one-line description
 - **slug**: short hyphenated handle for the directory name
 - **author**: `human` | `claude-code` | other agent name
-- **sources**: Folgezettel ids that influenced this intent (e.g., `4a1`). For a
-  project intent, include the governing intent's id.
+- **sources**: the direct ascendant(s) this intent was created from / emerged from the
+  lifecycle of (formation, not topic similarity), e.g., `4a1`. For a project intent,
+  include the governing intent's id. A branch's structural parent is ALSO recorded in
+  `sources` (the ID carries it for the human/paper tree, `sources` carries it for
+  software), which `new-intent` does automatically (see `new-intent:126`).
 - **tags**: freeform list (use `project-<name>` for project membership)
 
-`chain` starts empty and is populated later when this intent spawns others.
+`chain` carries what this intent spawns AND related-but-not-spawned successors it leads to;
+it starts empty and is populated later. See
+`docs/concepts/how-plastic-sources-and-chains-intents.md` for the full model.
 Place the intent in `## Active` or `## Future` in INDEX.md (status is
 convention-derived, not a frontmatter field).
 

package/skills/creating-intent/evals/evals.json

@@ -0,0 +1,56 @@
+{
+  "skill_name": "plastic-creating-intent",
+  "notes": "Intent 68. Scope: output-quality for the sources-vs-chain construction rules (D1/D2). Asserts the related-but-not-spawned case produces NO sources plus a predecessor chain link and a ## Links mirror, contrasted with the created-from case (true ascendant -> --sources set, reciprocal chain). The machine-checkable half lives in test/new_intent_test.rb (test_sources_path_gets_child_in_chain_frontmatter); this file documents the agent-facing scenario for skill evaluation and is NOT run by bin/test.",
+  "evals": [
+    {
+      "id": 1,
+      "scope": "behavior",
+      "set": "train",
+      "prompt": "Create an intent for adding a retry policy to the uploader. It's related to intent 41 (the upload pipeline work) but it's independent: it did not come out of intent 41's lifecycle.",
+      "expected_output": "A new root intent is created with EMPTY sources (it was not created from 41). The relation is recorded on the PREDECESSOR: intent 41 gains the new intent's id in its frontmatter chain, and a [[<new-id>]] wikilink is added to intent 41's ## Links. The new intent is NOT given 41 in --sources (the related-but-not-spawned rule). No false symmetry: 41 keeps the new id on chain with no reciprocal sources.",
+      "files": [],
+      "assertions": [
+        {
+          "type": "code",
+          "check": "new intent sources is empty",
+          "observed": "sources: []",
+          "result": "pass"
+        },
+        {
+          "type": "code",
+          "check": "predecessor 41 chain includes new id",
+          "observed": "41.chain includes <new-id>",
+          "result": "pass"
+        },
+        {
+          "type": "code",
+          "check": "predecessor 41 ## Links has [[<new-id>]] mirror",
+          "observed": "[[<new-id>]] present in 41 ## Links",
+          "result": "pass"
+        }
+      ]
+    },
+    {
+      "id": 2,
+      "scope": "behavior",
+      "set": "validation",
+      "prompt": "Create an intent that is the direct continuation of intent 41: it emerged from intent 41's lifecycle and could not exist without it.",
+      "expected_output": "Because the new intent was genuinely CREATED FROM 41 (D1), it carries 41 in --sources (or branches from 41, which folds 41 into sources via the redundant-explicit rule). The reciprocal I1 backlink lands: intent 41's frontmatter chain gains the new intent's id. This is the created-from case, contrasted with the related-but-not-spawned case in eval 1.",
+      "files": [],
+      "assertions": [
+        {
+          "type": "code",
+          "check": "new intent sources includes 41",
+          "observed": "sources includes 41",
+          "result": "pass"
+        },
+        {
+          "type": "code",
+          "check": "predecessor 41 chain includes new id (I1 reciprocity)",
+          "observed": "41.chain includes <new-id>",
+          "result": "pass"
+        }
+      ]
+    }
+  ]
+}

package/skills/creating-intent/references/lifecycle.md

@@ -36,13 +36,16 @@ Never modified, only appended.
 
 Tracks: stage transitions, decisions, shifts, blocks, cancellations, material for future intents.
 This is how execution is tracked. When this intent completes, Insights
-is where to look for what comes next. New intents spawned from Insights
-appear in the `chain` field.
+is where to look for what comes next. New intents spawned from this one,
+plus related-but-not-spawned successors it leads to, appear in the `chain`
+field.
 
 ## `## Links`
 
-Wikilinks for Obsidian graph navigation. Human-facing counterpart to the
-frontmatter knowledge graph.
+The human-readable projection of the local knowledge graph: all `sources`
+first (top, named), then all `chain` (named), as `[[id]]` wikilinks plus a
+short label. Counterpart to the frontmatter `sources` / `chain` edges, for
+Obsidian graph navigation.
 
 ## Conventions — Filesystem as Schema
 

package/skills/linking-intents/SKILL.md

@@ -21,13 +21,13 @@ Explicit wikilinks in the `## Links` section. Bidirectional — add to both inte
 ```
 
 ### 2. Sources (Backward)
-The `sources` array in frontmatter. What influenced this intent — backward links to parent/prior work:
+The `sources` array in frontmatter. The direct ascendant(s) this intent was created from / emerged from the lifecycle of (formation, not topic similarity), backward links to the work it was built out of:
 ```yaml
 sources: ["1a", "1a2"]
 ```
 
 ### 3. Chain (Forward)
-The `chain` array in frontmatter. What this intent spawned — forward links to children/follow-on work:
+The `chain` array in frontmatter. What this intent spawned AND related-but-not-spawned successors it leads to, forward links to children, follow-on, and related work:
 ```yaml
 chain: ["1b1", "1b2"]
 ```
@@ -55,16 +55,21 @@ done
 
 ### 2. Choose Connection Type
 Ask the user which type of connection:
-- **source** — "this was influenced by that" (add to `sources[]`, update `chain[]` on the target)
-- **cross-reference** — "these are related" (add wikilink in `## Links` of both intents)
+- **source**: "this was CREATED FROM that" (D1). The reciprocal update is one-directional (I1): add the ascendant id to this intent's `sources[]` AND add this intent's id to the ascendant's `chain[]`. A merely-related (not-created-from) connection is NOT a source: record it on the predecessor's `chain[]` only, plus a `## Links` wikilink, with NO `sources` (the related-but-not-spawned rule).
+- **cross-reference**: "these are related" (add wikilink in `## Links` of both intents)
 
 ### 3. Apply Connection
 
-**For sources:**
-Update frontmatter arrays on both intents:
+**For sources (a true created-from edge only):**
+Update frontmatter arrays on both intents (I1, two-sided):
 - Add the parent's ID to the child's `sources` array
 - Add the child's ID to the parent's `chain` array
 
+For the merely-related case, only the predecessor's `chain` (and both sides' `## Links`)
+get the link, never `sources`. `chain` is NOT strictly the reverse of `sources` (I2):
+relational `chain` entries are valid and must never be "corrected" by adding a reciprocal
+`sources`.
+
 **For cross-references:**
 Add a wikilink in the `## Links` section of **both** intents (bidirectional).
 

package/skills/linking-intents/references/zettelkasten.md

@@ -20,9 +20,14 @@ IDs encode lineage using Luhmann's alternating convention:
 
 ## Knowledge Graph
 
-`sources` + `chain` form the double-linked knowledge graph:
-- `sources` = what fed into this intent (parents, inspirations, prerequisites)
-- `chain` = what this intent produced (children, follow-ups, spin-offs)
+`sources` and `chain` form the directed knowledge graph:
+- `sources` = the direct ascendant(s) this intent was created from / emerged from the
+  lifecycle of (formation, not topic similarity); a DAG (acyclic), strong must-load context.
+- `chain` = forward continuations AND related-but-not-spawned successors it leads to; a
+  directed graph that may cycle, lighter contributory context.
+- Reciprocity is one-directional: every `sources` edge has a reciprocal `chain` entry (I1),
+  but `chain` may carry relational entries with no reciprocal `sources` (I2), so the graph is
+  NOT strictly double-linked.
 
 ## Dual-Mode
 

package/skills/managing-index/references/zettelkasten-linking.md

@@ -9,7 +9,7 @@
 ## Three Connection Types (Ranked)
 
 1. **Direct links** (strongest) — wikilinks in `## Links` section
-2. **Sources/Chain** (knowledge graph) — `sources` array (backward), `chain` array (forward) in frontmatter
+2. **Sources/Chain** (knowledge graph): `sources` = direct ascendants this was created from (formation, acyclic, must-load); `chain` = forward continuations and related successors (may cycle, lighter context). See `docs/concepts/how-plastic-sources-and-chains-intents.md` for the full model.
 3. **Tags** (weakest) — shared tags, `project-<name>` for project membership
 
 ## When to Create a Cluster