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

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/package.json

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

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/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