@zalom/plastic 1.0.0-beta.13 → 1.0.0-beta.15

package/PLASTIC.md

@@ -79,10 +79,29 @@ The connection: an intent's `## Insights` feeds the Coordinator's Observe phase.
 | **How** | Planning | `plan.md` + `actions/` + `checklist.md` | `plastic-writing-plans` |
 | **Exec** | Execution | `outcome.md` | `plastic-executing-plan` |
 
-`## Insights` — append-only work log captured throughout ALL stages. **Append-only means
-newest entry at the bottom; never prepend.** This ordering is a hard convention: Insights
-are the semantic trace of an intent, and a consistent newest-last order keeps that trace
-readable across every intent.
+`## Insights` is the append-only log of durable discoveries captured throughout ALL stages.
+An insight is a discovery worth keeping for later reads: novel, or old but newly relevant,
+surfaced at any stage (What, Why, How, Exec). It is the most interesting residue of an
+intent, the part a future reader most wants. **Append-only means newest entry at the bottom;
+never prepend.** This ordering is a hard convention: Insights are the semantic trace of an
+intent, and a consistent newest-last order keeps that trace readable across every intent.
+
+Every entry leads with a fixed, machine-parseable prefix `{utc-iso8601} · {stage} · {author}`,
+for example `2026-06-24T08:13:05Z · Why · plastic-brainstorming (autonomous)`. The UTC ISO8601
+timestamp (to the second, trailing `Z`) is the same convention the savepoint ledger uses, so
+the store has one timestamp convention. This per-entry prefix is not prepending the entry:
+entries stay append-only, newest at the bottom; the prefix only stamps each line with when,
+which stage, and who.
+
+The blessed write path is the `insight-append` helper
+(`scripts/insight-append <intent_dir> <text> --stage S --author A`), which formats the prefix,
+validates it, and appends at the bottom. Hand-editing `## Insights` is an escape hatch; the
+helper is the default so the format cannot drift.
+
+Background sessions and dispatched sub-agents do not write the insight themselves. They carry
+each nugget home in the completion report's `insights:` field, and the orchestrator (or any
+agent that can write the file) persists it via the helper. A session that cannot write the
+intent file still returns its report, so the insight survives.
 For full lifecycle detail, the skills in the Detail column have references/.
 
 `savepoint.md` — a deterministic, append-only ledger of cycle-step milestones (one line per

package/agents/plastic-brainstorming.md

@@ -31,7 +31,7 @@ When dispatched in auto mode you receive the standard Plastic spawn preamble (fr
 
 ## 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:
+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, insights) plus the brainstorming payload:
 
 - Decisions recorded in `### Decisions`, each with its one-line rationale
 - Context enriched: what was researched and the key findings

package/agents/plastic-executor.md

@@ -18,7 +18,7 @@ When dispatched in auto mode you receive the standard Plastic spawn preamble (fr
 
 1. **Implement the actions** — make the code changes for each action in order
 2. **Track progress** — check off `checklist.md` items as they complete
-3. **Record insights** — append observations to `## Insights` with the `(autonomous)` marker
+3. **Record insights** — capture durable discoveries and report them in the `insights:` field; persist each to `## Insights` via the `insight-append` helper (`scripts/insight-append <intent_dir> <text> --stage Exec --author "plastic-executor (autonomous)"`), the blessed write path that stamps the `{utc-iso8601} · {stage} · {author}` prefix
 4. **Prove it green** — run the full test suite and reach zero failures before reporting done
 
 ## How You Work
@@ -32,7 +32,7 @@ When dispatched in auto mode you receive the standard Plastic spawn preamble (fr
 
 ## 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:
+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, insights) 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)

package/agents/plastic-planner.md

@@ -31,7 +31,7 @@ When dispatched in auto mode you receive the standard Plastic spawn preamble (fr
 
 ## 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:
+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, insights) 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

package/agents/plastic-spec-specialist.md

@@ -31,7 +31,7 @@ When dispatched in auto mode you receive the standard Plastic spawn preamble (fr
 
 ## 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:
+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, insights) 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

package/package.json

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

package/scripts/agent-report

@@ -108,6 +108,26 @@ def outcome_line(intent_dir)
   "(no outcome yet)"
 end
 
+# The insights line: the LAST line of the intent file's `## Insights` section
+# (the newest nugget, since entries are append-only newest-at-bottom), else
+# `(none)`. Pure read of the intent dir, no clock.
+def insights_line(intent_dir)
+  ifile = Bridge.intent_file(intent_dir)
+  return "(none)" unless File.exist?(ifile)
+
+  lines = File.read(ifile).split("\n", -1)
+  idx = lines.index { |l| l.strip == "## Insights" }
+  return "(none)" if idx.nil?
+
+  last = nil
+  (idx + 1).upto(lines.length - 1) do |i|
+    break if lines[i].start_with?("## ")
+
+    last = lines[i] unless lines[i].strip.empty?
+  end
+  last || "(none)"
+end
+
 intent_dir_arg, role = parse_args(ARGV)
 
 if intent_dir_arg.nil? || intent_dir_arg.empty?
@@ -137,6 +157,7 @@ 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 << "Insights: #{insights_line(intent_dir)}"
 lines << "=== end report ==="
 
 puts lines.join("\n")

package/scripts/insight-append

@@ -0,0 +1,51 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# insight-append - the blessed write path for an intent's `## Insights` section
+# (intent 82). A thin CLI wrapper over Insights.append_insight: it formats the
+# `{utc-iso8601} · {stage} · {author}` prefix, validates it, and appends one
+# entry at the bottom of the section (creating the section or file if absent).
+#
+# Sibling to scripts/spawn-preamble and scripts/agent-report. The library's
+# `now:` seam is the test seam; the CLI uses the default Time.now, which is fine
+# because determinism is covered at the library level (test/insights_test.rb).
+#
+# Usage:
+#   insight-append <intent_dir> <text> --stage S --author A
+#
+# Exit codes: 0 (entry appended), 2 (usage).
+
+require_relative "lib/insights"
+
+def parse_args(argv)
+  stage = nil
+  author = nil
+  positional = []
+  i = 0
+  while i < argv.length
+    case argv[i]
+    when "--stage"
+      stage = argv[i + 1]
+      i += 2
+    when "--author"
+      author = argv[i + 1]
+      i += 2
+    else
+      positional << argv[i]
+      i += 1
+    end
+  end
+  [positional[0], positional[1], stage, author]
+end
+
+intent_dir, text, stage, author = parse_args(ARGV)
+
+if [intent_dir, text, stage, author].any? { |v| v.nil? || v.to_s.empty? }
+  warn "usage: insight-append <intent_dir> <text> --stage S --author A"
+  exit 2
+end
+
+entry = Insights.append_insight(File.expand_path(intent_dir), text,
+                                stage: stage, author: author)
+puts "appended: #{entry}"

package/scripts/lib/insights.rb

@@ -0,0 +1,86 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+
+# insights.rb - the blessed write path for an intent's `## Insights` section
+# (intent 82). A sibling library to bridge.rb so the insight write path stays
+# independent of the savepoint ledger (the spec forbids touching the ledger).
+#
+# Every entry leads with a fixed, machine-parseable prefix
+# `{utc-iso8601} · {stage} · {author}` where the timestamp is `now.utc.iso8601`,
+# the SAME convention `Bridge.append_savepoint_line` uses, so the store has one
+# timestamp convention across both ledgers. Entries are append-only, newest at
+# the BOTTOM (the [[34]] ordering law): the per-entry prefix is not prepending
+# the entry, and existing entries are never reordered.
+
+require "time"
+require_relative "bridge"
+
+module Insights
+  HEADING = "## Insights"
+  # The middle dot (U+00B7) with a single space on each side separates the
+  # timestamp, stage, and author fields.
+  SEPARATOR = " · "
+  # A well-formed prefix: UTC ISO8601 timestamp to the second with a trailing
+  # `Z`, then a non-empty stage, then a non-empty author, each ` · `-separated.
+  PREFIX_RE = /\A\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z · [^·]+ · [^·]+/.freeze
+
+  # Append one insight entry at the BOTTOM of the `## Insights` section of the
+  # intent file, creating the section (or the file) if absent. `now:` is the DI
+  # seam: defaults to Time.now, tests inject Time.utc(...). Raises ArgumentError
+  # if the assembled prefix is not well-formed (guard on write).
+  def self.append_insight(intent_dir, text, stage:, author:, now: Time.now)
+    prefix = "#{now.utc.iso8601}#{SEPARATOR}#{stage}#{SEPARATOR}#{author}"
+    unless valid_insight_prefix?(prefix)
+      raise ArgumentError, "malformed insight prefix: #{prefix.inspect}"
+    end
+
+    entry = "#{prefix} — #{text}"
+    path = Bridge.intent_file(intent_dir)
+    File.write(path, with_entry(File.exist?(path) ? File.read(path) : "", entry))
+    entry
+  end
+
+  # Pure validator: true when `line` begins with a well-formed prefix. No IO,
+  # no clock. Rejects a date-only prefix, a missing separator, a missing `Z`,
+  # and sub-second precision.
+  def self.valid_insight_prefix?(line)
+    line.is_a?(String) && line.match?(PREFIX_RE)
+  end
+
+  # Insert `entry` at the bottom of the `## Insights` section of `content`,
+  # preserving every existing line and their order. Pure string transform.
+  def self.with_entry(content, entry)
+    lines = content.empty? ? [] : content.split("\n", -1)
+    heading_idx = lines.index { |l| l.strip == HEADING }
+    return append_new_section(lines, entry) if heading_idx.nil?
+
+    insert_at = section_end(lines, heading_idx)
+    lines.insert(insert_at, entry)
+    lines.join("\n")
+  end
+
+  # The insertion index for a new entry: just after the last non-empty content
+  # line that belongs to the `## Insights` section (before the next `## `
+  # heading or EOF).
+  def self.section_end(lines, heading_idx)
+    last_content = heading_idx
+    idx = heading_idx + 1
+    while idx < lines.length
+      break if lines[idx].start_with?("## ")
+
+      last_content = idx unless lines[idx].strip.empty?
+      idx += 1
+    end
+    last_content + 1
+  end
+
+  # Append a fresh `## Insights` section (blank line, heading, entry) to the end
+  # of the existing content.
+  def self.append_new_section(lines, entry)
+    body = lines.join("\n")
+    body = body.sub(/\n+\z/, "") unless body.empty?
+    pieces = body.empty? ? [] : [body, ""]
+    pieces << HEADING << entry
+    "#{pieces.join("\n")}\n"
+  end
+end

package/scripts/lib/installer_core.rb

@@ -213,6 +213,7 @@ class InstallerCore
       "scripts/lib/retrieval_gate.rb" => "scripts/lib/retrieval_gate.rb",
       "scripts/hook-auto-arm" => "scripts/hook-auto-arm",
       "scripts/lib/bridge.rb" => "scripts/lib/bridge.rb",
+      "scripts/lib/insights.rb" => "scripts/lib/insights.rb",
       "scripts/lib/worktree.rb" => "scripts/lib/worktree.rb",
       "scripts/lib/boot_banner.rb" => "scripts/lib/boot_banner.rb",
       "scripts/lib/qmd_sync.rb" => "scripts/lib/qmd_sync.rb",
@@ -222,6 +223,8 @@ class InstallerCore
       "scripts/lib/frontmatter_writer.rb" => "scripts/lib/frontmatter_writer.rb",
       "scripts/lib/links_projection.rb" => "scripts/lib/links_projection.rb",
       "scripts/lib/links_section.rb" => "scripts/lib/links_section.rb",
+      "scripts/project-links" => "scripts/project-links",
+      "scripts/rebuild-graph" => "scripts/rebuild-graph",
       "scripts/validate-intent" => "scripts/validate-intent",
       "scripts/new-intent" => "scripts/new-intent",
       "scripts/hook-create-gate" => "scripts/hook-create-gate",

package/scripts/lib/retrieval_gate.rb

@@ -36,7 +36,7 @@ module RetrievalGate
   SERENA_EXTENSIONS = %w[
     rb js jsx ts tsx mjs cjs py go rs java kt scala c h cpp hpp cc
     cs php rb swift sh bash zsh lua ex exs erl clj sql
-    json yaml yml toml md markdown
+    json yaml yml toml
   ].freeze
 
   # Image / binary extensions that are always allowed (plain read is fine).

package/scripts/spawn-preamble

@@ -41,10 +41,16 @@ REPORT_CONTRACT =
   "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 " \
+  "checklist deltas, deviations from spec, blockers or handoff notes, and an " \
+  "insights field carrying 0..N durable nuggets (what I discovered worth keeping, " \
+  "the most interesting residue of this turn; none if there were none); 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). Keep the " \
-  "report prose-stripped: the envelope and payload only, no greeting, no preamble, " \
+  "(for example the planner explains the plan back to the orchestrator). Populate " \
+  "the insights field even when you cannot write the intent file yourself: a " \
+  "background or dispatched agent carries each nugget home in the report and the " \
+  "orchestrator persists it via scripts/insight-append, so an insight never " \
+  "depends on the discovering session's file-write access. Keep the report " \
+  "prose-stripped: the envelope and payload only, no greeting, no preamble, " \
   "no end-recap, no restating of the task; reasoning stays in the thinking channel. " \
   "See skills/auto/references/agent-report-contract.md for the per-role format."
 

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

@@ -39,6 +39,11 @@ Every role report, whatever the stage, carries these fields:
 - **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`.
+- **Insights**: 0..N durable nuggets discovered this turn (the most interesting residue),
+  each one a `## Insights`-worthy line; `none` if there were none. Background and dispatched
+  agents MUST populate this: they carry each nugget home in the report and the orchestrator
+  persists it (see Insights delivery below), so an insight never depends on the discovering
+  session having file-write access.
 
 ## Per-role payload
 
@@ -49,11 +54,13 @@ D2). The payload is what makes the report useful to the orchestrator beyond the
 - 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.
