@zalom/plastic 1.8.0 → 1.9.0

package/scripts/lib/installer_core.rb

@@ -32,17 +32,20 @@ class InstallerCore
   # Regex matching exactly one managed section (BEGIN line .. END line), non-greedy.
   CODEX_SECTION_RE = /^<!-- BEGIN PLASTIC INTEGRATION.*?-->\n.*?\n<!-- END PLASTIC INTEGRATION -->\n?/m
 
-  # Curated essentials plus a pointer to ~/.plastic/PLASTIC.md, injected into
-  # ~/.codex/AGENTS.md. Not a slice of PLASTIC.md (which is already over the 32 KiB
-  # AGENTS.md merge cap on its own), so it never drifts and carries no maintenance fork.
+  # Curated essentials plus a pointer to ~/.plastic/PLASTIC.md and the plastic-conventions
+  # skill, injected into ~/.codex/AGENTS.md. Not a slice of PLASTIC.md itself: AGENTS.md is
+  # a shared file Codex merges from multiple sources, so this block stays a small,
+  # hand-curated pointer rather than embedding the core wholesale, and it never drifts
+  # because it only ever points, never duplicates.
   CODEX_AGENTS_MD_BODY = <<~MD.freeze
     Plastic is installed for this agent. Plastic is intent-driven state management: all
     work flows through an intent, moved through What, Why, How, then Exec. Do not jump
     straight to code.
 
     Standing rules:
-    - The full conventions live in ~/.plastic/PLASTIC.md. Read it and follow it exactly.
-      It is generated and overwritten on Plastic updates, so never edit it.
+    - Core conventions live in ~/.plastic/PLASTIC.md. Read it and follow it exactly. For
+      depth, read a chapter from ~/.agents/skills/plastic-conventions/references/ on demand.
+      Both are generated and overwritten on Plastic updates, so never edit them.
     - Operational procedures are installed as skills under ~/.agents/skills/ (each
       plastic-<name>/SKILL.md). Invoke one explicitly as $plastic-<name> (for example
       $plastic-doctor), or let Codex pick one implicitly by matching its description.
@@ -232,6 +235,13 @@ class InstallerCore
   def distribute(mode)
     puts "  \u{1f4e6} #{mode == :update ? "Updating" : "Installing"} core files to #{plastic_home}"
 
+    manifest_path = File.join(plastic_home, "manifest.json")
+    # Capture the prior manifest before the copy loop touches anything, so a
+    # file dropped from core_files (renamed/removed) can be pruned below
+    # instead of orphaning forever. Mirrors install_for_agent's prune (D14
+    # Why-gate correction: this global path never had it).
+    old_files = manifest_files(manifest_path)
+
     FileUtils.mkdir_p(plastic_home)
     FileUtils.mkdir_p(File.join(plastic_home, "scripts", "lib"))
     FileUtils.mkdir_p(File.join(plastic_home, "templates"))
@@ -252,9 +262,11 @@ class InstallerCore
     global_files = core_files.values.map { |d| File.join(plastic_home, d) }
     global_files << File.join(plastic_home, "VERSION")
     global_files = global_files.select { |p| File.exist?(p) }
-    write_manifest(global_files, File.join(plastic_home, "manifest.json"))
+    write_manifest(global_files, manifest_path)
+
+    pruned = prune_removed_files(old_files - global_files, root: plastic_home)
 
-    puts "  \u{2705} Core files synced (v#{version})"
+    puts "  \u{2705} Core files synced (v#{version})#{pruned.positive? ? ", #{pruned} stale file(s) pruned" : ""}"
   end
 
   # Templates ship in full: every file under templates/ in the repo must reach
