@zalom/plastic 1.7.1 → 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",
@@ -358,7 +369,7 @@ class InstallerCore
       "scripts/update.rb" => "scripts/update.rb",
       "scripts/uninstall.rb" => "scripts/uninstall.rb",
       "scripts/rollback.rb" => "scripts/rollback.rb",
-      "scripts/lib/legacy_bookend_amnesty.rb" => "scripts/lib/legacy_bookend_amnesty.rb",
+      "scripts/lib/outcome_guard.rb" => "scripts/lib/outcome_guard.rb",
       "scripts/doctor.rb" => "scripts/doctor.rb",
       "scripts/dashboard.rb" => "scripts/dashboard.rb",
       "scripts/skill-lint" => "scripts/skill-lint",
@@ -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/outcome_guard.rb

@@ -0,0 +1,38 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "bridge"
+require_relative "intent_validator"
+
+# OutcomeGuard - the single definition of "is outcome.md real and disposition-matched for
+# THIS close" (intent 222). Extracted verbatim from scripts/end-intent's own
+# outcome_guard_reason (intent 161/188) so end-intent's existing exit-2 path and doctor's new
+# per-intent check (intent_lifecycle_artifacts) can never independently drift on what counts
+# as a valid outcome.md. Pure, read-only: authors nothing regardless of outcome.
+module OutcomeGuard
+  module_function
+
+  DISPOSITIONS = %w[delivered abandoned].freeze
+
+  # Returns nil when the guard PASSES, or a reason String to refuse with. Refuses a missing
+  # file, a still-placeholder file (first line is the sentinel), or a disposition that does
+  # not exactly equal the requested one.
+  def reason(intent_dir, disposition)
+    path = File.join(intent_dir, "outcome.md")
+    return "outcome.md is missing at #{path}" unless File.exist?(path)
+
+    content = File.read(path)
+    first_line = content.each_line.first.to_s.chomp
+    if first_line == Bridge::PLACEHOLDER_SENTINEL
+      return "outcome.md is still the scaffold placeholder (first line is the sentinel)"
+    end
+
+    fm = IntentValidator.parse_frontmatter_text(content)
+    actual = fm.is_a?(Hash) ? fm["disposition"] : nil
+    unless DISPOSITIONS.include?(actual) && actual == disposition
+      return "outcome.md frontmatter disposition is #{actual.inspect}, expected #{disposition.inspect}"
+    end
+
+    nil
+  end
+end

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

@@ -14,6 +14,7 @@
 #   maintenance-run --tool project-links --intent <id> [--store <key>] [--plastic-home PATH] [--apply]
 #   maintenance-run --tool rebuild-graph [--plastic-home PATH] [--apply]
 #   maintenance-run --tool restore-intent-v1 <id> --at <ref> [--plastic-home PATH] [--apply] [--skip-links]
+#   maintenance-run --tool rebuild-savepoint --intent <id> [--store <key>] [--plastic-home PATH] [--apply]
 #
 # project-links here is ALWAYS single-intent: --intent is required. A store-wide
 # project-links sweep is the rare, owner-approved batch exception (D2) and is run directly
@@ -35,6 +36,8 @@ require "time"
 require_relative "lib/store_discovery"
 require_relative "lib/lock"
 require_relative "lib/maintenance_git"
+require_relative "lib/bridge"
+require_relative "lib/revisions_writer"
 
 DEFAULT_HOME = File.join(Dir.home, ".plastic")
 
@@ -217,9 +220,58 @@ def run_restore_intent_v1(home, id, at, store, apply, skip_links)
   report_result(result)
 end
 
+def run_rebuild_savepoint(home, intent, store, apply)
+  abort_loud("--tool rebuild-savepoint requires --intent <id>") unless intent
+
+  discovery = StoreDiscovery.discover(home)
+  dir = resolve_dir_for_id(discovery, intent, store: store)
+  abort_loud("intent #{intent} not found under #{home}#{store ? " (--store #{store})" : ""}") unless dir
+  check_not_fresh!(dir, intent)
+
+  outcome_path = File.join(dir, "outcome.md")
+  unless Bridge.stage_file_present?(outcome_path)
+    abort_loud("intent #{intent}'s outcome.md is missing or a placeholder; the 124a recipe " \
+               "requires a real disposition to echo, and 219 D6 forbids ever inventing one", 1)
+  end
+
+  frontmatter = File.read(outcome_path)[/\A---\n(.*?)\n---/m, 1].to_s
+  disposition = frontmatter[/^disposition:\s*(\S+)/, 1]
+  abort_loud("intent #{intent}'s outcome.md has no disposition: frontmatter field", 1) unless disposition
+
+  unless apply
+    puts "maintenance-run: DRY RUN, would reconstruct savepoint.md for #{intent} " \
+         "(Bridge.rebuild_savepoint + Done #{disposition} echo)"
+    exit 0
+  end
+
+  begin
+    result = MaintenanceGit.run_scoped(
+      repo_dir: home, branch_name: "maintenance/rebuild-savepoint-#{intent}-#{stamp}",
+      commit_message: "chore: maintenance - rebuild-savepoint #{intent}"
+    ) do
+      Bridge.rebuild_savepoint(dir)
+      Bridge.append_terminal_savepoint(dir, disposition)
+      RevisionsWriter.append!(
+        dir,
+        why: "reconstruct missing operational savepoint.md (generic operational-gap predicate)",
+        rule: "savepoint-operational-reconstruction",
+        prior_location: "#{intent}/savepoint.md",
+        change: "savepoint.md rebuilt from disk (Bridge.rebuild_savepoint) plus Done " \
+                "#{disposition} echo appended (Bridge.append_terminal_savepoint); disposition " \
+                "read from outcome.md's own frontmatter, never invented"
+      )
+    end
+  rescue MaintenanceGit::DirtyWorkingTree, MaintenanceGit::NotAGitRepo => e
+    abort_loud(e.message, 4)
+  rescue RuntimeError => e
+    abort_loud(e.message, 3)
+  end
+  report_result(result)
+end
+
 def main(argv)
   opts = parse_argv(argv)
-  abort_loud("--tool is required (project-links|rebuild-graph|restore-intent-v1)") unless opts[:tool]
+  abort_loud("--tool is required (project-links|rebuild-graph|restore-intent-v1|rebuild-savepoint)") unless opts[:tool]
 
   case opts[:tool]
   when "project-links"
@@ -227,9 +279,11 @@ def main(argv)
   when "rebuild-graph" then run_rebuild_graph(opts[:plastic_home], opts[:apply])
   when "restore-intent-v1"
     run_restore_intent_v1(opts[:plastic_home], opts[:id], opts[:at], opts[:store], opts[:apply], opts[:skip_links])
+  when "rebuild-savepoint"
+    run_rebuild_savepoint(opts[:plastic_home], opts[:intent], opts[:store], opts[:apply])
   else
     abort_loud("unknown --tool #{opts[:tool].inspect} " \
-               "(expected project-links|rebuild-graph|restore-intent-v1)")
+               "(expected project-links|rebuild-graph|restore-intent-v1|rebuild-savepoint)")
   end
 end
 

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`
@@ -343,10 +353,11 @@ During initial project creation, all decisions are non-destructive by definition
    non-zero exit needs attention before moving on: 4 means a live foreign session holds the
    lock (back off), 5 means the code worktree is dirty (commit/stash first, or pass
    `--discard-worktree-changes` deliberately), 3 means disarm ran but the lock is still
-   present (run `/plastic-doctor check the lock status`). Only Step 6 (QMD reindex, async,
-   last) remains a separate action after this call succeeds. Never leave an orphaned
-   worktree; run `git worktree prune` on a stale reference. If any of this ever needs to
-   change, change `plastic-intent-ending`, not this skill.
+   present (run `/plastic-doctor check the lock status`), 6 means the structure gate refused
+   (see the named reason on stderr; fix via the owning tool named above, then re-run). Only
+   Step 6 (QMD reindex, async, last) remains a separate action after this call succeeds.
+   Never leave an orphaned worktree; run `git worktree prune` on a stale reference. If any of
+   this ever needs to change, change `plastic-intent-ending`, not this skill.
 7. Notify user (Done briefing): brief per `references/human-report-contract.md`
     (State: the delivered impact; Risk: residual risk; Call: the decision left to you, merge,
     release, or accept). See `outcome.md` for details.

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.