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

package/skills/auto/evals/evals.json

@@ -202,6 +202,54 @@
           "result": "pass"
         }
       ]
+    },
+    {
+      "id": 12,
+      "scope": "behavior",
+      "set": "validation",
+      "prompt": "A power-tool is present (qmd on PATH, or a .serena marker / serena on PATH). A substantive prompt arrives in auto mode.",
+      "expected_output": "The UserPromptSubmit power-tools hook appends a MANDATORY obligation per present tool: a MUST-use-QMD line when qmd is present (to check for an existing or related intent before treating work as new), and a MUST-use-Serena line when serena is present (symbolic tools before grep/Read). QMD hits are still injected when above threshold.",
+      "files": [],
+      "assertions": [
+        {
+          "type": "code",
+          "check": "PowerTools.mandate returns MUST/MANDATORY lines for each present tool; QmdHook.run appends the mandate",
+          "observed": "power_tools_test.rb + qmd_hook_test.rb assert MUST wording; serena line gated on the serena detector",
+          "result": "pass"
+        }
+      ]
+    },
+    {
+      "id": 13,
+      "scope": "behavior",
+      "set": "validation",
+      "prompt": "Neither qmd nor serena is present (no qmd on PATH, no .serena marker, no serena on PATH). A substantive prompt arrives.",
+      "expected_output": "Detect-then-degrade: the hook emits nothing (silent no-op, exit 0). No mandate text appears. Nothing is required to install.",
+      "files": [],
+      "assertions": [
+        {
+          "type": "code",
+          "check": "PowerTools.mandate returns nil and QmdHook.run returns nil when neither tool is present",
+          "observed": "power_tools_test.rb test_mandate_neither_is_nil + qmd_hook_test.rb test_nil_when_neither_tool_present",
+          "result": "pass"
+        }
+      ]
+    },
+    {
+      "id": 14,
+      "scope": "behavior",
+      "set": "validation",
+      "prompt": "QMD is present. In auto mode the user says: deliver the work on the uploader retry policy (no intent id given).",
+      "expected_output": "Before scanning the store with grep/Read to find the matching intent, runs `ruby ~/.plastic/scripts/qmd-sync search \"uploader retry policy\"` to surface the candidate intent, then opens the authoritative intent file for the hit it takes over. This discovery step is distinct from the completion-time reindex step. No-op fallback to INDEX.md / file scan when QMD is absent.",
+      "files": [],
+      "assertions": [
+        {
+          "type": "human",
+          "check": "qmd-sync search is run before grep/Read during discovery; authoritative file opened for the hit; reindex step stays separate",
+          "observed": "SKILL.md (or agent file) carries the QMD-first step: run qmd-sync search before grep/Read, then open the authoritative file; no-op fallback when QMD is absent",
+          "result": "pass"
+        }
+      ]
     }
   ]
 }

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/brainstorming/SKILL.md

