@zalom/plastic 2.0.0-alpha.20 → 2.0.0-alpha.22

package/PLASTIC.md

@@ -3,7 +3,7 @@
 > **This file is maintained by Plastic.** It is overwritten on update; do not edit it. Project
 > rules go in `AGENTS.md`. Deeper doctrine lives in the six `plastic-conventions` chapters
 > (`references/<chapter>.md`: knowledge-graph, lifecycle-and-savepoints, locks-and-worktrees,
-> completion-and-done, maintenance-and-revisions, roadmaps), read on demand.
+> completion-and-done, maintenance-and-revisions, roadmaps).
 
 ## Two Modes, Plus Auto
 
@@ -43,20 +43,20 @@ IDs follow Luhmann's alternating convention (`1`, `1a`, `1a1`, `1a1a`); siblings
 
 ## The Record: Stages as its Shape
 
-| Stage | Section | Deliverable | Skill |
-|---|---|---|---|
-| **What** | `## Intent` | `{ID}--{slug}.md` | `plastic-intent-creating` |
-| **Why** | `## Context` + Decisions | `spec.md` | `plastic-intent-speccing` (thinking mode) |
-| **How** | `checklist.md` + `actions/` | `plan.md` | `plastic-intent-speccing` writes the action files |
-| **Exec** | `## Outcome` | `outcome.md` | `plastic-intent-executing`; `plastic-intent-ending` closes |
+| Stage | Section | Skill |
+|---|---|---|
+| **What** | `## Intent` | `plastic-intent-creating` |
+| **Why** | `## Context` + Decisions | `plastic-intent-speccing` (optional) |
+| **How** | `graph.md` + `nodes/` | `plastic-intent-speccing` |
+| **Exec** | `## Outcome` | `plastic-intent-executing` drives the runner loop; `plastic-intent-ending` closes |
 
-Stages are the shape of the record, not checkpoints: nothing blocks a write. Only "how to
-execute" (a checklist item plus its action) must exist before work; the rest is backfilled at
-intent end from what was recorded while working.
+Stages are the shape of the record, not checkpoints: nothing blocks a write. Work runs on
+`graph.md` and `nodes/`, driven by `runner step` (dispatch), `runner status` (read the
+ledger), and `runner answer` (close a `needs_decision` node). `spec.md` stays optional;
+`plan.md` and `checklist.md` exist only for a legacy intent with no `graph.md`.
 
 Invoke a skill for your harness: Claude Code uses the slash form (`/plastic-intent-creating`);
-Codex CLI uses a dollar prefix instead (`$plastic-intent-creating`), and may also select a skill
-implicitly by matching its description.
+Codex CLI uses a dollar prefix instead (`$plastic-intent-creating`), and may also select a skill implicitly by matching its description.
 
 `## Insights` is the append-only log of durable discoveries from every stage, newest at the
 bottom, never prepended, each entry prefixed `{utc-iso8601} · {stage} · {author}`. Write
@@ -71,8 +71,8 @@ An auto team is `plastic-enforcer` (the lead) plus `plastic-executor`; models li
 Twenty skills, each `plastic-<name>`, listed by your harness. `plastic-doctor` checks
 installation health (core, store, and full scopes). `plastic-feedback` turns a Plastic quirk,
 bug, or feature idea into a redacted local report and a prefilled GitHub issue URL; only the
-user submits it. If the user hits one, offer to invoke the plastic-feedback skill yourself
-instead of waiting to be asked. A release is a collection of intents; `plastic-releasing`
+user submits it. If the user hits one, offer to invoke the plastic-feedback skill yourself.
+A release is a collection of intents; `plastic-releasing`
 runs the flow. A roadmap is an ordered, delivery-side collection; `plastic-roadmap` owns it.
 
 ## State System
@@ -108,8 +108,10 @@ the store root, so the id allocator and every 1.x store walker skip them.
 2. Artifacts go in the intent directory, never in `docs/plans/` or `docs/specs/`: code goes in
    the project, everything else in the intent. Capture observations in `## Insights`; at the
    end write `outcome.md` and `## Outcome`, and update INDEX.md.
