@zalom/plastic 1.0.0 → 1.0.2

package/PLASTIC.md

@@ -113,9 +113,9 @@ entries stay append-only, newest at the bottom; the prefix only stamps each line
 which stage, and who.
 
 The blessed write path is the `insight-append` helper
-(`scripts/insight-append <intent_dir> <text> --stage S --author A`), which formats the prefix,
-validates it, and appends at the bottom. Hand-editing `## Insights` is an escape hatch; the
-helper is the default so the format cannot drift.
+(`scripts/insight-append <intent_dir> <text> --stage S --author A`), which ships with every
+install and update, formats the prefix, validates it, and appends at the bottom. Hand-editing
+`## Insights` is an escape hatch; the helper is the default so the format cannot drift.
 
 Background sessions and dispatched sub-agents do not write the insight themselves. They carry
 each nugget home in the completion report's `insights:` field, and the orchestrator (or any
@@ -191,6 +191,13 @@ adapter layer that maps Plastic's hooks and model aliases onto each supported ag
 (Claude, Codex, Hermes) is the cross-harness portability layer; see
 docs/reference/harness-adapters.md for the adapter contract.
 
+**Spawn preamble (intent 152).** `scripts/spawn-preamble` emits a live-state block purely from
+filesystem state: the active intent, stage, role/cycle-step, the honor instruction, and the
+report contract. When the intent's code worktree is resolvable and exists on disk, it also
+appends the worktree's absolute path plus a verbatim instruction to `cd` there directly, for
+harnesses whose `EnterWorktree` cannot discover a nested repo from a non-repo launch directory.
+Output is byte-identical when no worktree resolves.
+
 **Orchestrator advisory.** At auto-mode start, the orchestrator recommends once that the user
 run the main session on the best available thinking model (Fable, Opus, or whatever supersedes
 them). This is advisory only: it changes no behavior and blocks nothing if ignored, and it
@@ -343,7 +350,7 @@ ALL work flows through intents.
 3. On completion, capture observations in `## Insights`.
 4. When done, write `outcome.md` + `## Outcome` summary. Update INDEX.md.
 5. Researches are intents. No separate folder.
-6. Intents are created only via `plastic-creating-intent`. Never hand-author an intent file. The skill self-verifies the written intent with `scripts/validate-intent` before announcing or committing, so every intent is born complete.
+6. Intents are created only via `plastic-creating-intent`. Never hand-author an intent file. The skill self-verifies the written intent with `scripts/validate-intent` before announcing or committing, so every intent is born complete. `--intent` text is escaped for double quotes and backslashes before it lands in frontmatter, so free-form text is safe to pass as-is, and a reciprocal `chain:` append preserves the target intent's existing flow- or block-style entries.
 
 ## House Style (self-check)
 
@@ -407,7 +414,9 @@ Each gate guards one thing. All are hard except the retrieval gate:
   `>` 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`.
+  `~/.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.
 - **retrieval-gate** is advisory only (see the Retrieval Gate section): it hints at QMD and never
   blocks a read or search.
 

package/README.md

@@ -102,14 +102,13 @@ Plastic delivers all work through successive stages ->
 
 ## Compatibility and ownership
 
-- Native installers for Claude, Codex, Hermes, and all supported targets.
+- Native installers for Claude (Codex, Hermes, and and others coming soon).
 - Plain Markdown plus Git. The work stays in files you own.
 - Personal stores by default.
 - Guided delivery with a human at every gate, or autonomous delivery when you
   ask for it.
 
-Plastic needs Ruby (already on macOS and Linux) and Node.js 18 or later. Swap
-`--claude` for `--codex`, `--hermes`, or `--all` to match your agent. Bun
+Plastic needs Ruby (already on macOS and Linux) and Node.js 18 or later. Bun
 users can run `bunx` in place of `npx`; Bun is never required.
 
 ## Built with Plastic

package/hooks/code-gate

@@ -17,5 +17,11 @@ fi
 
 SESSION_ID=$(echo "$INPUT" | ruby -rjson -e 'data = JSON.parse(STDIN.read); puts data.dig("session_id") || ""' 2>/dev/null)
 
+NEW_CONTENT=$(echo "$INPUT" | ruby -rjson -e '
+  data = JSON.parse(STDIN.read)
+  ti = data["tool_input"] || data["tool_params"] || {}
+  print ti["content"] || ti["new_string"] || ""
+' 2>/dev/null)
+
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-ruby "$SCRIPT_DIR/../scripts/hook-code-gate" "$FILE_PATH" "$SESSION_ID"
+ruby "$SCRIPT_DIR/../scripts/hook-code-gate" "$FILE_PATH" "$SESSION_ID" "$NEW_CONTENT"

package/package.json

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

package/scripts/hook-code-gate

@@ -20,8 +20,26 @@ exit 0 unless file_path && !file_path.empty?
 
 session = (ARGV[1] unless ARGV[1].to_s.empty?) || ENV["CLAUDE_CODE_SESSION_ID"]
 
+# Auditable escape (intent 150, mirrors the Bash gate's intent 108 D7): a trailing
+# `# plastic-ok` in the new Write/Edit content allows the edit and logs it, so a
+# deliberately sanctioned code edit no longer needs the Bash-funneling workaround.
+new_content = ARGV[2]
+if new_content && Bridge::PLASTIC_OK_RE.match?(new_content.chomp)
+  begin
+    require "fileutils"
+    log = File.join(Dir.home, ".plastic", ".cache", "gate-escapes.log")
+    FileUtils.mkdir_p(File.dirname(log))
+    File.open(log, "a") do |io|
+      io.puts("#{Time.now.utc.iso8601}\t#{session}\t#{file_path}")
+    end
+  rescue StandardError
+    # the escape still applies; logging is best-effort
+  end
+  exit 0
+end
+
 # --- Load bridge (shared resolution; stdin session_id -> CLAUDE_CODE_SESSION_ID -> /tmp scan) ---
-bridge_data = Bridge.discover_bridge(session: session, cwd: Dir.pwd)
+bridge_data = Bridge.discover_bridge(session: session, cwd: file_path)
 exit 0 unless bridge_data
 
 reason = Bridge.code_gate_decision(bridge_data, file_path) ||

package/scripts/lib/installer_core.rb

@@ -254,6 +254,7 @@ class InstallerCore
       "scripts/lib/hook_registry.rb" => "scripts/lib/hook_registry.rb",
       "scripts/agent-report" => "scripts/agent-report",
       "scripts/lib/insights.rb" => "scripts/lib/insights.rb",
+      "scripts/insight-append" => "scripts/insight-append",
       "scripts/lib/worktree.rb" => "scripts/lib/worktree.rb",
       "scripts/lib/boot_banner.rb" => "scripts/lib/boot_banner.rb",
       "scripts/lib/dashboard_banner.rb" => "scripts/lib/dashboard_banner.rb",

package/scripts/lib/qmd_sync.rb

@@ -42,8 +42,10 @@ module QmdSync
   end
 
   # Collection name for a store directory.
-  #   global store (<plastic_home>/store)        -> "plastic-global"
-  #   project store (<.../projects/<slug>/store) -> "plastic-<slug>"
+  #   global store (<plastic_home>/store)          -> "plastic-global"
+  #   project store (<.../projects/<slug>/store)   -> "plastic-<slug>"
+  #   roadmaps dir (sibling of either store above)  -> the sibling store's
+  #                                                    collection name, suffixed "-roadmaps"
   # Slug is resolved from projects.yml by matching the project path; falls back
   # to the directory's parent name when no registry match exists.
   def collection_name(store_dir, plastic_home:)
@@ -51,12 +53,19 @@ module QmdSync
     global_store = File.expand_path(File.join(plastic_home, "store"))
     return "plastic-global" if store_dir == global_store
 
+    if File.basename(store_dir) == "roadmaps"
+      sibling_store = File.join(File.dirname(store_dir), "store")
+      return "#{collection_name(sibling_store, plastic_home: plastic_home)}-roadmaps"
+    end
+
     slug = slug_for_store(store_dir, plastic_home: plastic_home)
     "plastic-#{slug}"
   end
 
   # Every store Plastic knows about: the global store plus each registered
-  # project store. Returns [{collection:, dir:}, ...].
+  # project store, plus a roadmap-companion entry per tier when that tier's
+  # sibling `roadmaps/` directory exists on disk (intent 135). Returns
+  # [{collection:, dir:}, ...].
   def enumerate_stores(plastic_home:)
     stores = [{
       collection: "plastic-global",
@@ -75,7 +84,12 @@ module QmdSync
       dir = Dir.exist?(mirror_store) ? mirror_store : project_store
       stores << { collection: "plastic-#{slug}", dir: dir }
     end
-    stores
+
+    stores.flat_map do |s|
+      roadmaps_dir = File.join(File.dirname(s[:dir]), "roadmaps")
+      next [s] unless Dir.exist?(roadmaps_dir)
+      [s, { collection: "#{s[:collection]}-roadmaps", dir: roadmaps_dir }]
+    end
   end
 
   # Register a store directory as a collection. Idempotent: re-running is safe.
@@ -185,7 +199,12 @@ module QmdSync
   # project's collection plus plastic-global, or just plastic-global when the
   # CWD is not inside any registered project. Project match = CWD equals the
   # registered path or is nested under it.
-  def collections_for_cwd(cwd, plastic_home:)
+  #
+  # Each collection's roadmap companion (intent 135) is appended right after it
+  # when actually registered (checked via the injected runner's `collection
+  # list`), because `qmd search -c <unregistered-collection>` hard-fails the
+  # whole call, so an unregistered companion must never be added blindly.
+  def collections_for_cwd(cwd, plastic_home:, runner: default_runner, detector: method(:detect))
     cwd = File.expand_path(cwd)
     projects = load_projects(plastic_home)
     slug, = projects.find do |_s, info|
@@ -194,7 +213,15 @@ module QmdSync
       root = File.expand_path(path)
       cwd == root || cwd.start_with?(root + File::SEPARATOR)
     end
-    slug ? ["plastic-#{slug}", "plastic-global"] : ["plastic-global"]
+
+    base = slug ? ["plastic-#{slug}", "plastic-global"] : ["plastic-global"]
+    return base unless detector.call
+
+    registered = list_collections(runner)
+    base.flat_map do |c|
+      roadmap = "#{c}-roadmaps"
+      registered.include?(roadmap) ? [c, roadmap] : [c]
+    end
   end
 
   # --- internals ---

package/scripts/new-intent

@@ -73,15 +73,28 @@ def default_templates_dir
 end
 
 def render_tokens(text, tokens)
-  tokens.reduce(text) { |acc, (k, v)| acc.gsub("{{#{k}}}", v.to_s) }
+  # Block-form gsub: a String replacement argument reinterprets backslash
+  # sequences (so a doubled backslash from escape_double_quoted_scalar
+  # collapses back to one); the block form substitutes the value literally.
+  tokens.reduce(text) { |acc, (k, v)| acc.gsub("{{#{k}}}") { v.to_s } }
+end
+
+# Escape the characters that would break a double-quoted YAML scalar: backslash
+# first, so a real backslash in the input isn't re-escaped by the quote step,
+# then the double quote itself. Used only for the frontmatter-bound INTENT
+# token; the body's DESCRIPTION copy stays raw (markdown prose, not a YAML
+# scalar) so escaping it would corrupt what the user actually typed.
+def escape_double_quoted_scalar(value)
+  value.to_s.gsub("\\") { "\\\\" }.gsub('"') { '\"' }
 end
 
 # Add an id to a source intent's frontmatter `chain` array, idempotently (I1
 # reciprocity: `child in parent.sources` => `parent.chain` gains `child`). A
-# targeted edit of the `chain:` line only; the body (including `## Links`) is
+# targeted edit that preserves every existing entry and appends the new id in
+# the SAME on-disk YAML style (flow `chain: [...]` or block `chain:` + indented
+# `- "id"` lines) the target already uses; the body (including `## Links`) is
 # preserved byte-for-byte and no other frontmatter key is touched, so the file
-# stays born-complete. Renders the array in flow style (`["a", "b"]`) to match
-# templates/intent.md. No-op when the id is already present.
+# stays born-complete. No-op when the id is already present.
 def add_to_chain(file_path, new_id)
   return unless File.exist?(file_path)
   content = File.read(file_path)
@@ -91,21 +104,41 @@ def add_to_chain(file_path, new_id)
   return unless parts.length >= 3
 
   fm = parts[1]
-  chain_line = fm.lines.find { |l| l.match?(/\A\s*chain\s*:/) }
-  return unless chain_line
+  lines = fm.lines
+  chain_idx = lines.index { |l| l.match?(/\A\s*chain\s*:/) }
+  return unless chain_idx
+
+  flow_match = lines[chain_idx].match(/\A\s*chain\s*:\s*\[(.*?)\]\s*\z/m)
 
-  existing = fm.match(/\bchain\s*:\s*\[(.*?)\]/m)
-  ids =
-    if existing
-      existing[1].scan(/"([^"]*)"|'([^']*)'/).flatten.compact
+  if flow_match
+    ids = flow_match[1].scan(/"([^"]*)"|'([^']*)'/).flatten.compact
+    return if ids.include?(new_id)
+
+    ids << new_id
+    lines[chain_idx] = "chain: [#{ids.map { |i| "\"#{i}\"" }.join(", ")}]\n"
+  else
+    entry_re = /\A(\s*-\s*)(?:"([^"]*)"|'([^']*)'|(\S+))\s*\z/
+    entry_lines = []
+    j = chain_idx + 1
+    while j < lines.length && lines[j].match?(entry_re)
+      entry_lines << lines[j]
+      j += 1
+    end
+
+    ids = entry_lines.map { |l| (m = l.match(entry_re)) && (m[2] || m[3] || m[4]) }
+    return if ids.include?(new_id)
+
+    if entry_lines.empty?
+      prefix, quote = "  - ", "\""
     else
-      []
+      m = entry_lines.last.match(entry_re)
+      prefix = m[1]
+      quote = m[2] ? "\"" : (m[3] ? "'" : "")
     end
-  return if ids.include?(new_id)
+    lines.insert(chain_idx + 1 + entry_lines.length, "#{prefix}#{quote}#{new_id}#{quote}\n")
+  end
 
-  ids << new_id
-  rendered = "chain: [#{ids.map { |i| "\"#{i}\"" }.join(", ")}]"
-  new_fm = fm.sub(/^\s*chain\s*:.*$/, rendered)
+  new_fm = lines.join
   File.write(file_path, ["", new_fm, parts[2]].join("---"))
 end
 
@@ -260,7 +293,7 @@ def main(argv)
   intent_template = File.read(File.join(templates, "intent.md"))
   intent_body = render_tokens(intent_template, {
     "ID" => id,
-    "INTENT" => opts[:intent],
+    "INTENT" => escape_double_quoted_scalar(opts[:intent]),
     "SOURCES" => sources_str,
     "DATE" => Date.today.iso8601,
     "AUTHOR" => opts[:author],

package/scripts/spawn-preamble

@@ -23,6 +23,7 @@
 # Exit codes: 0 (preamble emitted), 2 (usage).
 
 require_relative "lib/bridge"
+require_relative "lib/worktree"
 
 # Verbatim honoring instruction. Kept as one constant so the contract doc and the
 # test assert against the exact same string.
@@ -31,6 +32,16 @@ HONOR_INSTRUCTION =
   "Emit VALID lifecycle artifacts; do not hallucinate intents or stages. " \
   "Your primary output is valid lifecycle artifacts; you close with a structured report about them."
 
+# Verbatim cd-fallback instruction (intent 152). The harness's own EnterWorktree
+# tool assumes cwd IS the repo root, which fails when a dispatched agent's
+# session launches from a directory that is not itself a git repo (the normal
+# shape for a background job): it cannot discover the nested project repo
+# underneath it. Kept as one constant so the doc and the test assert against
+# the exact same string.
+WORKTREE_FALLBACK_INSTRUCTION =
+  "If EnterWorktree fails to discover the nested repo from a non-repo launch " \
+  "directory, cd directly to the code worktree path above before editing project code."
+
 # Verbatim completion-report contract (intent 74). Kept as one constant so the
 # contract doc (skills/auto/references/agent-report-contract.md), the role prompts,
 # and the test assert against the exact same string. SINGLE SOURCE OF TRUTH for the
@@ -123,7 +134,8 @@ end
 intent_dir = File.expand_path(intent_dir_arg)
 
 fm = frontmatter_for(intent_dir)
-id = fm["id"].to_s.strip
+raw_id = fm["id"].to_s.strip
+id = raw_id
 intent_name = fm["intent"].to_s.strip
 id = "(unknown)" if id.empty?
 intent_name = "(unknown)" if intent_name.empty?
@@ -131,12 +143,24 @@ intent_name = "(unknown)" if intent_name.empty?
 stage = current_stage(intent_dir)
 cycle = role || step || stage
 
+# Already-provisioned code worktree path (intent 152), resolved purely from
+# filesystem/YAML state (no git shell-out): see Worktree.paths's own doc
+# comment. Fails open (no lines added) when unresolvable or not on disk.
+store_root = File.dirname(intent_dir)
+project_slug = Worktree.slug_for_store(store_root)
+intent_slug = Worktree.slug_from_dir(intent_dir)
+code_path = Worktree.paths(slug: project_slug, intent_id: raw_id, intent_slug: intent_slug)["code"]
+
 lines = []
 lines << "=== Plastic spawn preamble ==="
 lines << "Store: #{intent_dir}"
 lines << "Active intent: #{id} - #{intent_name}"
 lines << "Current stage: #{stage}"
 lines << "Cycle step / role: #{cycle}"
+if code_path && Dir.exist?(code_path)
+  lines << "Code worktree: #{code_path}"
+  lines << WORKTREE_FALLBACK_INSTRUCTION
+end
 lines << ""
 lines << HONOR_INSTRUCTION
 lines << ""

package/skills/auto/SKILL.md

@@ -105,7 +105,7 @@ Roster (one role per cycle stage):
 
 Dispatch rule: sequential, one specialist per stage on one branch (the deliverables share files). Gate each deliverable against the stage's exit criteria before handing off. The How and Exec phases below default to Plastic's native dispatch (`plastic-executing-plan`) and delegate to the superpowers skills only when they are available or the user asks; do not restate the phase mechanics here.
 
-Spawn preamble (live-state injection): before dispatching any specialist, run `scripts/spawn-preamble <intent_dir> --role <role>` and PREPEND its output to that specialist's prompt. The preamble is a deterministic, filesystem-only snapshot of the active intent (id, intent line, current stage) plus the honoring instruction, so every spawned agent boots with accurate live state instead of guessing. This is the authoritative L2 mechanism for harnesses whose sub-agents do not inherit a top-level session event (see `docs/reference/harness-adapters.md`).
+Spawn preamble (live-state injection): before dispatching any specialist, run `scripts/spawn-preamble <intent_dir> --role <role>` and PREPEND its output to that specialist's prompt. The preamble is a deterministic, filesystem-only snapshot of the active intent (id, intent line, current stage, and the provisioned code worktree path when one exists on disk) plus the honoring instruction, so every spawned agent boots with accurate live state instead of guessing. This is the authoritative L2 mechanism for harnesses whose sub-agents do not inherit a top-level session event (see `docs/reference/harness-adapters.md`).
 
 Dispatch-time model contract (belt-and-braces): alongside the preamble, resolve each specialist's model through the config chain (`read-config agents.models.<basename> --project <repo>`: project override, then global, then the shipped tier default) and pass it explicitly at dispatch. Never rely on the dispatched role's frontmatter alone; a resolved subagent model is never Fable.
 

package/skills/roadmap/references/operations.md

@@ -20,6 +20,8 @@ next" in under a minute, just from this one file.
    status mirroring that intent's current `INDEX.md` status.
 6. Append the first `## Log` line, a short `YYYY-MM-DD HH:MM UTC`-prefixed plain-language note
    that the roadmap was created.
+7. Refresh the QMD index for this roadmap (no-op when QMD is absent), in the background so it
+   never blocks: `ruby ~/.plastic/scripts/qmd-sync reindex --store <roadmaps-dir> --async`.
 
 ## Add / reorder entries
 
@@ -32,6 +34,8 @@ next" in under a minute, just from this one file.
   entry is eligible to run.
 - After any add/reorder, append a `## Log` line describing the change (e.g.
   `- <YYYY-MM-DD HH:MM UTC> added 132 to wave 2`).
+- Refresh the QMD index for this roadmap (no-op when QMD is absent), in the background so it
+  never blocks: `ruby ~/.plastic/scripts/qmd-sync reindex --store <roadmaps-dir> --async`.
 
 ## Sync status mirror
 
@@ -45,6 +49,8 @@ next" in under a minute, just from this one file.
    one-line EM-to-CTO entry described in `file-format.md` (date, what shipped and its impact in
    plain language, then a link to that intent's `outcome.md`). For other transitions, write a
    short dated plain-language line (no codenames, no jargon).
+5. Refresh the QMD index for this roadmap (no-op when QMD is absent), in the background so it
+   never blocks: `ruby ~/.plastic/scripts/qmd-sync reindex --store <roadmaps-dir> --async`.
 
 ## Append a log line
 
@@ -54,6 +60,8 @@ next" in under a minute, just from this one file.
   A delivery event follows the EM-to-CTO one-line shape with an `outcome.md` link (see
   `file-format.md`); bookkeeping events (created, an intent added to a wave, a wave completed, a
   roadmap closed) are short dated plain-language lines.
+- Refresh the QMD index for this roadmap (no-op when QMD is absent), in the background so it
+  never blocks: `ruby ~/.plastic/scripts/qmd-sync reindex --store <roadmaps-dir> --async`.
 
 ## Read / consume
 
@@ -76,3 +84,5 @@ next" in under a minute, just from this one file.
    lists only live (open or in-flight) roadmaps.
 4. Append the final `## Log` line before or as part of the move:
    `- <YYYY-MM-DD HH:MM UTC> roadmap closed`.
+5. Refresh the QMD index for this roadmap (no-op when QMD is absent), in the background so it
+   never blocks: `ruby ~/.plastic/scripts/qmd-sync reindex --store <roadmaps-dir> --async`.