@zalom/plastic 2.0.0-alpha.21 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zalom/plastic",
-  "version": "2.0.0-alpha.21",
+  "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 ---