-3. State is derived from what exists: `outcome.md` present means done, so never write it
-   before the checklist is fully checked. Status lives on checklist items, not intents.
+3. State is derived from what exists: `outcome.md` present means the intent is closed, so
+   never write it before every node in `graph.md` reaches a terminal status (checklist.md
+   fully checked, for a legacy intent). Status lives on graph nodes or checklist items,
+   never on intents.
 4. The global store is never pushed (`~/.plastic/` holds sensitive data); agent-created repos
    are private by default (`gh repo create --private`).
 5. Intents are created only via `plastic-intent-creating`, never hand-authored. It
@@ -137,5 +139,5 @@ treating work as new. Enola, or Serena when Enola is absent: prefer its symbol r
 Locks and worktrees exist only for auto teams. One team develops an intent at a time: a
 session-keyed `delivery.lock` in the intent directory, alive while its mtime lease is fresh.
 Code edits happen in the intent's worktree (`<repo>/.claude/worktrees/{id}--{slug}`, branch
-`plastic/{id}--{slug}`). "Done" is three signals that agree: INDEX `## Completed` or
-`## Abandoned`, `outcome.md`, and the savepoint `Done` line; INDEX wins on conflict.
+`plastic/{id}--{slug}`). A terminal intent is three signals that agree: INDEX
+`## Completed`/`## Abandoned`, `outcome.md`, and the terminal savepoint line; INDEX wins.

package/bin/test

@@ -2,7 +2,10 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 
-# Runs the FULL Minitest suite in a single process.
+# Runs the Minitest suite in a single process, either the whole suite or a
+# named subset via --only (intent 355, n4, D5). Every run, named or full,
+# goes through FailuresReporter, so a green run costs one line and a red run
+# prints only the failures plus that line, never a dot per test.
 #
 # `release.verify` used to be `ruby -Itest test/*_test.rb`, but Ruby runs only
 # the first glob-expanded file as the program — the rest land in ARGV and are
@@ -12,17 +15,34 @@
 # loaded.
 
 root = File.expand_path("..", __dir__)
-
-files = Dir.glob(File.join(root, "test", "**", "*_test.rb")).sort
-abort "No test files found under #{File.join(root, "test")}" if files.empty?
+discover = -> { Dir.glob(File.join(root, "test", "**", "*_test.rb")).sort }
 
 # `bin/test --list` prints the discovered files without running them, so the
 # discovery logic can be tested cheaply (no full-suite execution).
 if ARGV.delete("--list")
+  files = discover.call
+  abort "No test files found under #{File.join(root, "test")}" if files.empty?
   puts files.map { |f| f.sub("#{root}/", "") }
   exit 0
 end
 
+only_index = ARGV.index("--only")
+if only_index
+  named = ARGV.slice!(only_index..-1)
+  named.shift
+  abort "--only requires at least one test file" if named.empty?
+  files = named.map { |f| File.expand_path(f, root) }
+  missing = files.reject { |f| File.exist?(f) }
+  unless missing.empty?
+    warn "no such test file: #{missing.map { |f| f.sub("#{root}/", "") }.join(', ')}"
+    exit 2
+  end
+else
+  files = discover.call
+  abort "No test files found under #{File.join(root, "test")}" if files.empty?
+end
+
 $LOAD_PATH.unshift File.join(root, "test")
+require_relative "../test/lib/failures_reporter"
 require "minitest/autorun"
 files.each { |f| require f }

package/hooks/call-budget

@@ -0,0 +1,4 @@
+#!/bin/bash
+INPUT=$(cat)
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+echo "$INPUT" | env -u RUBYOPT ruby --disable-gems "$SCRIPT_DIR/../scripts/hook-call-budget"

package/hooks/hooks.json

@@ -17,6 +17,18 @@
         ]
       }
     ],