@@ -282,7 +294,6 @@ class InstallerCore
   def hand_registered_files
     {
       "PLASTIC.md" => "PLASTIC.md",
-      "PLASTIC-reference.md" => "PLASTIC-reference.md",
       "deprecations.yml" => "deprecations.yml",
       "config_asks.yml" => "config_asks.yml",
       "scripts/folgezettel-id" => "scripts/folgezettel-id",
@@ -294,7 +305,7 @@ class InstallerCore
       "scripts/hook-future-intent-check" => "scripts/hook-future-intent-check",
       "scripts/hook-gate-check" => "scripts/hook-gate-check",
       "scripts/hook-savepoint-pre" => "scripts/hook-savepoint-pre",
-      "scripts/hook-qmd-search" => "scripts/hook-qmd-search",
+      "scripts/hook-power-tools" => "scripts/hook-power-tools",
       "scripts/lib/qmd_hook.rb" => "scripts/lib/qmd_hook.rb",
       "scripts/lib/power_tools.rb" => "scripts/lib/power_tools.rb",
       "scripts/lib/agent_models.rb" => "scripts/lib/agent_models.rb",
@@ -303,8 +314,6 @@ class InstallerCore
       "scripts/hook-code-gate" => "scripts/hook-code-gate",
       "scripts/hook-lock-gate" => "scripts/hook-lock-gate",
       "scripts/hook-bash-gate" => "scripts/hook-bash-gate",
-      "scripts/hook-retrieval-gate" => "scripts/hook-retrieval-gate",
-      "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/lock.rb" => "scripts/lib/lock.rb",
@@ -345,6 +354,8 @@ class InstallerCore
       "scripts/hook-create-gate" => "scripts/hook-create-gate",
       "scripts/hook-links-gate" => "scripts/hook-links-gate",
       "scripts/lib/links_gate.rb" => "scripts/lib/links_gate.rb",
+      "scripts/lib/edit_gates.rb" => "scripts/lib/edit_gates.rb",
+      "scripts/hook-edit-gates" => "scripts/hook-edit-gates",
       "scripts/lib/apply_patch_envelope.rb" => "scripts/lib/apply_patch_envelope.rb",
       "scripts/codex-hook" => "scripts/codex-hook",
       "scripts/spawn-preamble" => "scripts/spawn-preamble",
@@ -403,10 +414,11 @@ class InstallerCore
     MD
 
     write_if_missing(File.join(plastic_home, "AGENTS.md"), <<~MD)
-      # Plastic \u{2014} Agent Instructions
+      # Plastic: Agent Instructions
 
-      Read `PLASTIC.md` in this directory. It contains all Plastic conventions.
-      Follow it exactly. Never modify it \u{2014} it is overwritten on plugin updates.
+      Read `PLASTIC.md` in this directory for the core conventions; deeper doctrine lives
+      in the `plastic-conventions` skill's chapters. Follow it exactly. Never modify it:
+      it is overwritten on plugin updates.
 
       This file (`AGENTS.md`) is where project-specific rules live.
 
@@ -508,7 +520,8 @@ class InstallerCore
              end
 
     new_files = manifest_files(manifest_path_for(key, config))
-    pruned = prune_removed_files(old_files - new_files)
+    pruned = prune_removed_files(old_files - new_files,
+                                  root: [config[:dir], config[:home_dir], *shared_fragment_prune_roots])
     result[:pruned] = pruned if pruned.positive?
 
     # The legacy manifest is fully superseded once the new one is written; delete it so
@@ -588,7 +601,8 @@ class InstallerCore
         restore_agent(config)
         result = { agent: config[:name], success: false, reason: "verify failed - restored prior snapshot" }
       else
-        prune_removed_files(manifest_files(manifest_path_for(key, config)))
+        prune_removed_files(manifest_files(manifest_path_for(key, config)),
+                             root: [config[:dir], config[:home_dir], *shared_fragment_prune_roots])
         result = { agent: config[:name], success: false, reason: "verify failed - partial install pruned" }
       end
     end
@@ -599,10 +613,30 @@ class InstallerCore
 
   # Delete tracked files present in the old manifest but absent from the new one,
   # then remove any now-empty skill directories they lived in.
-  def prune_removed_files(stale_files)
+  #
+  # `root:` is a mandatory containment boundary (intent 223 F5): every manifest path
+  # is read back from JSON written by write_manifest and could, on a hand-edited or
+  # otherwise corrupt manifest, name a path outside the install this call is pruning
+  # (for example `distribute` prunes against `~/.plastic/`, `install_for_agent` prunes
+  # against one agent's own directories). Accepts a single path or an array (an agent
+  # with a two-root schema, like Codex's `dir` plus `home_dir`, tracks files under
+  # both, so a single boundary would wrongly reject legitimate prunes under the root
+  # not passed). A candidate that resolves outside every given root is skipped and
+  # never deleted, so a stray manifest entry can never delete a path outside the
+  # target home.
+  def prune_removed_files(stale_files, root:)
+    expanded_roots = Array(root).compact.map { |r| File.expand_path(r) }
     removed = 0
     dirs = []
     stale_files.each do |f|
+      if path_contained?(f, store_roots)
+        warn "  \u{26a0}\u{fe0f}  Refused to prune #{f}: inside the intent store"
+        next
+      end
+      unless path_contained?(f, expanded_roots)
+        warn "  \u{26a0}\u{fe0f}  Skipped prune of #{f}: outside #{expanded_roots.join(", ")}"
+        next
+      end
       if File.exist?(f)
         File.delete(f)
         removed += 1
@@ -615,6 +649,54 @@ class InstallerCore
     removed
   end
 
+  # True when `path`, once expanded, is one of `roots` itself or lives underneath
+  # one of them. String-prefix containment guarded by a trailing separator so a
+  # sibling directory that merely shares a prefix (`/home/x-evil` vs root `/home/x`)
+  # never counts as contained.
+  def path_contained?(path, roots)
+    expanded = File.expand_path(path)
+    Array(roots).any? { |root| expanded == root || expanded.start_with?(root + File::SEPARATOR) }
+  end
+
+  # Intent 223 (post-delivery hardening): the user's entire intent history lives under
+  # `plastic_home/store` (the global store) and `plastic_home/projects` (every project
+  # store). `distribute` legitimately prunes with `root: plastic_home`, which CONTAINS
+  # both directories, so the ordinary `root:` containment check in `prune_removed_files`
+  # admits a store path instead of refusing it. Today that branch is unreachable (the
+  # pruned set is always `old_files - global_files`, both derived from `core_files` plus
+  # `VERSION`, so no store path can ever appear there), so this is defense in depth for
+  # an unreachable case, not a fix for a live bug. It exists because the standing rule is
+  # that NO path ever deletes the global or project intent stores, and the cost of being
+  # wrong (irreversible loss of the user's whole intent history) warrants a guard that
+  # fails milder than the bug it prevents, independent of what any caller's `root:` is or
+  # what a hand-edited manifest claims.
+  def store_roots
+    [File.join(plastic_home, "store"), File.join(plastic_home, "projects")].map { |p| File.expand_path(p) }
+  end
+
+  # `install_skills_flat` relocates any top-level underscore-prefixed markdown
+  # fragment (today: `_active-intent-gate.md`, `_decision-tables.md`) out of the
+  # per-agent skills tree and into `plastic_home` directly, then lists them in
+  # `installed`, so they are manifest-tracked and eligible for prune. But
+  # `install_for_agent`'s prune roots are `[config[:dir], config[:home_dir]]`,
+  # which do not cover `plastic_home`, so those two files could never actually be
+  # pruned (every attempt printed "Skipped prune of ... outside ..." to stderr).
+  #
+  # Fix scope (intent 223 N3): add each shared fragment's exact FILE path as its
+  # own containment root, never `plastic_home` itself as a directory root.
+  # `path_contained?` only matches a candidate that equals a root exactly or
+  # lives under `root + separator`; a root that is itself a file path can never
+  # have children, so listing these exact files as roots permits pruning ONLY
+  # those files, never anything else under `plastic_home`. This keeps
+  # `~/.plastic/store` and `~/.plastic/projects` (the user's intent stores, never
+  # prunable by standing rule) outside every prune root.
+  def shared_fragment_prune_roots
+    skills_source = File.join(package_root, "skills")
+    return [] unless File.directory?(skills_source)
+    Dir.children(skills_source).select { |e| e.start_with?("_") && e.end_with?(".md") }
+       .map { |e| File.join(plastic_home, e) }
+  end
+
   def install_claude(config, force, argv: [], input: $stdin, reinstall: false)
     hooks_dir = File.join(config[:dir], "hooks")
     skills_root = File.join(config[:dir], "skills")

package/scripts/lib/qmd_hook.rb

@@ -5,22 +5,28 @@ require_relative "qmd_sync"
 require_relative "power_tools"
 
 # QmdHook - decision logic for the power-tools UserPromptSubmit hook (intents 66,
-# 66b). Pure and dependency-injected: returns the additionalContext string to
-# emit, or nil to emit nothing. The executable hook wires real deps and prints;
-# this is unit-tested with a fake runner/detector (no real qmd, no network).
+# 66b, 187, 246). Pure and dependency-injected: returns the additionalContext
+# string to emit, or nil to emit nothing. The executable hook wires real deps and
+# prints; this is unit-tested with fake detectors (no real qmd, no network, no
+# subprocess at all).
 #
-# When qmd is present it still injects scored qmd hits (intent 66), then appends
-# the PowerTools mandate (a recommendation per present tool: qmd for finding
-# intents, Enola-first for code navigation, falling back to Serena; intent 187
-# added the enola_detector alongside the pre-existing serena_detector).
+# It emits exactly one thing: the PowerTools mandate, one recommendation line per
+# present tool (qmd for finding intents, Enola-first for code navigation, falling
+# back to Serena; intent 187 added the enola_detector alongside the pre-existing
+# serena_detector).
+#
+# Intent 246 removed the scored qmd hit injection this hook used to prepend.
+# Intent 225 measured that injection at 0.24 intent-level recall@3 against a plain
+# ripgrep control at 0.18, while agent-driven `qmd query` scored 0.71. The failure
+# was recall, not latency, so caching and async were both rejected. QmdSync.search
+# is untouched and still backs the `scripts/qmd-sync search` CLI verb. All three
+# detectors are PATH and marker-file walks with no subprocess, which is why what is
+# left costs about a tenth of a second.
 module QmdHook
   module_function
 
-  MIN_PROMPT_LENGTH = 10
-
-  def run(prompt:, cwd:, plastic_home:, runner: QmdSync.default_runner,
-          detector: QmdSync.method(:detect), limit: 3, min_score: 0.5,
-          serena_detector: nil, enola_detector: nil)
+  def run(cwd:, detector: QmdSync.method(:detect), serena_detector: nil,
+          enola_detector: nil)
     serena_detector ||= -> { PowerTools.serena?(cwd: cwd) }
     enola_detector ||= -> { PowerTools.enola?(cwd: cwd) }
     qmd_present = !!detector.call
@@ -28,34 +34,8 @@ module QmdHook
     enola_present = !!enola_detector.call
     return nil unless qmd_present || serena_present || enola_present
 
-    p = prompt.to_s.strip
-    # The hit SEARCH is the only expensive step and the only one gated by prompt
-    # triviality: skip it for short or bare-"continue" prompts (and when qmd is
-    # absent). The mandate itself is always-on for whichever tools are present.
-    search_ok = qmd_present && p.length >= MIN_PROMPT_LENGTH && p.downcase != "continue"
-
-    parts = []
-    if search_ok
-      collections = QmdSync.collections_for_cwd(cwd, plastic_home: plastic_home)
-      hits = QmdSync.search(p, collections: collections, limit: limit,
-                            min_score: min_score, runner: runner, detector: detector)
-      if hits.any?
-        parts << "Related / prior Plastic intents (qmd BM25, includes completed) - " \
-                 "check before treating this as new work:"
-        hits.each do |h|
-          loc = h[:file].to_s.sub(%r{\Aqmd://}, "")
-          pct = (h[:score] * 100).round
-          parts << "- [#{pct}%] #{loc} - #{h[:title]}"
-        end
-        parts << ""
-      end
-    end
-
-    mandate = PowerTools.mandate(cwd: cwd, qmd_detector: -> { qmd_present },
-                                 serena_detector: -> { serena_present },
-                                 enola_detector: -> { enola_present })
-    parts << mandate if mandate
-    return nil if parts.empty?
-    parts.join("\n")
+    PowerTools.mandate(cwd: cwd, qmd_detector: -> { qmd_present },
+                       serena_detector: -> { serena_present },
+                       enola_detector: -> { enola_present })
   end
 end

package/scripts/lib/qmd_sync.rb

@@ -134,21 +134,6 @@ module QmdSync
     pid
   end
 
-  # True when the QMD index has no pending (unembedded) documents. Binary
-  # freshness signal for the retrieval gate (intent 84, Lever 2). `qmd status` is
-  # plain text (no --json); it prints a line like "Pending: N need embedding".
-  # No pending line found -> treat as fresh (conservative: a parse miss must not
-  # block reads). Runner failure -> false (cannot confirm freshness). The caller
-  # gates on `detect` first, so absence is handled upstream; this only answers
-  # "is the present index fresh?". Pure via the injected runner.
-  def self.fresh?(runner: default_runner)
-    out, ok = runner.call(["status"])
-    return false unless ok && out
-    m = out[/^\s*Pending:\s*(\d+)\b/i, 1]
-    pending = m ? m.to_i : 0
-    pending.zero?
-  end
-
   # Read-only status used by doctor and the session-start report line.
   # Returns a structured hash; never mutates the index.
   def status(plastic_home:, runner: default_runner, detector: method(:detect))

package/scripts/lib/revisions_writer.rb

@@ -15,7 +15,7 @@ module RevisionsWriter
   module_function
 
   # PURE. Renders one `## Revision vN - TIMESTAMP` entry in the documented shape
-  # (PLASTIC-reference.md > Structural maintenance and revisions.md; templates/revisions.md).
+  # (plastic-conventions > references/maintenance-and-revisions.md; templates/revisions.md).
   # `n` is the next revision number (caller resolves it via next_revision_number, or a caller
   # that already knows it, e.g. a batch writer amortizing one file read across many entries).
   # `why` is the one-sentence reason ending in "[rule: <tag>]" (tag is appended here if the

package/scripts/restore-intent-v1

@@ -6,9 +6,10 @@
 # while preserving its frontmatter GRAPH (sources/chain) as a target-resolved
 # union of the v1 snapshot and the current snapshot (intent 193). This is the
 # ONLY sanctioned way to restore a completed intent to v1; a hand-run whole-file
-# `git checkout`/revert is forbidden (see PLASTIC.md > Terminal immutability),
-# because it cannot tell prose from graph metadata and silently destroys
-# backlinks written after v1 (the 124/131 incident this tool exists to prevent).
+# `git checkout`/revert is forbidden (see plastic-conventions > references/maintenance-and-revisions.md,
+# WORK vs MAINTENANCE and its Restore-to-v1 paragraph), because it cannot tell prose from graph
+# metadata and silently destroys backlinks written after v1 (the 124/131 incident this tool
+# exists to prevent).
 #
 # Usage:
 #   restore-intent-v1 <intent-id> --at <git-ref> [--plastic-home PATH] [--apply] \
@@ -19,12 +20,14 @@
 # class of tool already destroyed live store data once. --apply is required to
 # write.
 #
-# Restore-to-v1 runs under the MAINTENANCE lock (PLASTIC.md > Terminal
-# immutability: the maintenance lock covers sanctioned structural move-and-record
-# edits after completion). This tool does NOT acquire, check, or manage that
-# lock itself (fail-open doctrine, intent 111: lock management is the
-# orchestrator's job, never built into a CLI as a trap); it only prints a
-# one-line reminder on --apply.
+# There is exactly one lock in Plastic, `delivery.lock`, and MAINTENANCE (this tool included)
+# never acquires or checks it: WORK vs MAINTENANCE (plastic-conventions >
+# references/maintenance-and-revisions.md) holds the corrected doctrine after intent 112's
+# proposed second "maintenance.lock" was abandoned before merge and never shipped. This tool does
+# NOT acquire, check, or manage `delivery.lock` itself (fail-open doctrine, intent 111: lock
+# management is the orchestrator's job, never built into a CLI as a trap); it only prints a
+# one-line reminder on --apply that the target intent must be terminal, which the caller is
+# responsible for confirming before running with --apply.
 #
 # LINKS BLAST RADIUS: an applied restore reprojects `## Links` via
 # scripts/project-links, which is a STORE-WIDE operation with no per-intent
@@ -142,8 +145,10 @@ class RestoreIntentV1CLI
     File.write(md_path, new_md) if md_changed
     other_files.each { |f, content| File.write(File.join(dir, f), content) }
 
-    puts "Reminder: restore-to-v1 runs under the maintenance lock (PLASTIC.md > Terminal " \
-         "immutability). Confirm the maintenance lock is held before this --apply."
+    puts "Reminder: restore-to-v1 is MAINTENANCE, not WORK (plastic-conventions > " \
+         "references/maintenance-and-revisions.md, WORK vs MAINTENANCE). There is no " \
+         "maintenance lock to hold; confirm the target intent is terminal (Completed or " \
+         "Abandoned) with no fresh delivery.lock before this --apply."
 
     handle_links_reprojection(base)
     append_revision(dir, base, graph, files: prose_changes,

package/skills/auto/SKILL.md

@@ -85,6 +85,10 @@ and artifact depth to that size. Extended walkthrough: `references/tiers.md`.
 5. **Tier record.** `Tier: S|M|L` at the top of spec.md. Convention-only: read by the
    orchestrator, never validated by any gate or by doctor.
 
+Read `../plastic-conventions/references/tiers-and-dispatch.md` for tier sizing, agent-model
+config, advisor routing, and the auto-mode human report contract behind the sizing above. This
+path resolves relative to this skill's own installed directory.
+
 ## Arm the Lifecycle Gate (do this FIRST)
 
 Immediately after selecting the intent - before any other work - arm auto mode. This
@@ -110,6 +114,9 @@ implies for later tool calls) read `references/end-tail.md`.
 intent directory / `~/.plastic/`) until `plan.md` AND `checklist.md` exist for the intent.
 Honor the cycle: What → Why (spec.md) → How (plan.md + actions/ + checklist.md) → Exec.
 
+Read `../plastic-conventions/references/locks-and-worktrees.md` for delivery isolation: the
+single-owner lock, claims, worktrees, solo mode, and the station ledger behind the arming above.
+
 ## Flags
 
 - `--skip-permissions` - bypass hard stops on destructive actions on existing projects. Full trust mode. Default: off.
@@ -303,6 +310,9 @@ During initial project creation, all decisions are non-destructive by definition
 
 ## Completion
 
+Read `../plastic-conventions/references/completion-and-done.md` for what "intent done" means and
+the End-stage tail the steps below walk through.
+
 1. Verify all checklist items are checked
 2. Write `outcome.md` with detailed results, from `${CLAUDE_PLUGIN_ROOT}/templates/outcome.md`.
    Set the frontmatter `disposition: delivered` (this is the delivered terminal). `outcome.md`

package/skills/auto/evals/evals.json

@@ -208,13 +208,13 @@
       "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.",
+      "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). No search hits are injected: intent 246 removed the per-prompt qmd hit search, so the hook emits the mandate and nothing else.",
       "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",
+          "observed": "power_tools_test.rb + qmd_hook_test.rb assert MUST wording; serena line gated on the serena detector; qmd_hook_test.rb test_no_retrieval_hits_are_ever_injected asserts no hit header for any tool combination",
           "result": "pass"
         }
       ]