@@ -74,6 +74,7 @@ digraph brainstorming {
 ## The Process
 
 **Understanding the idea:**
+- QMD-first (when available): before scanning the store with grep/Read for prior decisions, specs, or outcomes, run `ruby ~/.plastic/scripts/qmd-sync search "<terms>"` to surface candidate, prior, or related intents, then open the authoritative intent file for any hit you act on. The command is a no-op when QMD is absent, so fall back to the existing INDEX.md / file scan.
 - Check out the current project state first (files, docs, recent commits)
 - Before asking detailed questions, assess scope: if the request describes multiple independent subsystems (e.g., "build a platform with chat, file storage, billing, and analytics"), flag this immediately. Don't spend questions refining details of a project that needs to be decomposed first.
 - If the project is too large for a single spec, help the user decompose into sub-projects: what are the independent pieces, how do they relate, what order should they be built? Then brainstorm the first sub-project through the normal design flow. Each sub-project gets its own spec → plan → implementation cycle.

package/skills/brainstorming/evals/evals.json

@@ -0,0 +1,22 @@
+{
+  "skill_name": "plastic-brainstorming",
+  "notes": "Intent 66a. Spec for the QMD-first step in the Why/explore-context phase (surface prior decisions/specs/outcomes before grep/Read). Runner is intent 76; spec only.",
+  "evals": [
+    {
+      "id": 1,
+      "scope": "behavior",
+      "set": "validation",
+      "prompt": "QMD is present. Brainstorming the active intent during the Why phase, the agent needs prior decisions and specs on caching.",
+      "expected_output": "In the explore-project-context (Why) step, before scanning the store with grep/Read, runs `ruby ~/.plastic/scripts/qmd-sync search \"caching decisions\"` to surface prior decisions, specs, or outcomes, then opens the authoritative intent file for any hit it acts on. No-op fallback to INDEX.md / file scan when QMD is absent.",
+      "files": [],
+      "assertions": [
+        {
+          "type": "human",
+          "check": "qmd-sync search is run during Why before grep/Read; authoritative file opened for any hit",
+          "observed": "SKILL.md (or agent file) carries the QMD-first step: run qmd-sync search before grep/Read, then open the authoritative file; no-op fallback when QMD is absent",
+          "result": "pass"
+        }
+      ]
+    }
+  ]
+}

package/skills/continuing/SKILL.md

@@ -54,7 +54,14 @@ intents. Do not start executing work. The branches below are the only follow-ups
 ## Conditional Ledger-Resume
 
 Fires ONLY when the user explicitly asks to continue a SPECIFIC intent, or an agent is
-instructed to continue one. It is not part of every boot. For that intent's directory:
+instructed to continue one. It is not part of every boot.
+
+QMD-first (when available): when the user names the intent by description rather than id, before
+scanning the store with grep/Read run `ruby ~/.plastic/scripts/qmd-sync search "<terms>"` to
+surface the candidate intent, then open the authoritative intent file for the hit you resume. The
+command is a no-op when QMD is absent, so fall back to the existing INDEX.md / file scan.
+
+For that intent's directory:
 
 1. **Read `savepoint.md`.** It is a deterministic, append-only stage ledger (one line per
    milestone, newest at the bottom): `{utc-iso8601}  {Stage}  {milestone}`. The **last line =

package/skills/continuing/evals/evals.json

@@ -131,6 +131,15 @@
       "assertions": [
         { "type": "convention", "check": "Determine Store step 2 documents local/project store detection via projects.yml + CWD match", "observed": "filled", "result": "pass" }
       ]
+    },
+    {
+      "id": 15, "scope": "behavior", "set": "validation",
+      "prompt": "QMD is present. The user says: continue the work on the statusline coloring (names the intent by description, not id).",
+      "expected_output": "Before scanning the store with grep/Read to locate the named intent, runs `ruby ~/.plastic/scripts/qmd-sync search \"statusline coloring\"` to surface the candidate intent, then opens the authoritative intent file for the hit it resumes. No-op fallback to INDEX.md / file scan when QMD is absent.",
+      "files": ["skills/continuing/SKILL.md"],
+      "assertions": [
+        { "type": "human", "check": "qmd-sync search is run before grep/Read when the intent is named by description; authoritative file opened for the hit", "observed": "Conditional Ledger-Resume carries the QMD-first step: run qmd-sync search before grep/Read, then open the authoritative file; no-op fallback when QMD is absent", "result": "pass" }
+      ]
     }
   ]
 }

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/`)
 
@@ -41,6 +41,14 @@ When creating a tactical intent in a project store:
 - **Global:** `~/.plastic/store/`
 - **Project:** `~/.plastic/projects/{slug}/store/`
 
+### 1b. Check for a Duplicate or Predecessor (QMD-first)
+
+QMD-first (when available): before scanning the store with grep/Read, run
+`ruby ~/.plastic/scripts/qmd-sync search "<terms>"` to surface candidate, prior, or duplicate
+intents, then open the authoritative intent file for any hit you act on. The command is a no-op
+when QMD is absent, so fall back to the existing INDEX.md / file scan. Do this before allocating
+the id so a near-duplicate can be reused and a true predecessor can be set in `--sources`.
+
 ### 2. Decide Branch vs Root
 
 Decide this BEFORE scaffolding, because it sets whether you pass `--parent`.
@@ -48,10 +56,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 +74,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,72 @@
+{
+  "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"
+        }
+      ]
+    },
+    {
+      "id": 3,
+      "scope": "behavior",
+      "set": "validation",
+      "prompt": "QMD is present. The user says: create an intent to add retry to the uploader.",
+      "expected_output": "Before allocating the id / scaffolding, runs `ruby ~/.plastic/scripts/qmd-sync search \"add retry to the uploader\"` to surface a near-duplicate or true predecessor, then opens the authoritative intent file for any hit (reusing a near-duplicate or setting a real predecessor in --sources). No-op fallback to INDEX.md / file scan when QMD is absent.",
+      "files": [],
+      "assertions": [
+        {
+          "type": "human",
+          "check": "qmd-sync search is run before id allocation; authoritative file opened for any hit; informs reuse / --sources",
+          "observed": "SKILL.md (or agent file) carries the QMD-first step: run qmd-sync search before grep/Read, then open the authoritative file; no-op fallback when QMD is absent",
+          "result": "pass"
+        }
+      ]
+    }
+  ]
+}

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