+    "PreToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook\" call-budget",
+            "statusMessage": ""
+          }
+        ]
+      }
+    ],
     "PreCompact": [
       {
         "matcher": "",

package/package.json

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

package/scripts/doctor.rb

@@ -631,6 +631,11 @@ class Doctor
     # ReadySet's own require chain is 65,648 bytes, far past that budget.
     checks.concat(node_graph_checks(intent_dirs))
 
+    # unpromoted_rules (intent 341, G8, C37): an Insights entry tagged
+    # `rule:` (via `insight-append --rule`) is a promise the rule will make
+    # it into project doctrine. Advisory only.
+    checks.concat(unpromoted_rules_checks(intent_dirs, home: Dir.home))
+
     # cross_store_resolution — RESOLVES (not just shape-checks) every cross-store
     # `store:id` ref against the FULL store family via the relocation map
     # (relocation consulted first), closing the shape-only gap i1/i3/i4 leave open.
@@ -795,7 +800,11 @@ def done_signal_findings_for_dir(dir, label:, scope:, dirname:, terminal:, activ
     # written from the record by `scaffold-intent backfill`, so this is repairable and
     # reported as a fixable warn (backfilled_complete). Its exclusions go to their OWN
     # bucket so savepoint_operational's consumed/dead-row bookkeeping above never sees them.
-    backfill_gaps = %w[spec.md plan.md].reject { |f| Savepoint.stage_file_present?(File.join(dir, f)) }
+    # A graph intent (real graph.md on disk) never carries spec.md or plan.md by design
+    # (D1, no ceremonies, intent 341): the graph IS the spec and the plan, so a missing one
+    # is never a gap here.
+    is_graph_intent = File.exist?(File.join(dir, "graph.md"))
+    backfill_gaps = is_graph_intent ? [] : %w[spec.md plan.md].reject { |f| Savepoint.stage_file_present?(File.join(dir, f)) }
     # Name whichever directory the intent actually used (post-execution
     # review, non-blocking 8), consistent with Savepoint.missing_for_stage:
     # a nodes/ directory on disk means the intent chose the node-graph
@@ -853,7 +862,7 @@ def check_done_signals(scopes: nil)
       projection = IndexProjection.analyze(store[:store_dir], index_path: store[:index])
       projection[:drift].each do |row|
         index_drift << "#{store[:scope]}: #{row[:id]} - INDEX says #{row[:index_status]}, " \
-                        "the ledger's last Done line says #{row[:ledger_status]}"
+                        "the ledger's last line says #{row[:ledger_status]}"
       end
     end
 
@@ -1097,7 +1106,7 @@ def check_done_signals(scopes: nil)
       fix_hint: "For a live (Active) intent, rebuild the ledger via " \
                 "Savepoint.rebuild_savepoint. Terminal (Completed/Abandoned) intents are immutable: " \
                 "a phantom there stays advisory unless an explicit human grant authorizes the " \
-                "124a manual Done-bookend repair."
+                "124a manual terminal-bookend repair."
     )
   end
 
@@ -1294,9 +1303,13 @@ end
   end
 
   INTENT_END_LIFECYCLE_FILES = %w[spec.md plan.md checklist.md outcome.md].freeze
+  # A graph intent (D1, no ceremonies, intent 341) never carries spec.md, plan.md, or
+  # checklist.md by design; the graph IS the spec and the plan. outcome.md stays mandatory.
+  GRAPH_INTENT_LIFECYCLE_FILES = %w[outcome.md].freeze
 
   def intent_lifecycle_artifacts_check(intent_dir, disposition)
-    missing = INTENT_END_LIFECYCLE_FILES.select { |f| !Savepoint.stage_file_present?(File.join(intent_dir, f)) }
+    files = File.exist?(File.join(intent_dir, "graph.md")) ? GRAPH_INTENT_LIFECYCLE_FILES : INTENT_END_LIFECYCLE_FILES
+    missing = files.select { |f| !Savepoint.stage_file_present?(File.join(intent_dir, f)) }
     unless Savepoint.stage_file_present?(Savepoint.intent_file(intent_dir))
       missing = [File.basename(Savepoint.intent_file(intent_dir))] + missing
     end
@@ -1774,6 +1787,68 @@ end
     end
   end
 
+  # --- Check: unpromoted rule: findings (intent 341, G8, C37) ---------------
+  #
+  # `insight-append --rule` tags an entry "... - rule: <text>". A tag is a
+  # promise the rule will make it into project doctrine; until the exact
+  # rule text shows up in some skills/conventions/references/*.md chapter,
+  # it is only visible to a session that happens to read this one intent
+  # file, and the next session repeats the mistake the rule names. Advisory
+  # only (warn, never fail): a freshly tagged rule is not yet promoted by
+  # design, and nothing here can auto-promote it (that is an editorial call,
+  # not a mechanical one).
+  RULE_ENTRY_RE = /—\s*rule:\s*(.+?)\s*\z/.freeze
+
+  def unpromoted_rules_checks(intent_dirs, package_root: PACKAGE_ROOT, home: nil)
+    # The installed doctor runs from ~/.plastic/scripts, so PACKAGE_ROOT
+    # (~/.plastic) has no skills/ directory: the conventions chapters install
+    # to the agent home layout instead. `home` is caller-injected (never an
+    # ENV read here) so this stays hermetic in tests; the real call site
+    # passes the process's actual home directory.
+    chapter_dirs = []
+    if home
+      chapter_dirs << File.join(home, ".claude", "skills", "plastic-conventions", "references")
+      chapter_dirs << File.join(home, ".agents", "skills", "plastic-conventions", "references")
+    end
+    chapter_dirs << File.join(package_root, "skills", "conventions", "references")
+
+    chapters_text = chapter_dirs.select { |d| Dir.exist?(d) }
+                                .flat_map { |d| Dir.glob(File.join(d, "*.md")) }
+                                .map { |f| File.read(f) }
+                                .join("\n\n")
+
+    unpromoted = []
+    intent_dirs.each do |d|
+      md_path = File.join(d[:path], "#{d[:name]}.md")
+      next unless File.exist?(md_path)
+
+      File.readlines(md_path).each do |line|
+        m = line.chomp.match(RULE_ENTRY_RE)
+        next unless m
+
+        rule_text = m[1].strip
+        next if rule_text.empty?
+
+        unpromoted << "#{tilde(d[:path])}: #{rule_text}" unless chapters_text.include?(rule_text)
+      end
+    end
+
+    if unpromoted.empty?
+      [check(
+        category: "conventions", name: "unpromoted_rules", status: "pass",
+        message: "Every tagged rule: finding is carried by a conventions chapter"
+      )]
+    else
+      [check(
+        category: "conventions", name: "unpromoted_rules", status: "warn",
+        message: "#{unpromoted.size} tagged rule(s) not yet carried by any conventions chapter",
+        details: unpromoted, fixable: false,
+        fix_hint: "Promote the rule into the right skills/conventions/references/*.md chapter, " \
+                  "or drop the tag if the finding does not belong in doctrine"
+      )]
+    end
+  end
+
   # --- Check category 3: Agent registration ---
 
 

package/scripts/hook-call-budget

@@ -0,0 +1,222 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Usage: hook-call-budget (reads the PreToolUse stdin JSON payload)
+#
+# Intent 355, n2 (review fix n8). A node gets a call budget by kind
+# (RunnerPolicy.call_cap): a cap on tool calls per attempt. RunnerDispatch
+# writes the cap onto the running line as `calls=` and states it as one
+# sentence in the node's own input, so the executor learns the number before
+# it ever gets denied.
+#
+# Inside a subagent the hook input's session_id and transcript_path are the
+# MAIN session's, never the subagent's own (v1 finding). So this hook caps
+# ONLY a subagent call: agent_id present in the payload. A call with no
+# agent_id (the main thread, a plain conversation, a live --agent session's
+# own turns) is never capped and the decision returns before any file is
+# touched.
+#
+# Which node a subagent is working is read from the subagent's OWN
+# transcript, at <dirname(transcript_path)>/<session_id>/subagents/
+# agent-<agent_id>.jsonl (the main transcript_path plus the main session_id
+# plus the subagent's own agent_id): its first user record carries the
+# dispatch prompt, and the lead/spawn block always pastes the node's packet
+# path into that prompt (PACKET_PATH_RE). The packet path names the intent
+# directory directly (its grandparent), so this hook never scans the store to
+# find it. No packet path in that first prompt means allow.
+#
+# The cap applies only when that node's LATEST transition line in
+# <intent>/savepoint.md is `running` and carries `calls=`; a later `done` or
+# `failed_verification` line (or a sibling node's own running line) means no
+# cap. Past the cap, a Bash call that runs only a safe git verb (add, commit,
+# status, rev-parse, log) is still allowed, so the denial the hook itself
+# orders (commit what is green) is never the thing the hook blocks.
+#
+# Pure and dependency-injected down to the paths it reads; the trailing block
+# guarded by `$PROGRAM_NAME == __FILE__` is this file's only I/O (stdin,
+# stdout), so a test can `load` this file and call HookCallBudget's module
+# functions directly without spawning a process or touching stdin.
+
+require "json"
+require_relative "lib/node_ledger"
+require_relative "lib/savepoint"
+
+module HookCallBudget
+  module_function
+
+  RETURN_INSTRUCTION = "commit what is green and return failed_verification reason=call_budget"
+
+  # A node id, then "--a", then an attempt number, inside a /packets/
+  # directory: the exact shape RunnerDispatch's spawn block pastes into a
+  # subagent's own first prompt. Captures [full_path, node].
+  PACKET_PATH_RE = %r{(\S+/packets/([a-z]{1,2}\d+)--a\d+\.packet)}.freeze
+
+  FIRST_RECORD_SCAN_LIMIT = 20
+
+  GIT_ALLOWED_VERBS = %w[add commit status rev-parse log].freeze
+  GIT_UNSAFE_RE = /[;&|\n]|\$\(|`/.freeze
+
+  # The one decision: nil (allow, no output) or a deny payload Hash. Never
+  # raises across its own boundary.
+  def decide(payload)
+    return nil unless payload.is_a?(Hash)
+
+    agent_id = payload["agent_id"]
+    return nil if agent_id.to_s.strip.empty?
+
+    session_id = payload["session_id"].to_s
+    transcript_path = payload["transcript_path"].to_s
+    return nil if session_id.empty? || transcript_path.empty?
+
+    sub_path = subagent_transcript_path(transcript_path, session_id, agent_id)
+
+    prompt = begin
+      first_user_prompt_text(sub_path)
+    rescue StandardError
+      nil
+    end
+    return nil unless prompt
+
+    match = PACKET_PATH_RE.match(prompt)
+    return nil unless match
+
+    node = match[2]
+    intent_dir = File.dirname(File.dirname(match[1]))
+
+    cap = node_cap(intent_dir, node)
+    return nil unless cap
+
+    count = begin
+      count_tool_use_blocks(sub_path)
+    rescue StandardError => e
+      note_unreadable(intent_dir, session_id, e.message)
+      return nil
+    end
+
+    return nil if count <= cap
+    return nil if git_only_bash_call?(payload)
+
+    deny_payload("#{node} is past its call budget (#{count}/#{cap} tool calls); #{RETURN_INSTRUCTION}")
+  end
+
+  def subagent_transcript_path(main_transcript_path, session_id, agent_id)
+    File.join(File.dirname(main_transcript_path), session_id, "subagents", "agent-#{agent_id}.jsonl")
+  end
+
+  # The first `"type":"user"` record in `path`'s own transcript, rendered to
+  # plain text (message.content as a string, or the joined text blocks of a
+  # content array). Scans at most FIRST_RECORD_SCAN_LIMIT lines: the dispatch
+  # prompt is always the transcript's opening record, so this never touches
+  # the bulk of a long-running subagent's history. Raises on a genuinely
+  # unreadable path (a directory, a permission error); the caller decides
+  # what that means.
+  def first_user_prompt_text(path)
+    File.open(path) do |f|
+      f.each_line.first(FIRST_RECORD_SCAN_LIMIT).each do |raw|
+        record = begin
+          JSON.parse(raw)
+        rescue JSON::ParserError
+          next
+        end
+        next unless record.is_a?(Hash) && record["type"] == "user"
+
+        return message_text(record)
+      end
+    end
+    nil
+  end
+
+  def message_text(record)
+    content = record.dig("message", "content")
+    case content
+    when String
+      content
+    when Array
+      content.select { |b| b.is_a?(Hash) && b["type"] == "text" }.map { |b| b["text"].to_s }.join("\n")
+    else
+      ""
+    end
+  end
+
+  # The cap named on `node`'s LATEST (file-order) non-torn transition line in
+  # `intent_dir`/savepoint.md, or nil when that line is not `running`, carries
+  # no `calls=`, or does not exist at all (matrix 2.6/2.6b: a later done/
+  # failed_verification line, or a sibling node's own running line, never
+  # caps this node).
+  def node_cap(intent_dir, node)
+    path = File.join(intent_dir, "savepoint.md")
+    return nil unless File.exist?(path)
+
+    latest = NodeLedger.entries(path).select { |e| !e[:torn] && e[:subject] == node }.last
+    return nil unless latest && latest[:state] == "running"
+
+    cap = (latest[:fields] || {})["calls"]
+    cap ? cap.to_i : nil
+  end
+
+  # Streams `path` a line at a time, counting `"type":"tool_use"` content
+  # blocks with a plain regex rather than a full JSON parse per line (matrix
+  # 2.5/2.8): a 3 MB transcript counts in well under 50 ms this way.
+  def count_tool_use_blocks(path)
+    count = 0
+    File.foreach(path) { |ln| count += ln.scan(/"type"\s*:\s*"tool_use"/).length }
+    count
+  end
+
+  # Past the cap, a Bash call is still allowed when its command runs only one
+  # safe git verb (matrix 2.7/D3): the git add/commit the denial itself
+  # orders must never be the call the hook blocks. Any chaining token
+  # (`;`, `&`, `|`, a newline, a subshell or a backtick) refuses the whole
+  # command, so a compound command can never smuggle an unrelated call past
+  # the cap riding on a leading `git`.
+  def git_only_bash_call?(payload)
+    return false unless payload["tool_name"].to_s == "Bash"
+
+    command = payload.dig("tool_input", "command").to_s.strip
+    return false if command.empty? || GIT_UNSAFE_RE.match?(command)
+
+    tokens = command.split(/\s+/)
+    return false unless tokens.shift == "git"
+
+    tokens.shift(2) if tokens.first == "-C"
+    GIT_ALLOWED_VERBS.include?(tokens.first)
+  end
+
+  def deny_payload(reason)
+    { "hookSpecificOutput" => { "hookEventName" => "PreToolUse", "permissionDecision" => "deny",
+                                 "permissionDecisionReason" => reason } }
+  end
+
+  # Best-effort note that the transcript could not be counted (matrix 2.9): a
+  # plain milestone line, the same shared primitive Commit/Review/Report
+  # lines already use, dedup'd on (stage, milestone) so a repeat failure in
+  # the same session with the same message is not written twice.
+  def note_unreadable(intent_dir, session_id, message, now: Time.now)
+    Savepoint.append_savepoint_line(intent_dir, "CallBudget", "transcript unreadable for #{session_id}: #{message}",
+                                     now)
+  rescue StandardError
+    nil
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  raw = begin
+    $stdin.read
+  rescue StandardError
+    nil
+  end
+
+  if raw && !raw.strip.empty?
+    payload = begin
+      JSON.parse(raw)
+    rescue StandardError
+      nil
+    end
+
+    result = HookCallBudget.decide(payload)
+    puts JSON.generate(result) if result
+  end
+
+  exit 0
+end