+- Insights: durable discoveries from the Why exploration, reported in the `insights:` field.
 
 ### 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.
+- Insights: durable discoveries from consolidating the spec, reported in the `insights:` field.
 
 ### planner (How): worked exemplar
 The planner report EXPLAINS THE PLAN BACK TO THE ORCHESTRATOR. It carries:
@@ -62,17 +69,20 @@ The planner report EXPLAINS THE PLAN BACK TO THE ORCHESTRATOR. It carries:
 - 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.
+- Insights: durable discoveries from planning, reported in the `insights:` field.
 
 ### 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.
+- Insights reported in the `insights:` field (each with the `(autonomous)` marker); the
+  executor or the orchestrator persists them to `## Insights` via the `insight-append` helper.
 
 ### 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.
+- Insights: durable discoveries from the review, reported in the `insights:` field.
 
 ## Fallback: always a report
 
@@ -92,3 +102,20 @@ ledger, the lifecycle artifacts present, the checklist checked / total, and the
 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.
+
+## Insights delivery
+
+Insights ride home in the completion report. Every agent reports its durable nuggets in the
+`insights:` field; the orchestrator (or any agent that can write the intent file) then persists
+each one via the helper:
+
+```
+scripts/insight-append <intent_dir> <text> --stage S --author A
+```
+
+The helper formats the `{utc-iso8601} · {stage} · {author}` prefix (the same timestamp
+convention as the savepoint ledger), validates it, and appends the entry at the bottom of the
+`## Insights` section, newest last. This is the fix for dropped background and sub-agent
+insights: a session that cannot write the intent file still returns its report, so the insight
+survives and the orchestrator writes it on receipt. Hand-editing `## Insights` is an escape
+hatch; the helper is the default so the prefix format cannot drift.