package/skills/conventions/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: plastic-conventions
+description: >
+  Chapters of Plastic doctrine used by more than one skill: the knowledge graph,
+  lifecycle and savepoints, tiers and dispatch, gates and enforcement, locks and
+  worktrees, completion, maintenance, and roadmaps. Read a chapter when its trigger
+  applies to the work in front of you.
+user-invocable: false
+---
+
+# Plastic Conventions
+
+The chapters below hold Plastic doctrine that more than one skill needs. Core always-on
+conventions stay in `~/.plastic/PLASTIC.md`, which is injected at session start. Read a chapter
+when the trigger in the second column applies to the work in front of you.
+
+| Chapter | Read it when |
+|---|---|
+| `references/knowledge-graph.md` | when creating, linking, curating, or indexing intents and you need the sources-vs-chain doctrine, the tiers of influence, the `## Links` projection, or branch-vs-root directory semantics |
+| `references/lifecycle-and-savepoints.md` | when running a lifecycle stage or a savepoint and you need the subagent report-home contract for how an insight reaches the intent |
+| `references/tiers-and-dispatch.md` | when sizing an intent, choosing agent models, routing to the advisor, or writing an auto-mode human report |
+| `references/gates-and-enforcement.md` | when a transition gate blocks you, or before using an audited escape, for the gate mechanics and the logging contract |
+| `references/locks-and-worktrees.md` | before taking or releasing a delivery lock, and when working with claims, worktrees, solo mode, or the station ledger |
+| `references/completion-and-done.md` | when ending an intent, for what "intent done" means and the End-stage tail |
+| `references/maintenance-and-revisions.md` | before any structural maintenance edit, for WORK vs MAINTENANCE, the `revisions.md` move-and-record contract, the violation-tag catalog, and the context-economy measurement buckets |
+| `references/roadmaps.md` | when creating, ordering, closing, or consuming a roadmap, for the file format and the status-mirror rule |
+
+Other skills read these chapters directly at
+`../plastic-conventions/references/<chapter>.md`, resolved relative to their own installed
+directory. All three harnesses install skills flat into one shared skills root through the same
+`install_skills_flat` call, so that path is harness-independent.

package/skills/conventions/references/completion-and-done.md

@@ -0,0 +1,40 @@
+# Completion and Done
+
+This chapter holds what "intent done" means and the End-stage tail.
+
+#### What "intent done" means (intent 93)
+
+Done is one law with three signals, and they must agree. INDEX `## Completed` /
+`## Abandoned` is the single canonical terminal marker: it is the store-wide ledger a fresh
+session reads first, so it wins on any conflict. `outcome.md` is the "deliverable exists"
+signal, and the savepoint `Done delivered|abandoned` line is the audit echo. All three must
+agree; when they disagree, INDEX is authoritative and `doctor` flags the mismatch (the
+`done_signals` check: `outcome.md` real but still under `## Active`, or terminal without a
+real `outcome.md`, or a terminal intent whose savepoint carries no `Done` line).
+
+`outcome.md` is mandatory at every terminal transition, delivered and abandoned alike. It
+self-declares its disposition through a `disposition: delivered|abandoned` frontmatter
+header. The delivered path authors it with the result; the abandoned path authors it with
+the abandonment reason and no longer leaves the scaffolded placeholder sentinel in place.
+
+The canonical End tail runs in this order, and the QMD reindex is always LAST, after the
+purge: `outcome.md -> INDEX terminal -> savepoint Done -> commit -> disarm (Worktree.release
+-> Lock.release -> purge) -> QMD reindex`. Running the reindex last keeps the index from
+ever referencing a bridge or lock that disarm is about to remove.
+
+`scripts/end-intent` performs this order's disarm step (verify the code worktree is clean,
+then merge/remove worktrees, then clear the lock) as its own step 5, mechanically, since
+intent 188: a session no longer needs a separate one-liner for it, and the script's own
+exit code (0) is the single fact a caller needs that the intent is closed AND its delivery
+lock is gone. A pre-flight lock guard runs before anything is written (refuses a live
+foreign session, reclaims a stale one with an audit line), and a dirty code worktree
+refuses before removal rather than force-discarding uncommitted changes.
+
+The post-done access window is lock-bounded: `[INDEX terminal -> Lock.release]`. Through it
+the completing session keeps full read and write access to the terminal directory and no
+purge can fire (108's lock-held keep-guard keeps the bridge while `delivery.lock` exists).
+Once the lock is released the window closes: the bridge becomes purge-eligible and the
+directory is frozen. A crash mid-tail is recovered by stale-lock reclaim plus finishing the
+tail; `doctor` surfaces this as a "stalled completion" (terminal in INDEX but the lock is
+still present or stale). Finishing the tail is FINISHING a completion, never a reactivation:
+a done intent is never moved back to `## Active`.

package/skills/conventions/references/gates-and-enforcement.md

@@ -0,0 +1,23 @@
+# Gates and Enforcement
+
+This chapter holds the escape-and-logging depth for each transition gate.
+
+#### The gates by name
+
+Each gate guards one thing. All are hard:
+
+- **create-gate** validates the proposed intent file at What write-time (Write, Edit, and MCP
+  edits), so a malformed or incomplete intent never lands.
+- **gate-check** enforces lifecycle stage order (spec.md before plan.md, the plan triplet before
+  the checklist, all checklist items before outcome.md).
+- **lock-gate** arbitrates ownership and claims: it admits only the intent's lock owner or a
+  registered delegate to write into an active intent directory, and every deny names the
+  resolving `plastic-lock` command.
+- **bash-gate** intercepts a write attempted through a bash or interpreter one-liner (a heredoc, a
+  `>` redirect, a `ruby -e` or `python -c` write), so the same rules apply whether an edit goes
+  through the Write tool or a shell. A trailing `# plastic-ok` comment is an auditable escape that
+  lets a deliberate command through, and every use is logged to
+  `~/.plastic/.cache/gate-escapes.log`. The code gate (Write and Edit) carries the identical
+  audited `# plastic-ok` escape, logged to the same file. The escape does not extend to
+  `NotebookEdit` or MCP structural edits: they are still gated, just without an escape hatch.
+

package/skills/conventions/references/knowledge-graph.md

@@ -0,0 +1,47 @@
+# Knowledge Graph
+
+This chapter holds the linking doctrine from Frontmatter and the branch-vs-root directory semantics from Directory Naming.
+
+- `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.
+
+- `## Links` (I5) is the human-readable projection of the graph. It mirrors the
+  frontmatter exactly: every 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.
+- `## Links` is a DERIVED view, not a place to author links (Convention over Configuration).
+  It equals the projection of `sources` (first) then `chain`. Never hand-write or hand-edit a
+  `## Links` line, and never auto-delete one. The edge lives in the frontmatter graph; the
+  section is regenerated from it (doctor `graph_links_projection` enforces this identity). To
+  add a link, add the frontmatter edge, then reproject.
+
+- Links are decided by CONTEXT INFLUENCE, not by shared files, shared symbols, or a topic
+  similarity score. The question is whether one intent's context actually informed another.
+  Three tiers:
+  - **sources:** the foundational context that shaped this intent's creation (a split, an idea
+    born during development, a merge). Earns an edge.
+  - **chain:** the context that materially helps DELIVER this intent. This is a HIGH bar: only
+    the genuinely delivery-moving intents, not everything in the same area. Earns an edge,
+    reflected in `## Links`.
+  - **tags:** a loose theme grouping for search. NOT a link. A shared tag is a door INTO the
+    store (filtered discovery), not a pathway BETWEEN two notes.
+  Judging influence is an agent's call, made by reading the candidate's Intent and Context. A
+  script cannot grade it, so `scripts/link-suggest` only gathers candidates with that evidence,
+  records a confirmed edge with a rating and reason, and flags drift.
+
+**Branch vs root: the semantic decision.** The numbering is mechanics; choosing
+*whether* to branch is meaning:
+
+- **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.
+  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--slug|<target's full intent: text>]]` wikilink in `## Links`).
+- **Rule of thumb:** if the intent could exist without its parent, it's a root.

package/skills/conventions/references/lifecycle-and-savepoints.md

@@ -0,0 +1,11 @@
+# Lifecycle and Savepoints
+
+This chapter holds the subagent report-home depth for how an insight reaches the intent when the writer cannot write the file itself.
+
+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 the stage table (What/Why/How/Exec, deliverable, owning skill), see PLASTIC.md's Lifecycle
+Stages section; each named skill's own `references/` holds that stage's own depth.