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

package/skills/conventions/references/locks-and-worktrees.md

@@ -4,10 +4,10 @@ This chapter holds the delivery lock, claims, worktrees, the fail-safe doctrine,
 
 ### Delivery Isolation and the Single-Owner Lock
 
-Locks and worktrees exist only for auto teams. An interactive session working direct or
-thinking takes no lock: it records into the day ledger, or into the intent its per-session
-pointer names (`~/.plastic/store/.tmp/<session>/current`, where `<session>` is the first eight
-characters of the session id; the file holds today's day id or an intent id).
+The delivery lock names the session delivering an intent, as its owner or a delegate. Locks
+and worktrees exist only for auto teams: an interactive session working direct or thinking
+takes no lock and records into its day ledger instead (the oldest day in the last seven whose
+checklist carries the session's line, else today).
 
 For an auto team, exactly one team develops an intent's delivery at a time. Ownership is
 session-keyed and durable: arming acquires `delivery.lock` inside the intent directory
@@ -17,9 +17,7 @@ but never grants access and is never inferred from transcripts or filesystem pat
 fields on legacy locks display as `Unknown`. Liveness is a lease: the record hook refreshes
 the lock file's mtime on every write the owning session makes, and that mtime is the sole
 heartbeat truth. The lock counts as stale only when the mtime is older than the TTL. No
-process id is consulted anywhere. The pointer file is a cache of which intent a session
-records into; the lock file is the truth of who owns a delivery, and wins on any
-disagreement. Another team that finds a fresh lock backs off; a stale lock is reclaimed only
+process id is consulted anywhere. The lock file is the truth of who owns a delivery. Another team that finds a fresh lock backs off; a stale lock is reclaimed only
 by explicit takeover, which replaces the lock and appends an audit line to the intent's
 savepoint.md. Rearming the same session preserves its acquired identity and refreshes known
 provenance; an explicit takeover replaces the controller and starts new provenance.
@@ -31,7 +29,7 @@ retained as descriptive history, bounded to the 20 most recent terminal entries.
 a delegate, and an artifact claim are distinct evidence: controller ownership authorizes the
 delivery, delegate registration authorizes a child session, and a claim selects one current
 writer for one artifact. Disarm clears the lock; the End tail is ordered: verify, merge and
-remove worktrees, clear the lock, and only then is the session pointer purge-eligible. Repair
+remove worktrees, then clear the lock. Repair
 is one idempotent function with two entry points: the `plastic-lock` command (`who`, status,
 fix, release, reclaim, delegate) and the `plastic-doctor` skill's lock section, so repair
 self-heals. `who` is read-only and reports the controller, mtime heartbeat, delegates, and
@@ -90,18 +88,18 @@ an orphaned worktree behind, and clear a stale worktree reference with `git work
 
 #### Intent delivery, station by station
 
-How one auto-team intent travels from boarding to the End tail, and what the lock, the pointer, and
+How one auto-team intent travels from boarding to the End tail, and what the lock and
 the record hook do at each station. Nothing in the third column blocks; the fourth column is
 what gets written down.
 
-| Station | Delivered artifact | Lock and pointer steps | Record |
+| Station | Delivered artifact | Lock steps | Record |
 |---|---|---|---|
-| Start (board) | none (a procedure, not a stage) | `plastic-lock fix` self-heals stale, corrupt, or legacy state; arm acquires `delivery.lock` (O_EXCL, session-keyed), provisions the code worktree, writes the session pointer | savepoint confirms the boarding station |
+| Start (board) | none (a procedure, not a stage) | `plastic-lock fix` self-heals stale, corrupt, or legacy state; arm acquires `delivery.lock` (O_EXCL, session-keyed), provisions the code worktree | savepoint confirms the boarding station |
 | What (create) | `<id>--<slug>.md`, born complete | no lock yet; `new-intent` validates the file it writes (`scripts/validate-intent`) | savepoint `What` line; intent listed in INDEX `## Active` |
 | Why | `spec.md` | owner writes refresh the lease (lock file mtime heartbeat) | savepoint `Why started`, `Why spec.md created` |
 | How | `plan.md`, `actions/ACTION_N.md` (at least one), `checklist.md` | heartbeat on writes | savepoint `How started`, `How plan.md created`, `How checklist.md created`, `Exec started` |
 | Exec | code on the intent branch, checklist checked off | heartbeat; code edits confined to the provisioned worktree; delegates write under the owner's lock | checklist boxes; savepoint milestones; the day-ledger line promotes when a project file lands |
-| End (done) | mandatory `outcome.md` (`disposition: delivered\|abandoned`), INDEX moves to Completed or Abandoned | ordered End tail: verify, merge and remove worktrees, disarm clears `delivery.lock`, then the pointer is purge-eligible, and the QMD reindex runs LAST (after purge); `end-intent` backfills a placeholder `outcome.md` from the record and its structure check reports (never refuses) | the savepoint's terminal `delivered` (or `abandoned`) line; takeover audits, if any, remain in savepoint.md |
+| End (done) | mandatory `outcome.md` (`disposition: delivered\|abandoned`), INDEX moves to Completed or Abandoned | ordered End tail: verify, merge and remove worktrees, disarm clears `delivery.lock`, and the QMD reindex runs LAST; `end-intent` backfills a placeholder `outcome.md` from the record and its structure check reports (never refuses) | the savepoint's terminal `delivered` (or `abandoned`) line; takeover audits, if any, remain in savepoint.md |
 | Maintenance (Future, Terminal, or Active-with-a-stale-or-no-lock) | `revisions.md` move-and-record entries | detects (never acquires) `delivery.lock`; defers and reports while the target's lock is FRESH (`Lock.fresh?`); a stale or absent lock is not-active, maintenance proceeds | append-only, rule-tagged `revisions.md` entry written in the same operation as the change, or the change is refused; lands via a fresh branch off store main merged back as one closed op, never `git add -A` |
 
 ## The write guard is not residue

package/skills/direct/SKILL.md

@@ -54,8 +54,8 @@ the 15 observable signals and the response each one selects.
   item.
 - Only a prompt that changes something on disk or produces an artifact becomes a checklist item.
   A pure question is answered inline and recorded nowhere.
-- Direct work records into the day ledger that the per-session pointer names. Assume the pointer
-  exists. Never write it.
+- Direct work records into the day ledger for the session's day (the oldest day in the last
+  seven whose checklist carries the session's line, else today). Never write that lookup by hand.
 
 ## 5. What direct does not take
 

package/skills/doctor/SKILL.md

@@ -223,7 +223,7 @@ knowingly-exempt `(intent_id, rule)` pairs. Format: one `rule_name id id id` lin
 blank lines and `#` comments ignored. v1 honors exactly one rule, `savepoint_operational`.
 
 **Reading the count.** When any exclusion applies, the `savepoint_operational` check's message
-folds in the count and the file's path, e.g. `"... (3 excluded via ~/.plastic/doctor-exclusions)"`.
+includes the count and the file's path, e.g. `"... (3 excluded via ~/.plastic/doctor-exclusions)"`.
 A malformed line in the file forces the check to `warn` with the parse error in `details`, even
 when zero real gaps remain, so a broken file is never silently permissive.
 
@@ -262,13 +262,13 @@ Locks exist for auto teams: a `delivery.lock` file in the intent directory names
 session, and the `record` hook refreshes its mtime on every edit (the lease heartbeat; stale
 means older than the TTL). Direct work takes no lock. When a lock reads held by a session
 that is gone, when work resumes after a crash, reboot, or `/tmp` wipe, or when the user says
-"fix the lock", "who holds the lock", or "reclaim the lock", use the CLI (intent 304 folded
+"fix the lock", "who holds the lock", or "reclaim the lock", use the CLI (intent 304 merged
 the former locking skill here):
 
 | Verb | What it does | When |
 |---|---|---|
 | `who` | Owner, heartbeat, claims, delegates, from durable files only | Safe inspection; needs `--intent-dir` |
-| `status` | Lock file, freshness, the derived worktree, whether this session's pointer names the intent, claims | Always safe; run first |
+| `status` | Lock file, freshness, the derived worktree, whether this session is delivering the intent, claims | Always safe; run first |
 | `fix` | Idempotent repair from disk truth for this session; never touches a fresh foreign lock | Interrupted work, corrupt state, `/tmp` wiped |
 | `release` | The owner clears the lock | Ending or abandoning an auto delivery |
 | `reclaim` | Explicit takeover of a stale lock; appends an audit line to `savepoint.md` | The owner is gone and the lease expired |
@@ -290,7 +290,7 @@ these verbs (claims, worktrees, the station ledger).
 ## Provisioning a project store
 
 When a project is registered in `~/.plastic/projects.yml` but has no store on disk (doctor
-reports `project_store_dir`), provision it (intent 304 folded the former provisioning skill
+reports `project_store_dir`), provision it (intent 304 merged the former provisioning skill
 here). The slug is the project's key under `projects`; an unregistered slug exits non-zero and
 creates nothing, and this procedure never edits `projects.yml`.
 

package/skills/intent-creating/evals/evals.json

@@ -35,7 +35,7 @@
       "scope": "behavior",
       "set": "validation",
       "prompt": "Create an intent that is the direct continuation of intent 41: it emerged from intent 41's lifecycle and could not exist without it.",
-      "expected_output": "Because the new intent was genuinely CREATED FROM 41 (D1), it carries 41 in --sources (or branches from 41, which folds 41 into sources via the redundant-explicit rule). The reciprocal I1 backlink lands: intent 41's frontmatter chain gains the new intent's id. This is the created-from case, contrasted with the related-but-not-spawned case in eval 1.",
+      "expected_output": "Because the new intent was genuinely CREATED FROM 41 (D1), it carries 41 in --sources (or branches from 41, which merges 41 into sources via the redundant-explicit rule). The reciprocal I1 backlink lands: intent 41's frontmatter chain gains the new intent's id. This is the created-from case, contrasted with the related-but-not-spawned case in eval 1.",
       "files": [],
       "assertions": [
         {

package/skills/intent-executing/SKILL.md

@@ -26,7 +26,7 @@ touching the worktree above.
 
 `ruby scripts/runner step <intent_dir>` computes which nodes in `graph.md`/`nodes/*.md` are
 ready, applies dispatch policy (model, call cap), and prints a spawn block per dispatched node
-- agent, model, packet path, the one test command, the call cap - fenced in its own stdout.
+- agent, model, node input path, the one test command, the call cap - fenced in its own stdout.
 The runner itself never spawns an agent (327 D42). Call `step` again after each dispatched
 node returns.
 
@@ -35,6 +35,12 @@ node returns.
 The dispatch step is the paste, not a lead's hand-typed brief: copy each spawn block into the
 Agent tool as its own dispatch, verbatim.
 
+On Claude Code, the session spawns each dispatched node as a background subagent of its
+per-kind agent (`plastic-node-work`, `plastic-node-verify`, `plastic-node-research`) named in
+the spawn block. On Codex, one node runs over `codex exec` in a sandbox scoped to its kind and
+writes only a return file, which the next `step` absorbs the same way it absorbs a Claude Code
+return.
+
 ## status
 
 `ruby scripts/runner status <intent_dir>` renders the graph's ledger state: which nodes are

package/skills/releasing/SKILL.md

@@ -293,11 +293,11 @@ branch, then removes the worktree, and prunes the repo:
 
 ```bash
 ruby -r ~/.plastic/scripts/lib/worktree -r ~/.plastic/scripts/lib/arm -e \
-  'Worktree.finish(Arm.bridge_hash(intent_dir: "<STORE>/<dir>"), merge: true)'
+  'Worktree.finish(Arm.delivery(intent_dir: "<STORE>/<dir>"), merge: true)'
 ```
 
 (The worktree block is derived from `projects.yml` and the intent id, so the one-liner needs
-only the intent directory; the `/tmp` bridge it once discovered was removed in 2.0, intent 307.)
+only the intent directory.)
 
 Honor the worktree-cleanup rule: never leave an orphaned worktree, and run `git worktree
 prune` in the affected repo if you hit a stale reference. For why this is the one place the

package/skills/releasing/references/promotion-and-tagging.md

@@ -13,7 +13,7 @@ for why the intent's worktree is merged before removal.
 ## Worktree merge-then-remove rationale
 
 **Worktree-isolated intents (intent 73c3).** When the intent was delivered in a Plastic
-worktree (the bridge has a provisioned `worktree` block), its code lives on the branch
+worktree (the delivery lock has a provisioned `worktree` block), its code lives on the branch
 `plastic/{id}--{slug}` inside `<repo>/.claude/worktrees/{id}--{slug}`, not on a hand-made
 feature branch. The merge-then-remove of that worktree is handled together with cleanup in
 Workflow step 9, which merges `plastic/{id}--{slug}` into the default branch BEFORE removing the

package/skills/releasing/references/release-lines.md

@@ -29,7 +29,7 @@ Work rides the beta-verified lane when it changes operational substrate, carries
 migration, lock, or state-format risk, or cannot be fully validated by a hermetic suite alone.
 Everything else merges straight to main.
 
-Intent 41's DB layer is the archetypal beta-lane case: it replaces the bridge, lock, and session
+Intent 41's DB layer is the archetypal beta-lane case: it replaces the lock and session
 file formats with a new persistent SQLite substrate. A green suite proves the code correct; it
 cannot prove the new substrate survives real, uncontrolled usage, so real-use verification on
 beta comes first.

package/skills/tutorial/references/track-2-auto.md

@@ -67,7 +67,7 @@ No new command. At each stage boundary (What, Why, How, Exec) the agent briefs i
 fixed three-line shape: State (what happened and why it matters), Risk (the one thing that
 could bite, or "nothing flagged"), and Call (the decision left to the user, or the call the
 agent is taking on its own). That is the depth for a medium or large intent. A small intent
-gets one briefing, at How, folding in what the earlier stages would have said.
+gets one briefing, at How, merging in what the earlier stages would have said.
 
 Checkpoint: in the most recent report, point at the State line, the Risk line, and the Call
 line.

package/templates/index.md

@@ -2,7 +2,7 @@
 
 ## Active
 <!-- Line shape: `- [ID — Title](path)`. Writes emit the em-dash (U+2014) between
-     id and title; readers (Bridge.index_entry_match) accept the em-dash or a plain
+     id and title; readers (IndexEntry.match) accept the em-dash or a plain
      hyphen, so either form parses (see https://github.com/zalom/plastic/blob/main/docs/internals.md). -->
 (no active intents)
 

package/templates/project.yml

@@ -8,5 +8,5 @@ release:
 #   mode: direct               # direct | pull_request
 #   base: main                 # defaults to origin/HEAD, then main, then master
 #   branch_template: "session/{{day}}"   # {{day}}, {{ticket}}, {{slug}} tokens
-#   ticket_source: intent_id   # intent_id (the session pointer's intent id, else the day id)
+#   ticket_source: intent_id   # intent_id (the delivering intent's id from its delivery lock, else the day id)
 #   workspace: checkout        # checkout | worktree (worktree applies to direct mode only)

package/scripts/lib/bridge.rb

@@ -1,116 +0,0 @@
-#!/usr/bin/env ruby
-# encoding: UTF-8
-
-require "yaml"
-require_relative "lock"
-
-# Bridge - the shared helpers that outlived the /tmp bridge JSON.
-#
-# Until 2.0 this file cached a session's delivery state in
-# `<tmp>/plastic-<session>--<id>.json` (stage, worktree, lock, auto flag) and
-# arbitrated which bridge a gate hook should read. Ruling 6 of intent 296
-# retired that: the per-session pointer (`~/.plastic/store/.tmp/<session>/current`)
-# plus `delivery.lock` in the intent directory is the whole bridge, and
-# `scripts/lib/arm.rb` is how a team takes and gives back an intent (intent
-# 307). What stays here is the handful of pure helpers a dozen callers still
-# share: the INDEX entry matcher, the Active check, the id-from-dir parser,
-# the project config reader, `blank?`, and the skill-reference delegator.
-module Bridge
-  # Single place a skill-reference string gets built (intent 201, D3). The
-  # prefix table lives on Lock; this is a thin delegator so call sites read
-  # Bridge.skill_ref.
-  def self.skill_ref(name, harness: :claude)
-    Lock.skill_ref(name, harness: harness)
-  end
-
-  def self.blank?(value)
-    value.nil? || value.to_s.strip.empty?
-  end
-
-  # --- Shared INDEX entry matcher (intent 188, D12/D13) -----------------------
-  #
-  # ONE definition site for the "- [ID <sep> Title](link)" shape both
-  # `intent_active?` (below) and `scripts/end-intent`'s own INDEX-move parser
-  # depend on, so the two regexes can never drift apart. Accepts a real em dash
-  # (U+2014) OR a plain hyphen as the id/title separator on READ; every WRITE
-  # still emits the real em dash (D10). The separator is built from the
-  # codepoint, not a literal byte, so this file stays em-dash free.
-  EM_DASH = "\u2014".freeze
-  INDEX_ENTRY_RE = /\A- \[(\S+)\s+(?:#{Regexp.escape(EM_DASH)}|-)\s+(.*?)\]\(([^)]+)\)/.freeze
-
-  # Match `line` (already chomped) against the shared INDEX entry shape.
-  # Returns a MatchData (captures: 1 = id, 2 = title, 3 = link) or nil.
-  def self.index_entry_match(line)
-    line.to_s.match(INDEX_ENTRY_RE)
-  end
-
-  # True iff the intent is Active in its store's INDEX.md, which lives at the
-  # PARENT of the store/ dir. Non-raising: any failure (missing or unreadable
-  # INDEX, bad arg) returns false. `index_active_ids` is a pure-data test
-  # seam: when an Array of id strings is supplied, membership is checked
-  # against it directly with no file read.
-  def self.intent_active?(intent_id, store:, index_active_ids: nil)
-    target = intent_id.to_s
-    return index_active_ids.include?(target) if index_active_ids.is_a?(Array)
-
-    index = File.join(File.dirname(store.to_s), "INDEX.md")
-    return false unless File.exist?(index)
-
-    in_active = false
-    File.foreach(index) do |line|
-      stripped = line.chomp
-      if stripped == "## Active"
-        in_active = true
-        next
-      end
-      next unless in_active
-      break if stripped.start_with?("## ") # next section ends the Active block
-      m = index_entry_match(stripped)
-      return true if m && m[1] == target
-    end
-    false
-  rescue StandardError
-    false
-  end
-
-  # --- Project config -------------------------------------------------------------
-
-  PROJECT_CONFIG_DEFAULTS = {
-    "governing_docs" => ["AGENTS.md"],
-    "release" => {
-      "on_complete" => "commit",
-    },
-  }.freeze
-
-  def self.read_project_config(slug)
-    path = File.join(Dir.home, ".plastic", "projects", slug, "project.yml")
-    config = if File.exist?(path)
-               YAML.safe_load(File.read(path)) || {}
-             else
-               {}
-             end
-
-    deep_merge(PROJECT_CONFIG_DEFAULTS, config)
-  rescue => e
-    $stderr.puts "Warning: failed to read project config for #{slug}: #{e.message}"
-    PROJECT_CONFIG_DEFAULTS.dup
-  end
-
-  # "<id>" from a ".../store/<id>--<slug>" dir, else nil.
-  def self.intent_id_from_dir(dir)
-    base = File.basename(dir.to_s)
-    base.include?("--") ? base.split("--", 2).first : nil
-  end
-
-  def self.deep_merge(base, overlay)
-    result = base.dup
-    overlay.each do |key, value|
-      if value.is_a?(Hash) && result[key].is_a?(Hash)
-        result[key] = deep_merge(result[key], value)
-      else
-        result[key] = value
-      end
-    end
-    result
-  end
-end