@@ -36,13 +36,21 @@ 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, mirroring the
+frontmatter exactly. Each entry is `- [[id--slug|<target's full intent: text>]]`,
+a clickable `id--slug` wikilink target with the target intent's full `intent:`
+text as the label (cross-store targets render
+`- [[store:id--slug|<target's full intent: text>]]`). Ordering is mandatory: all
+`sources` first (top), then all `chain`, frontmatter order preserved within each
+group. Sources never appear at the end. No source/chain tags, no sub-grouping. An
+intent with empty `sources` and `chain` carries the empty-state comment. Counterpart
+to the frontmatter `sources` / `chain` edges, for Obsidian graph navigation.
 
 ## Conventions — Filesystem as Schema
 

package/skills/dashboard/SKILL.md

@@ -67,6 +67,11 @@ instead of showing it.
 
 ### Step 4 — Entry flow (the board is the menu)
 
+QMD-first (when available): when the user navigates by describing an intent rather than giving its
+id, before scanning the store with grep/Read run `ruby ~/.plastic/scripts/qmd-sync search "<terms>"`
+to surface the candidate intent, then open the authoritative intent file for the hit. The command is
+a no-op when QMD is absent, so fall back to the existing INDEX.md / file scan.
+
 The board lists everything; the user navigates by free prose (no capped picker):
 - On the **global** board, the user replies with an **intent id** (work it), a **project
   name** (re-run `project <slug> --data` and present that board), or **"new"** (start a new

package/skills/dashboard/evals/evals.json

@@ -0,0 +1,22 @@
+{
+  "skill_name": "plastic-dashboard",
+  "notes": "Intent 66a. Spec for the QMD-first step in the entry flow (resolve a free-prose intent reference before grep/Read). Runner is intent 76; spec only.",
+  "evals": [
+    {
+      "id": 1,
+      "scope": "behavior",
+      "set": "validation",
+      "prompt": "QMD is present. On the board, the user navigates by describing an intent (the search verb work) instead of giving its id.",
+      "expected_output": "Before scanning the store with grep/Read to resolve the free-prose reference, runs `ruby ~/.plastic/scripts/qmd-sync search \"search verb\"` to surface the candidate intent, then opens the authoritative intent file for the hit. No-op fallback to INDEX.md / file scan when QMD is absent.",
+      "files": [],
+      "assertions": [
+        {
+          "type": "human",
+          "check": "qmd-sync search is run before grep/Read when the user navigates by description; authoritative file opened for the hit",
+          "observed": "SKILL.md (or agent file) carries the QMD-first step: run qmd-sync search before grep/Read, then open the authoritative file; no-op fallback when QMD is absent",
+          "result": "pass"
+        }
+      ]
+    }
+  ]
+}

package/skills/executing-plan/SKILL.md

@@ -75,7 +75,7 @@ Capture observations in `## Insights`. When ALL checklist items are checked:
 3. Move intent from `## Active` to `## Completed` in INDEX.md (with today's date)
 4. Update cluster entries to show `_(completed)_`
 5. Auto-commit: `cd <store-root> && git add . && git commit -m "feat: complete intent <ID> — <name>"`
-6. Refresh the QMD search index for this store (optional, no-op when QMD is absent): `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root>`. Delivery is the lifecycle event that keeps the search index fresh.
+6. On completion, ALWAYS refresh the QMD search index for this store (no-op when QMD is absent), running in the background so it never blocks the turn: `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root> --async`. Completion is the lifecycle event that keeps the search index fresh.
 
 **This is NOT optional.** An intent with all checklist items done but no Outcome is a broken state. Complete the intent immediately — do not leave it for later.
 
@@ -101,7 +101,7 @@ Capture observations in `## Insights`. When ALL checklist items are checked:
 3. Move intent from `## Active` to `## Completed` in INDEX.md (with today's date)
 4. Update cluster entries to show `_(completed)_`
 5. Auto-commit: `cd <store-root> && git add . && git commit -m "feat: complete intent <ID> — <name>"`
-6. Refresh the QMD search index for this store (optional, no-op when QMD is absent): `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root>`. Delivery is the lifecycle event that keeps the search index fresh.
+6. On completion, ALWAYS refresh the QMD search index for this store (no-op when QMD is absent), running in the background so it never blocks the turn: `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root> --async`. Completion is the lifecycle event that keeps the search index fresh.
 
 **This is NOT optional.** Complete the intent immediately when work is done.
 

package/skills/intent-curator/SKILL.md

@@ -33,9 +33,11 @@ Invoke the `plastic-intent-curator` agent via the Agent tool with `subagent_type
 
 The agent handles:
 - Intent lifecycle management (status transitions, Outcome sections)
-- INDEX.md maintenance (Active/Future/Clusters/Completed sections)
+- INDEX.md maintenance (Active/Future/Clusters/Completed/Abandoned sections)
 - Link discovery between related intents
 - Cluster management (create, merge, rename)
 - Orphan detection
 
+When an intent reaches a terminal state — moved to Completed OR Abandoned — refresh the QMD index for the affected store (no-op when QMD absent), running in the background so it never blocks: `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root> --async`.
+
 After the agent completes, report what changed.

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

@@ -0,0 +1,22 @@
+{
+  "skill_name": "plastic-intent-curator",
+  "notes": "Intent 66a. Spec for the QMD-first discovery step in agents/plastic-intent-curator.md (locate a specific intent before grep/find; distinct from the completion-time reindex step). Runner is intent 76; spec only.",
+  "evals": [
+    {
+      "id": 1,
+      "scope": "behavior",
+      "set": "validation",
+      "prompt": "QMD is present. The user says: find and reclassify the intent about orphan detection.",
+      "expected_output": "During discovery (How You Work), before scanning the store with grep/find to locate the intent, runs `ruby ~/.plastic/scripts/qmd-sync search \"orphan detection\"` to surface the candidate or related intents, then opens the authoritative intent file for the hit it acts on. This discovery step is distinct from the completion-time reindex step. No-op fallback to the full scan when QMD is absent.",
+      "files": [],
+      "assertions": [
+        {
+          "type": "human",
+          "check": "qmd-sync search is run before grep/find during discovery; authoritative file opened for the hit; reindex step stays separate",
+          "observed": "SKILL.md (or agent file) carries the QMD-first step: run qmd-sync search before grep/Read, then open the authoritative file; no-op fallback when QMD is absent",
+          "result": "pass"
+        }
+      ]
+    }
+  ]
+}

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"]
 ```
@@ -41,6 +41,12 @@ tags: [plastic, project-reddit-kb]
 ## Workflow
 
 ### 1. Identify Intents to Connect
+
+QMD-first (when available): before scanning the store with grep/Read, run
+`ruby ~/.plastic/scripts/qmd-sync search "<terms>"` to surface candidate, prior, or related
+intents to propose as sources/chain, then open the authoritative intent file for any hit you act
+on. The command is a no-op when QMD is absent, so fall back to the directory scan below.
+
 Show existing intents by scanning the store's directory for intent files:
 ```bash
 for dir in $STORE_ROOT/store/*/; do
@@ -55,16 +61,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/evals/evals.json

@@ -0,0 +1,22 @@
+{
+  "skill_name": "plastic-linking-intents",
+  "notes": "Intent 66a. Spec for the QMD-first discovery step (surface candidate/related intents to propose as sources/chain before grep/Read). Runner is intent 76; this case is a spec, not executed.",
+  "evals": [
+    {
+      "id": 1,
+      "scope": "behavior",
+      "set": "validation",
+      "prompt": "QMD is present. The user says: link this intent to the related upload-pipeline work.",
+      "expected_output": "Before scanning the store directory with grep/Read to identify related intents, runs `ruby ~/.plastic/scripts/qmd-sync search \"upload pipeline\"` to surface candidate or related intents to propose as sources/chain, then opens the authoritative intent file for any hit it links. No-op fallback to the directory scan when QMD is absent.",
+      "files": [],
+      "assertions": [
+        {
+          "type": "human",
+          "check": "qmd-sync search is run before the directory scan; authoritative file opened for any hit before proposing sources/chain",
+          "observed": "SKILL.md (or agent file) carries the QMD-first step: run qmd-sync search before grep/Read, then open the authoritative file; no-op fallback when QMD is absent",
+          "result": "pass"
+        }
+      ]
+    }
+  ]
+}

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

@@ -10,6 +10,13 @@ Plastic implements three Zettelkasten structures:
 
 INDEX.md is a structure note (hub), not a table of contents.
 
+`## Links` mirrors the frontmatter graph exactly. Each entry is
+`- [[id--slug|<target's full intent: text>]]` (cross-store: `- [[store:id--slug|...]]`),
+a clickable `id--slug` target with the target's full `intent:` text as the label.
+Ordering is mandatory: all `sources` first (top), then all `chain`, frontmatter order
+preserved within each group. Sources never appear at the end. No source/chain tags, no
+sub-grouping. An intent with empty `sources` and `chain` carries the empty-state comment.
+
 ## Folgezettel IDs
 
 IDs encode lineage using Luhmann's alternating convention:
@@ -20,9 +27,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/SKILL.md

@@ -43,6 +43,12 @@ All completed intents with dates. Links preserved, never deleted.
 
 ## Workflow
 
+QMD-first (when available): when you need to locate a specific intent (to reclassify, flag, or
+cluster it) rather than rebuild every section, before scanning the store with grep/Read run
+`ruby ~/.plastic/scripts/qmd-sync search "<terms>"` to surface candidate or related intents, then
+open the authoritative intent file for any hit you act on. The command is a no-op when QMD is
+absent, so fall back to the directory scan below.
+
 ### Rebuild Sections
 Scan the active store's `store/` directory for intent files and rebuild each section: