@zalom/plastic 1.0.0-alpha.37 → 1.0.0-alpha.38

package/hooks/create-gate

@@ -0,0 +1,3 @@
+#!/bin/bash
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+exec ruby "$SCRIPT_DIR/../scripts/hook-create-gate"

package/hooks/hooks.json

@@ -40,6 +40,16 @@
           }
         ]
       },
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook\" create-gate",
+            "statusMessage": "Checking create gate..."
+          }
+        ]
+      },
       {
         "matcher": "Bash",
         "hooks": [

package/package.json

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

package/scripts/dashboard.rb

@@ -23,6 +23,7 @@ require "json"
 require "yaml"
 require "date"
 require_relative "doctor"
+require_relative "lib/bridge"
 
 PLASTIC_HOME = ENV.fetch("PLASTIC_HOME") { File.join(Dir.home, ".plastic") }
 
@@ -113,10 +114,14 @@ def parse_intent(store_info, dir_name, status_index)
 
   id = fm["id"].to_s
   has = ->(f) { File.exist?(File.join(dir, f)) }
+  # Sentinel-aware presence for lifecycle files (intent 60b): a scaffolded
+  # placeholder spec/plan/checklist/outcome reads as absent, so a freshly
+  # scaffolded intent reports What/Why and is never marked completed/advanced.
+  real = ->(f) { Bridge.stage_file_present?(File.join(dir, f)) }
   body = File.exist?(md) ? File.read(md) : ""
 
   status =
-    if has.("outcome.md") then "completed"
+    if real.("outcome.md") then "completed"
     elsif status_index[:active].include?(id) then "active"
     elsif status_index[:abandoned].include?(id) then "abandoned"
     elsif status_index[:completed].include?(id) then "completed"
@@ -134,12 +139,12 @@ def parse_intent(store_info, dir_name, status_index)
     created: (fm["created"].to_s rescue ""),
     value_field: fm["value"] && fm["value"].to_s,
     status: status,
-    spec: has.("spec.md"),
-    plan: has.("plan.md"),
-    checklist: has.("checklist.md"),
-    outcome: has.("outcome.md"),
+    spec: real.("spec.md"),
+    plan: real.("plan.md"),
+    checklist: real.("checklist.md"),
+    outcome: real.("outcome.md"),
     savepoint: has.("savepoint.md"),
-    checklist_partial: has.("checklist.md") && checklist_partially_done?(File.join(dir, "checklist.md")),
+    checklist_partial: real.("checklist.md") && checklist_partially_done?(File.join(dir, "checklist.md")),
     body_has_context: body.include?("## Context"),
     last_accessed_at: last_accessed_at(dir, (fm["created"].to_s rescue "")),
   }

package/scripts/doctor.rb

@@ -439,6 +439,40 @@ class Doctor
       )
     end
 
+    # section_structure — per-intent top-level `##` section set. Reuses
+    # IntentValidator::SANCTIONED_SECTIONS / validate_sections so the sanctioned
+    # set is defined in exactly one place (shared with the create gate and the
+    # validate-intent CLI). Read-only diagnostic: unknown or missing sections are
+    # not auto-fixable here.
+    bad_sections = []
+    intent_dirs.each do |d|
+      md_path = File.join(d[:path], "#{d[:name]}.md")
+      next unless File.exist?(md_path)
+
+      body = IntentValidator.body_of(File.read(md_path))
+      result = IntentValidator.validate_sections(body)
+      next if result[:ok]
+
+      issues = []
+      issues.concat(result[:unknown].map { |h| "unknown #{h}" })
+      issues.concat(result[:missing].map { |s| "missing #{s}" })
+      bad_sections << { dir: tilde(d[:path]), issues: issues }
+    end
+
+    if bad_sections.empty?
+      checks << check(
+        category: "conventions", name: "section_structure", status: "pass",
+        message: "All intent files have the sanctioned ## section structure"
+      )
+    else
+      checks << check(
+        category: "conventions", name: "section_structure", status: "warn",
+        message: "#{bad_sections.size} intent file(s) have non-sanctioned ## sections",
+        details: bad_sections.map { |b| "#{b[:dir]}: #{b[:issues].join(", ")}" },
+        fixable: false
+      )
+    end
+
     checks
   end
 

package/scripts/hook-create-gate

@@ -0,0 +1,59 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# PreToolUse create gate (intent 60b): validate the PROPOSED content of a Write
+# to an intent file before it lands. Fires when the target path is an intent file
+# inside its own equally-named directory (store/<id>--<slug>/<id>--<slug>.md). It
+# validates the proposed content from the hook payload (tool_input.content), NOT
+# the on-disk file (which does not exist yet at PreToolUse), using IntentValidator
+# for born-complete frontmatter plus the sanctioned section structure.
+#
+# It depends ONLY on the stdin path + content, never on the auto-bridge or
+# CLAUDE_SESSION_ID, so it runs unconditionally (headless / background sessions).
+# It validates ONLY the intent file, never sentinel placeholder lifecycle files
+# (spec.md/plan.md/etc.); the path matcher excludes them.
+#
+# Exit 0 = allow. Exit 2 = block (reason on stderr, shown to the agent).
+#
+# Reads the Claude Code PreToolUse payload as JSON on STDIN:
+#   { "tool_input": { "file_path": "...", "content": "..." } }
+# Empty / unparseable / non-matching path => exit 0 (cannot judge, allow).
+# Matching path but missing content => exit 2 (fail-safe: refuse to allow an
+# unvalidated intent write).
+
+require "json"
+require_relative "lib/intent_validator"
+
+raw = $stdin.read rescue nil
+exit 0 if raw.nil? || raw.strip.empty?
+
+payload = JSON.parse(raw) rescue nil
+exit 0 unless payload.is_a?(Hash)
+
+path = payload.dig("tool_input", "file_path") || payload.dig("tool_params", "file_path")
+exit 0 if path.nil? || path.to_s.strip.empty?
+
+# Precise path matcher: the target must be an intent file inside its own
+# equally-named dir. Never matches sibling lifecycle files (spec.md, etc.) or
+# unrelated store files.
+abs = File.expand_path(path)
+dir = File.dirname(abs)
+is_intent_file = dir.match?(%r{/store/[^/]+--[^/]+\z}) &&
+                 File.basename(abs) == "#{File.basename(dir)}.md"
+exit 0 unless is_intent_file
+
+content = payload.dig("tool_input", "content") || payload.dig("tool_params", "content")
+if content.nil?
+  $stderr.puts "PLASTIC CREATE GATE — #{File.basename(abs)}: cannot read proposed content; " \
+               "refusing to allow an unvalidated intent write."
+  exit 2
+end
+
+result = IntentValidator.validate_content(content)
+exit 0 if result[:ok]
+
+$stderr.puts "PLASTIC CREATE GATE — #{File.basename(abs)} is not a valid intent:"
+result[:errors].each { |e| $stderr.puts "  #{e}" }
+$stderr.puts "Create intents via new-intent / plastic-creating-intent; do not hand-author them."
+exit 2

package/scripts/lib/bridge.rb

@@ -10,6 +10,14 @@ require "digest"
 module Bridge
   STAGES = %w[what why how exec done].freeze
 
+  # Placeholder sentinel (intent 60b). A scaffolded lifecycle file
+  # (spec.md/plan.md/checklist.md/outcome.md) carries this exact string as its
+  # first line until an agent fills the file and deletes the sentinel. The
+  # sentinel is the "stage not reached yet" marker, so stage detection treats a
+  # sentinel-marked file as absent (see stage_file_present?). The intent file
+  # (<id>--<slug>.md) is never sentineled; it is born complete.
+  PLACEHOLDER_SENTINEL = "<!-- plastic:placeholder -->"
+
   # Stale-bridge purge window (intent 67). The bridge file is ephemeral
   # live-session gate state, NOT a continuation source: an intent is resumed from
   # its savepoint.md ledger, never from a /tmp bridge. So any bridge older than
@@ -168,14 +176,28 @@ module Bridge
     raise e
   end
 
+  # True iff a lifecycle file is PRESENT AND REAL: it exists and its first line is
+  # not the placeholder sentinel. Reads only the file head (never the whole file)
+  # so the dashboard stays fast across many intents. Exact first-line match only,
+  # so a real file that merely contains an HTML comment later is unaffected, and a
+  # partially-edited sentinel reads as real rather than sticking as a placeholder.
+  def self.stage_file_present?(path)
+    return false unless File.exist?(path)
+    first = File.open(path, &:gets)
+    return true if first.nil? # empty file: present, not a sentinel
+    first.chomp != PLACEHOLDER_SENTINEL
+  rescue StandardError
+    File.exist?(path)
+  end
+
   def self.derive_stage(intent_dir)
-    return "done" if File.exist?("#{intent_dir}/outcome.md")
-    if File.exist?("#{intent_dir}/plan.md") &&
+    return "done" if stage_file_present?("#{intent_dir}/outcome.md")
+    if stage_file_present?("#{intent_dir}/plan.md") &&
        File.directory?("#{intent_dir}/actions") &&
-       File.exist?("#{intent_dir}/checklist.md")
+       stage_file_present?("#{intent_dir}/checklist.md")
       return "exec"
     end
-    return "how" if File.exist?("#{intent_dir}/spec.md")
+    return "how" if stage_file_present?("#{intent_dir}/spec.md")
     return "why" if File.exist?(intent_file(intent_dir))
     "what"
   end
@@ -183,8 +205,9 @@ module Bridge
   def self.has_files(intent_dir)
     files = []
     ifile = File.basename(intent_file(intent_dir))
-    [ifile, "spec.md", "plan.md", "checklist.md", "outcome.md"].each do |f|
-      files << f if File.exist?("#{intent_dir}/#{f}")
+    files << ifile if File.exist?("#{intent_dir}/#{ifile}")
+    ["spec.md", "plan.md", "checklist.md", "outcome.md"].each do |f|
+      files << f if stage_file_present?("#{intent_dir}/#{f}")
     end
     files << "actions/" if File.directory?("#{intent_dir}/actions")
     files
@@ -236,8 +259,12 @@ module Bridge
   # Append a milestone line for file_path if (and only if) it is a milestone
   # not already recorded. Returns true when a line was written, false otherwise.
   def self.append_savepoint(intent_dir, file_path, now: Time.now)
-    stage, milestone = savepoint_milestone(intent_dir, File.basename(file_path))
+    basename = File.basename(file_path)
+    stage, milestone = savepoint_milestone(intent_dir, basename)
     return false unless milestone
+    # A sentinel-marked lifecycle file logs NO milestone (the stage is not real
+    # yet). The intent file is never sentineled, so it still logs its What line.
+    return false unless stage_file_present?(File.join(intent_dir, basename))
     return false if savepoint_recorded_milestones(intent_dir).include?(milestone)
 
     line = "#{now.utc.iso8601}  #{stage}  #{milestone}\n"
@@ -254,7 +281,7 @@ module Bridge
     ]
     lines = ordered.filter_map do |basename|
       path = File.join(intent_dir, basename)
-      next unless File.exist?(path)
+      next unless stage_file_present?(path)
       stage, milestone = savepoint_milestone(intent_dir, basename)
       next unless milestone
       "#{File.mtime(path).utc.iso8601}  #{stage}  #{milestone}\n"
@@ -311,16 +338,16 @@ module Bridge
         return "Cannot start Why — What is incomplete (#{File.basename(ifile)} missing or no ## Intent)"
       end
     when "plan.md"
-      unless File.exist?("#{intent_dir}/spec.md")
+      unless stage_file_present?("#{intent_dir}/spec.md")
         return "Cannot start How — Why is incomplete (spec.md missing)"
       end
     when "checklist.md"
-      unless File.exist?("#{intent_dir}/plan.md") && File.directory?("#{intent_dir}/actions")
+      unless stage_file_present?("#{intent_dir}/plan.md") && File.directory?("#{intent_dir}/actions")
         return "Cannot complete How — plan.md or actions/ missing"
       end
     when "outcome.md"
       checklist = "#{intent_dir}/checklist.md"
-      if File.exist?(checklist)
+      if stage_file_present?(checklist)
         content = File.read(checklist)
         unchecked = content.scan(/^- \[ \]/).length
         if unchecked > 0
@@ -399,8 +426,8 @@ module Bridge
     # "How reached" = the plan triplet exists. Gate by artifact presence, not the
     # stage label (derive_stage returns "how" as soon as spec.md exists, before any
     # plan). Code edits stay blocked until plan.md + checklist.md are both present.
-    reached_how = File.exist?("#{intent_dir_abs}/plan.md") &&
-                  File.exist?("#{intent_dir_abs}/checklist.md")
+    reached_how = stage_file_present?("#{intent_dir_abs}/plan.md") &&
+                  stage_file_present?("#{intent_dir_abs}/checklist.md")
     return nil if reached_how
 
     file_abs = File.expand_path(file_path.to_s)

package/scripts/lib/installer_core.rb

@@ -166,11 +166,15 @@ class InstallerCore
 
     FileUtils.mkdir_p(plastic_home)
     FileUtils.mkdir_p(File.join(plastic_home, "scripts", "lib"))
+    FileUtils.mkdir_p(File.join(plastic_home, "templates"))
 
     core_files.each do |src, dest|
       src_path = File.join(package_root, src)
       dest_path = File.join(plastic_home, dest)
-      FileUtils.cp(src_path, dest_path) if File.exist?(src_path)
+      next unless File.exist?(src_path)
+
+      FileUtils.mkdir_p(File.dirname(dest_path))
+      FileUtils.cp(src_path, dest_path)
     end
 
     File.write(File.join(plastic_home, "VERSION"), "#{version}\n")
@@ -210,6 +214,13 @@ class InstallerCore
       "scripts/qmd-sync" => "scripts/qmd-sync",
       "scripts/lib/intent_validator.rb" => "scripts/lib/intent_validator.rb",
       "scripts/validate-intent" => "scripts/validate-intent",
+      "scripts/new-intent" => "scripts/new-intent",
+      "scripts/hook-create-gate" => "scripts/hook-create-gate",
+      "templates/intent.md" => "templates/intent.md",
+      "templates/spec.md" => "templates/spec.md",
+      "templates/plan.md" => "templates/plan.md",
+      "templates/checklist.md" => "templates/checklist.md",
+      "templates/outcome.md" => "templates/outcome.md",
       "scripts/spawn-preamble" => "scripts/spawn-preamble",
       "scripts/lib/store_provisioning.rb" => "scripts/lib/store_provisioning.rb",
       "scripts/provision-project-store" => "scripts/provision-project-store",
@@ -527,12 +538,25 @@ class InstallerCore
           { "type" => "command", "command" => "#{hook_dir}/plastic-savepoint", "statusMessage" => "Saving Plastic intent state..." },
         ],
       },
-      "PreToolUse" => {
-        "matcher" => "Write|Edit|NotebookEdit",
-        "hooks" => [
-          { "type" => "command", "command" => "#{hook_dir}/plastic-code-gate", "statusMessage" => "Checking lifecycle gate..." },
-        ],
-      },
+      # PreToolUse carries TWO plastic groups with distinct matchers: the
+      # code-gate (Write|Edit|NotebookEdit) and the create-gate (Write only, intent
+      # 60b). A single group cannot carry two matchers, so this event maps to a
+      # LIST of groups; the merge loop appends each (idempotent because the purge
+      # pass removes all prior plastic groups first).
+      "PreToolUse" => [
+        {
+          "matcher" => "Write|Edit|NotebookEdit",
+          "hooks" => [
+            { "type" => "command", "command" => "#{hook_dir}/plastic-code-gate", "statusMessage" => "Checking lifecycle gate..." },
+          ],
+        },
+        {
+          "matcher" => "Write",
+          "hooks" => [
+            { "type" => "command", "command" => "#{hook_dir}/plastic-create-gate", "statusMessage" => "Checking create gate..." },
+          ],
+        },
+      ],
       "PostToolUse" => {
         "matcher" => "Write|Edit",
         "hooks" => [
@@ -552,13 +576,23 @@ class InstallerCore
 
     plastic_hooks.each do |event, group|
       hooks[event] ||= []
-      existing = hooks[event].find { |g| g.is_a?(Hash) && g["hooks"].is_a?(Array) && g["hooks"].any? { |h| h["command"].to_s.include?("plastic-") } }
 
-      if existing
-        existing["matcher"] = group["matcher"]
-        existing["hooks"] = group["hooks"]
-      else
-        hooks[event] << group
+      # An event may map to a LIST of plastic groups (PreToolUse carries the
+      # code-gate AND the create-gate). The purge pass above already removed all
+      # prior plastic groups, so appending each desired group fresh is idempotent
+      # across re-runs and never collapses two matchers into one group.
+      groups = group.is_a?(Array) ? group : [group]
+      groups.each do |g|
+        existing = hooks[event].find do |h|
+          h.is_a?(Hash) && h["matcher"] == g["matcher"] &&
+            h["hooks"].is_a?(Array) && h["hooks"].any? { |x| x["command"].to_s.include?("plastic-") }
+        end
+
+        if existing
+          existing["hooks"] = g["hooks"]
+        else
+          hooks[event] << g
+        end
       end
     end
 

package/scripts/lib/intent_validator.rb

@@ -27,6 +27,12 @@ module IntentValidator
   # Fields whose value must be a well-formed array of valid id strings.
   ARRAY_ID_FIELDS = %w[sources chain].freeze
 
+  # Sanctioned top-level intent sections, in order (intent 60b). The only
+  # sanctioned `###` subsection is `### Decisions`, which is OPTIONAL (added after
+  # brainstorming) and therefore never flagged as missing. This is the single
+  # definition shared by the create gate, the validate-intent CLI, and doctor.
+  SANCTIONED_SECTIONS = ["## Intent", "## Context", "## Outcome", "## Insights", "## Links"].freeze
+
   # Folgezettel id form: digits then an optional lowercase-letter/digit suffix
   # (for example "14", "14a", "4a1"). Mirrors scripts/folgezettel-id.
   ID_PATTERN = /\A([a-z0-9-]+:)?\d+[a-z0-9]*\z/
@@ -42,8 +48,15 @@ module IntentValidator
   def parse_frontmatter(path)
     return nil unless File.exist?(path)
 
-    content = File.read(path)
-    return nil unless content.start_with?("---")
+    parse_frontmatter_text(File.read(path))
+  rescue StandardError
+    nil
+  end
+
+  # PURE: parse YAML frontmatter from a content STRING (no file IO). Returns the
+  # parsed Hash, {} for an empty block, or nil when there is no parseable block.
+  def parse_frontmatter_text(content)
+    return nil unless content.is_a?(String) && content.start_with?("---")
 
     parts = content.split("---", 3)
     return nil if parts.length < 3
@@ -53,6 +66,32 @@ module IntentValidator
     nil
   end
 
+  # PURE: strip the leading YAML frontmatter block from a content STRING,
+  # returning the body text (everything after the closing `---`). When there is
+  # no frontmatter block, the whole content is the body.
+  def body_of(content)
+    return "" unless content.is_a?(String)
+    return content unless content.start_with?("---")
+
+    parts = content.split("---", 3)
+    parts.length < 3 ? content : parts[2]
+  end
+
+  # PURE: given the intent file body text, return sanctioned-section findings.
+  # Flags any unknown top-level `## ` heading and any missing sanctioned section.
+  # Ignores `### ` subsections entirely (Decisions is optional and lives under
+  # Context). Returns { ok:, missing: [section names], unknown: [heading strings] }.
+  def validate_sections(body)
+    headings = body.to_s.lines.filter_map do |l|
+      s = l.strip
+      s if s.start_with?("## ") && !s.start_with?("### ")
+    end
+    present = headings & SANCTIONED_SECTIONS
+    missing = SANCTIONED_SECTIONS - present
+    unknown = headings - SANCTIONED_SECTIONS
+    { ok: missing.empty? && unknown.empty?, missing: missing, unknown: unknown }
+  end
+
   # PURE: given a parsed frontmatter Hash (or nil), return
   # { ok: Boolean, missing: [field names], errors: [human strings] }.
   def validate_frontmatter(fm)
@@ -80,11 +119,38 @@ module IntentValidator
     { ok: missing.empty? && errors.empty?, missing: missing, errors: errors }
   end
 
-  # Resolve an intent directory's primary md file and validate its frontmatter.
-  # `plastic_home` is accepted for house-style parity (injectable) even though
-  # validation reads the intent dir directly.
+  # PURE: combine the frontmatter result with section-structure findings for a
+  # content STRING. Returns the frontmatter result hash extended with
+  # :section_missing, :section_unknown, and folded section errors; :ok is the AND
+  # of frontmatter and sections. Lets the create gate validate proposed content
+  # (no file on disk) with the same definition as the CLI and doctor.
+  def validate_content(content)
+    fm_result = validate_frontmatter(parse_frontmatter_text(content))
+    sections = validate_sections(body_of(content))
+    merge_sections(fm_result, sections)
+  end
+
+  # Fold section findings into a frontmatter result hash (shared by validate and
+  # validate_content). Does not mutate the input.
+  def merge_sections(fm_result, sections)
+    errors = fm_result[:errors].dup
+    sections[:unknown].each { |h| errors << "unknown section: #{h}" }
+    sections[:missing].each { |s| errors << "missing required section: #{s}" }
+    {
+      ok: fm_result[:ok] && sections[:ok],
+      missing: fm_result[:missing],
+      errors: errors,
+      section_missing: sections[:missing],
+      section_unknown: sections[:unknown],
+    }
+  end
+
+  # Resolve an intent directory's primary md file and validate its frontmatter
+  # AND its sanctioned section structure. `plastic_home` is accepted for
+  # house-style parity (injectable) even though validation reads the dir directly.
   def validate(intent_dir, plastic_home: File.join(Dir.home, ".plastic"))
     md_path = File.join(intent_dir, "#{File.basename(intent_dir)}.md")
-    validate_frontmatter(parse_frontmatter(md_path))
+    content = File.exist?(md_path) ? File.read(md_path) : nil
+    validate_content(content)
   end
 end

package/scripts/new-intent

@@ -0,0 +1,177 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# new-intent (intent 60b) - the one-call scaffolding contract.
+#
+# A single invocation scaffolds a COMPLETE intent: it allocates the Folgezettel
+# id (root vs branch by --parent), creates the directory tree (<id>--<slug>/ plus
+# actions/ and resources/), renders the born-complete intent file from
+# templates/intent.md, writes sentinel placeholder lifecycle files (spec.md,
+# plan.md, checklist.md, outcome.md, each carrying <!-- plastic:placeholder -->
+# as its first line), wires reciprocal file links, and self-validates with
+# IntentValidator (exit non-zero if not born complete).
+#
+# It does NOT touch INDEX.md, git, or project creation: those remain skill/agent
+# responsibilities (see plastic-creating-intent).
+#
+# Usage:
+#   new-intent --store <store_path> --intent "<one-line>" --slug <slug> \
+#              [--parent <id>] [--author <name>] [--sources id,id] \
+#              [--tags tag,tag] [--templates <dir>]
+#
+# Exit codes: 0 (born complete), 1 (scaffold failed self-validation or bad input).
+
+require "fileutils"
+require "date"
+require_relative "lib/bridge"
+require_relative "lib/intent_validator"
+
+# --- Explicit flag parsing (no eval, no global injection) ------------------
+
+def parse_args(argv)
+  opts = {
+    store: nil, intent: nil, slug: nil, parent: nil,
+    author: "claude-code", sources: [], tags: [], templates: nil
+  }
+  i = 0
+  while i < argv.length
+    arg = argv[i]
+    case arg
+    when "--store"     then opts[:store] = argv[i += 1]
+    when "--intent"    then opts[:intent] = argv[i += 1]
+    when "--slug"      then opts[:slug] = argv[i += 1]
+    when "--parent"    then opts[:parent] = argv[i += 1]
+    when "--author"    then opts[:author] = argv[i += 1]
+    when "--sources"   then opts[:sources] = split_list(argv[i += 1])
+    when "--tags"      then opts[:tags] = split_list(argv[i += 1])
+    when "--templates" then opts[:templates] = argv[i += 1]
+    else
+      abort "new-intent: unknown argument #{arg.inspect}"
+    end
+    i += 1
+  end
+  opts
+end
+
+def split_list(value)
+  value.to_s.split(",").map(&:strip).reject(&:empty?)
+end
+
+def expand(path)
+  File.expand_path(path.to_s.sub(/\A~/, Dir.home))
+end
+
+# Default templates dir: sibling of this script's dir. Works in-repo
+# (<repo>/scripts/new-intent -> <repo>/templates) and installed
+# (~/.plastic/scripts/new-intent -> ~/.plastic/templates when present).
+def default_templates_dir
+  File.expand_path("../templates", __dir__)
+end
+
+def render_tokens(text, tokens)
+  tokens.reduce(text) { |acc, (k, v)| acc.gsub("{{#{k}}}", v.to_s) }
+end
+
+# Append a wikilink line under the file's `## Links` section, idempotently.
+def append_link(file_path, link_line)
+  return unless File.exist?(file_path)
+  content = File.read(file_path)
+  return if content.include?(link_line)
+
+  lines = content.lines
+  idx = lines.index { |l| l.strip == "## Links" }
+  return unless idx
+
+  insert_at = lines.length
+  ((idx + 1)...lines.length).each do |j|
+    if lines[j].strip.start_with?("## ")
+      insert_at = j
+      break
+    end
+  end
+  lines.insert(insert_at, "#{link_line}\n")
+  File.write(file_path, lines.join)
+end
+
+def main(argv)
+  opts = parse_args(argv)
+  abort "new-intent: --store is required" if opts[:store].nil? || opts[:store].empty?
+  abort "new-intent: --intent is required" if opts[:intent].nil? || opts[:intent].empty?
+  abort "new-intent: --slug is required" if opts[:slug].nil? || opts[:slug].empty?
+
+  store = expand(opts[:store])
+  abort "new-intent: store dir does not exist: #{store}" unless Dir.exist?(store)
+
+  templates = opts[:templates] ? expand(opts[:templates]) : default_templates_dir
+  abort "new-intent: templates dir not found: #{templates}" unless Dir.exist?(templates)
+
+  # 1. Allocate id via the existing folgezettel-id logic (root vs branch).
+  folg = File.expand_path("folgezettel-id", __dir__)
+  cmd = [folg, store]
+  cmd << opts[:parent] if opts[:parent] && !opts[:parent].empty?
+  id = `#{cmd.map { |c| "'#{c}'" }.join(" ")}`.strip
+  abort "new-intent: id allocation failed" if id.empty?
+
+  slug = opts[:slug]
+  intent_dir = File.join(store, "#{id}--#{slug}")
+  abort "new-intent: #{intent_dir} already exists" if File.exist?(intent_dir)
+
+  # 2. Create dirs.
+  FileUtils.mkdir_p(File.join(intent_dir, "actions"))
+  FileUtils.mkdir_p(File.join(intent_dir, "resources"))
+
+  # 3. Render the born-complete intent file from templates/intent.md.
+  sources = opts[:sources]
+  sources = sources | [opts[:parent]] if opts[:parent] && !opts[:parent].empty? && !sources.include?(opts[:parent])
+  sources_str = sources.map { |s| "\"#{s}\"" }.join(", ")
+  tags_str = opts[:tags].map { |t| "\"#{t}\"" }.join(", ")
+
+  intent_template = File.read(File.join(templates, "intent.md"))
+  intent_body = render_tokens(intent_template, {
+    "ID" => id,
+    "INTENT" => opts[:intent],
+    "SOURCES" => sources_str,
+    "DATE" => Date.today.iso8601,
+    "AUTHOR" => opts[:author],
+    "TAGS" => tags_str,
+    "DESCRIPTION" => opts[:intent],
+  })
+  intent_file = File.join(intent_dir, "#{id}--#{slug}.md")
+  File.write(intent_file, intent_body)
+
+  # 4. Reciprocal links: forward link to parent + back-reference in the parent.
+  if opts[:parent] && !opts[:parent].empty?
+    parent_id = opts[:parent]
+    append_link(intent_file, "- [[#{parent_id}]]")
+    parent_dir = Dir.glob(File.join(store, "#{parent_id}--*")).find { |d| File.directory?(d) }
+    if parent_dir
+      parent_file = File.join(parent_dir, "#{File.basename(parent_dir)}.md")
+      append_link(parent_file, "- [[#{id}]]")
+    end
+  end
+
+  # 5. Sentinel placeholders for each lifecycle file. The sentinel is the FIRST
+  # line; the rendered template body follows so the file is a usable starting
+  # point once an agent deletes the sentinel.
+  %w[spec.md plan.md checklist.md outcome.md].each do |name|
+    template_path = File.join(templates, name)
+    body = File.exist?(template_path) ? File.read(template_path) : ""
+    body = render_tokens(body, { "INTENT_NAME" => opts[:intent] })
+    File.write(File.join(intent_dir, name), "#{Bridge::PLACEHOLDER_SENTINEL}\n#{body}")
+  end
+
+  # 6. Self-validate (frontmatter + sanctioned sections).
+  result = IntentValidator.validate(intent_dir)
+  unless result[:ok]
+    warn "new-intent: scaffolded intent is NOT born complete:"
+    result[:missing].each { |f| warn "  missing field: #{f}" }
+    result[:errors].each { |e| warn "  #{e}" }
+    exit 1
+  end
+
+  puts intent_dir
+  exit 0
+end
+
+main(ARGV) if $PROGRAM_NAME == __FILE__

package/skills/creating-intent/SKILL.md

@@ -41,63 +41,60 @@ When creating a tactical intent in a project store:
 - **Global:** `~/.plastic/store/`
 - **Project:** `~/.plastic/projects/{slug}/store/`
 
-### 2. Determine Folgezettel ID
+### 2. Decide Branch vs Root
 
-IDs are scoped to the store they live in. Use the correct store path:
+Decide this BEFORE scaffolding, because it sets whether you pass `--parent`.
+Having a "parent" in mind does NOT automatically mean branch. Choose by meaning:
 
-**Global store:**
-```bash
-"${CLAUDE_PLUGIN_ROOT}/scripts/folgezettel-id" "~/.plastic/store"
-```
-
-**Project store:**
-```bash
-"${CLAUDE_PLUGIN_ROOT}/scripts/folgezettel-id" "~/.plastic/projects/{slug}/store"
-```
-
-**Branch intent (has parent, either store):**
-```bash
-"${CLAUDE_PLUGIN_ROOT}/scripts/folgezettel-id" "<STORE>" "<parent_id>"
-```
-
-**Branch vs root — decide before assigning the ID.** 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.
-- **Root (`15`, `16`)** — an independent thought, even if inspired by another intent.
-  Capture the inspiration in `sources` (e.g., `sources: ["14"]`), not in the ID.
+- **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.
+  set `--sources`. Only branch when it genuinely cannot stand alone.
 
 ### 3. Determine Intent Properties
 
 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**: array of Folgezettel IDs that influenced this intent (e.g., `["4a1"]`)
-- **chain**: starts empty `[]`, populated when this intent spawns others
+- **sources**: Folgezettel ids that influenced this intent (e.g., `4a1`). For a
+  project intent, include the governing intent's id.
 - **tags**: freeform list (use `project-<name>` for project membership)
 
-Place in `## Active` or `## Future` in INDEX.md (status is convention-derived, not a frontmatter field).
+`chain` starts empty and is populated later when this intent spawns others.
+Place the intent in `## Active` or `## Future` in INDEX.md (status is
+convention-derived, not a frontmatter field).
 
-### 4. Create Directory and Files
+### 4. Scaffold via new-intent (single call)
+
+Delegate id allocation, directory and file creation, the born-complete intent
+file, the sentinel placeholder lifecycle files, the reciprocal file links, and
+self-validation to one `new-intent` invocation. Do NOT hand-author any of these
+files.
 
 ```bash
-mkdir -p <STORE>/ID--slug
+"${CLAUDE_PLUGIN_ROOT}/scripts/new-intent" \
+  --store "<STORE>" --intent "<one-line>" --slug "<slug>" \
+  [--parent "<parent_id>"] [--author "<author>"] \
+  [--sources "id,id"] [--tags "project-<slug>,tag"]
 ```
 
-Write `{ID}--{slug}.md` using the intent template. For project intents, add the governing intent's ID to `sources` and add `[[global:ID]]` backlink in `## Links`.
-
-### 5. Self-Verify the Written Intent
+`new-intent` allocates the Folgezettel id (root, or a branch of `--parent`),
+creates `<STORE>/<id>--<slug>/` plus `actions/` and `resources/`, renders the
+born-complete `<id>--<slug>.md` from the intent template, writes the sentinel
+placeholder `spec.md`/`plan.md`/`checklist.md`/`outcome.md` (each marked
+`<!-- plastic:placeholder -->` so no stage detector reads them as reached), wires
+the reciprocal `[[id]]` links, and self-validates (frontmatter plus the sanctioned
+`##` sections). It prints the created directory path and exits 0.
 
-Before announcing or committing, verify the just-written intent is born complete:
-
-```bash
-"${CLAUDE_PLUGIN_ROOT}/scripts/validate-intent" "<STORE>/ID--slug"
-```
+It does NOT touch INDEX.md, git, or project creation: those stay in this skill
+(steps 6 to 9 below).
 
-If it exits non-zero, read the stderr report, inject the missing field(s) into the `{ID}--{slug}.md` frontmatter (for example add `chain: []`) WITHOUT disturbing other frontmatter keys, and re-run `validate-intent` until it exits 0. Only then proceed to the remaining steps (project spawn, INDEX.md, commit, announce).
+If `new-intent` exits non-zero, read the stderr report and fix the inputs (slug,
+intent, sources). Do not commit or announce an intent that did not scaffold
+cleanly, and do not work around the failure by hand-writing the files.
 
 ### 6. If Implementation Intent Spawns a Project
 
@@ -138,12 +135,12 @@ Add to `## Active` (or `## Future`) and appropriate cluster.
 ### 8. Auto-commit
 
 ```bash
-cd <store-root> && git add . && git commit -m "feat: create intent ID — [name]"
+cd <store-root> && git add . && git commit -m "feat: create intent ID - [name]"
 ```
 
 ### 9. Announce
 
-"Created intent ID — [name]. Placed in: [Active|Future]. Store: [global|project:<slug>|local]."
+"Created intent ID - [name]. Placed in: [Active|Future]. Store: [global|project:<slug>|local]."
 
 ## References
 

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

@@ -64,11 +64,10 @@ State is derived from what exists, not from what's declared.
 ## Creating an Intent — Full Steps
 
 1. Determine the target store: `~/.plastic/store/` for global intents (default), `~/.plastic/projects/{slug}/store/` for project intents
-2. Determine the Folgezettel ID: If root (no parent), find highest root number +1. If branch, run `"${CLAUDE_PLUGIN_ROOT}/scripts/folgezettel-id" <parent_id> <store_path>`
-3. Create the intent directory in the chosen store (e.g., `ID--three-to-five-words`)
-4. Create `{ID}--{slug}.md` with frontmatter (id, intent, sources, chain, created, author, tags)
-5. Write `## Intent` — the What
-6. Add remaining sections: `## Context`, `## Outcome`, `## Insights`, `## Links`
-7. Update the appropriate `INDEX.md` — add to Active section and appropriate cluster
-
-A fleeting intent can skip `## Context` — just `## Intent` and empty sections.
+2. Decide branch vs root (this sets whether you pass `--parent`)
+3. Scaffold with one call: `"${CLAUDE_PLUGIN_ROOT}/scripts/new-intent" --store <store> --intent "<one-line>" --slug <slug> [--parent <id>] [--sources id,id] [--tags ...]`. This allocates the id, creates the directory plus `actions/` and `resources/`, renders the born-complete intent file (frontmatter plus `## Intent`, `## Context`, `## Outcome`, `## Insights`, `## Links`), writes the sentinel placeholder lifecycle files, wires the reciprocal links, and self-validates.
+4. Update the appropriate `INDEX.md` — add to Active section and appropriate cluster
+
+The intent file is born complete with all five sanctioned `##` sections; the lifecycle files (`spec.md`/`plan.md`/`checklist.md`/`outcome.md`) are sentinel placeholders that read as "stage not reached" until an agent fills them and deletes the `<!-- plastic:placeholder -->` first line.
+
+Always scaffold through `new-intent` (or this skill). Never hand-author intent files: the write-time create gate blocks an incomplete or malformed intent file, and hand-authoring is the bypass this contract is designed to remove.