@zalom/plastic 1.1.1 → 1.1.2

package/PLASTIC.md

@@ -19,7 +19,7 @@ store/
     plan.md               # optional - implementation plan (How deliverable)
     checklist.md          # optional - execution registry (How deliverable)
     outcome.md            # optional - detailed result (Exec deliverable)
-    actions/              # optional - individual work items
+    actions/              # optional - real action files (How deliverable, at least one required)
     resources/            # optional - research, references, screenshots, diagrams
     savepoint.md          # optional - deterministic cycle-step ledger (auto-written)
     revisions.md          # optional - append-only structural-maintenance audit trail
@@ -95,7 +95,7 @@ tags: [plastic, architecture]
 |-------|---------|-------------|--------|
 | **What** | `## Intent` | `{ID}--{slug}.md` | `plastic-intent-creating` |
 | **Why** | `## Context` + Decisions | `spec.md` | `plastic-intent-brainstorming` |
-| **How** | Planning | `plan.md` + `actions/` + `checklist.md` | `plastic-intent-planning` |
+| **How** | Planning | `plan.md` + `actions/ACTION_N.md` (at least one) + `checklist.md` | `plastic-intent-planning` |
 | **Exec** | Execution | `outcome.md` | `plastic-intent-executing` |
 
 `## Insights` is the append-only log of durable discoveries captured throughout ALL stages.
@@ -133,8 +133,9 @@ same-structure invariant holds: same file set, stage order, gates, and savepoint
 every tier and in both modes.
 
 S/M collapse the topology (one thinker agent writes spec.md then plan.md plus
-checklist.md in one context; actions/ only for L; a sonnet executor implements). L keeps
-the full team.
+checklist.md plus at least one real action file in one context, consolidated into a single
+actions/ACTION_1.md at S/M and one file per task at L; a sonnet executor implements). L
+keeps the full team.
 
 Never cut at any tier: the independent reviewer, outcome.md as truth of delivery, the
 delivery lock, worktree isolation, intent creation via skill, INDEX as status truth, the
@@ -425,8 +426,8 @@ purge. See `docs/internals.md` for depth.
 | Transition | Trigger | Gate |
 |---|---|---|
 | What → Why | `spec.md` written | (none) |
-| Why → How | `plan.md` + `actions/` + `checklist.md` | `spec.md` must exist |
-| How → Exec | Checklist has items | Plan triplet must exist |
+| Why → How | `plan.md` + `actions/ACTION_N.md` (at least one) + `checklist.md` | `spec.md` must exist |
+| How → Exec | Checklist has items | plan.md, checklist.md, and at least one real actions/ACTION_N.md must exist |
 | Exec → Done | `outcome.md` written | All checklist items checked |
 
 Hard blocking: hooks exit code 2 on gate failure.
@@ -530,7 +531,7 @@ each 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, writes the bridge cache | lock-gate denies any write into an active intent dir without this intent's lock; every deny names the resolving command | savepoint confirms the boarding station |
 | What (create) | `<id>--<slug>.md`, born complete | no lock yet; no bridge | create-gate validates the proposed intent content (Write, Edit, and MCP edits) | savepoint `What` line; intent listed in INDEX `## Active` |
 | Why | `spec.md` | owner writes refresh the lease (lock file mtime heartbeat) | gate-check requires the intent file with `## Intent` before spec.md; lock-gate admits only the owner or a delegate | savepoint `Why started`, `Why spec.md created` |
-| How | `plan.md`, `actions/`, `checklist.md` | heartbeat on writes; the code gate stays closed until plan.md plus checklist.md exist | gate-check requires spec.md before plan.md, and plan.md plus actions/ before checklist.md | savepoint `How started`, `How plan.md created`, `How checklist.md created`, `Exec started` |
+| How | `plan.md`, `actions/ACTION_N.md` (at least one), `checklist.md` | heartbeat on writes; the code gate stays closed until plan.md, checklist.md, and a real action file all exist | gate-check requires spec.md before plan.md, and plan.md plus a real actions/ACTION_N.md before checklist.md | 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; bash, interpreter, and MCP writes gated the same way | code-gate, worktree-gate, bash-gate, lock-gate | checklist boxes; savepoint milestones |
 | 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 bridge is purge-eligible, and the QMD reindex runs LAST (after purge) | gate-check blocks outcome.md while checklist items are unchecked | savepoint `Done delivered` (or `abandoned`); takeover audits, if any, remain in savepoint.md |
 | Maintenance (any stage) | `revisions.md` move-and-record entries | future `maintenance.lock` (short TTL), mutually exclusive with `delivery.lock` in either direction; 108 ships the schema seam only, the implementation follows intent 93 in a chained intent | acquisition refuses while the other lock type is fresh; a terminal intent with no lock held is read-only | dated, rule-tagged `revisions.md` entry; savepoint untouched |

package/agents/plastic-enforcer.md

@@ -31,8 +31,9 @@ is honored as written.
 4. **Sequence the team** — dispatch specialists per the chosen topology with a constructed
    context bundle:
    - S/M: ONE thinker agent, one boot, two stations — it writes spec.md, then plan.md +
-     checklist.md, in a single context. Sections may be one line each; plan.md carries the
-     checklist rationale inline; `actions/` files appear only for L. S may skip the QMD
+     checklist.md + at least one real action file, in a single context. Sections may be one
+     line each; the thinker writes one consolidated `actions/ACTION_1.md` (never an empty
+     `actions/`), while L writes one `actions/ACTION_N.md` per task. S may skip the QMD
      discovery deposit when chain and sources are both empty. A sonnet executor implements.
    - L: today's full team, one specialist per stage (brainstorming, spec-specialist, planner,
      executor), each in a fresh context.

package/agents/plastic-executor.md

@@ -19,11 +19,11 @@ When dispatched in auto mode you receive the standard Plastic spawn preamble (fr
 
 ## How You Work
 
-1. Receive (input handoff): `plan.md` and `checklist.md` from the planner (plus
-   `ACTION_N.md` files inside `actions/` at L; at S/M the `actions/` directory exists but
-   stays empty, so read the tier fork from the inline plan-as-checklist in plan.md
-   instead). For S/M intents you run on the sonnet default, the collapsed topology's
-   implementer; behavior is otherwise unchanged.
+1. Receive (input handoff): `plan.md`, `checklist.md`, and at least one real `ACTION_N.md`
+   inside `actions/` from the planner (S/M hand you one consolidated `actions/ACTION_1.md`;
+   L hands you one `actions/ACTION_N.md` per task). Execute the action files in order. For
+   S/M intents you run on the sonnet default, the collapsed topology's implementer; behavior
+   is otherwise unchanged.
 2. Work one action at a time, preferring safe, non-destructive routes
 3. Edit project code (the gate is open now that plan and checklist exist)
 4. Run the full suite, iterate to zero failures and zero errors

package/agents/plastic-planner.md

@@ -14,14 +14,17 @@ When dispatched in auto mode you receive the standard Plastic spawn preamble (fr
 
 1. **Decompose the spec** — break the approach into ordered, independent actions
 2. **Write the plan** — produce `plan.md` with numbered tasks and verification
-3. **Write self-contained actions, tier-forked**:
-   - S/M: `plan.md` carries the checklist rationale INLINE; do NOT write
-     `actions/ACTION_N.md` files. Sections may be one line each.
-   - L: keep today's shape — one self-contained `actions/ACTION_N.md` per task.
+3. **Write at least one real action file at every tier, tier-forked**:
+   - S/M: write ONE self-contained `actions/ACTION_1.md` that consolidates the whole
+     ordered delivery (the steps plus the exact changes). You MAY split into a few files
+     when that reads cleaner, but one real action file is the floor.
+   - L: one self-contained `actions/ACTION_N.md` per task. A `.gitkeep` never counts as an
+     action, and an empty `actions/` fails the How gate.
 4. **Write the checklist** — `checklist.md` as the execution registry covering every action.
-   `checklist.md` exists at every tier: the file set does not change by tier, only depth
-   (inline vs action files) and agent topology do. plan.md + checklist.md are the two files
-   that open the code gate at every tier.
+   `checklist.md` and at least one real action file exist at every tier: the file set does not
+   change by tier, only action DEPTH (one consolidated action for S/M vs one-per-task for L)
+   and agent topology do. plan.md, checklist.md, AND a real `actions/ACTION_N.md` are what open
+   the code gate at every tier.
 
 ## How You Work
 
@@ -38,7 +41,7 @@ END your turn with a structured completion report as your final message, per the
 - The ordered actions, one line each: what the action does and how it is verified
 - Decomposition rationale: why this order, and why the actions are independent
 - Checklist coverage: the item count, and that every action plus suite-green is covered
-- Which tier shape was produced: inline plan-as-checklist (S/M) or full `actions/` (L)
+- Which tier shape was produced: one consolidated `actions/ACTION_1.md` (S/M) or one `actions/ACTION_N.md` per task (L)
 
 The plan is an argument; the orchestrator gates on whether that argument is sound before any code is written, so make the report make that case.
 
@@ -46,7 +49,8 @@ The plan is an argument; the orchestrator gates on whether that argument is soun
 
 - You are dispatched by the plastic-enforcer and your deliverable is gated before Exec begins
 - You write only intent-store files (`plan.md`, `actions/`, `checklist.md`); no project code
-- The code gate stays closed until `plan.md` and `checklist.md` exist, so produce both
+- The code gate stays closed until `plan.md`, `checklist.md`, and at least one real `actions/ACTION_N.md` exist, so produce all three
 - Keep each action self-contained so the executor can run them one at a time
-- The `actions/` empty-directory git-tracking edge (present only within one same-session
-  local delivery) is out of scope; do not add a `.gitkeep` or a guard for it here
+- Write real `actions/ACTION_N.md` files, never a `.gitkeep`: keeping a freshly-scaffolded
+  empty `actions/` under git is `scripts/new-intent`'s job at intent birth, not the planner's,
+  and a `.gitkeep` never counts as an action

package/package.json

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

package/scripts/doctor.rb

@@ -25,6 +25,7 @@ require_relative "lib/lock"
 require_relative "lib/bridge"
 require_relative "lib/agent_models"
 require_relative "lib/legacy_bookend_amnesty"
+require_relative "lib/skill_lint"
 
 # Diagnostic engine, instantiable with an injected store/agent map so tests can
 # run it hermetically (no eval, no global-constant rewriting).
@@ -1805,6 +1806,48 @@ class Doctor
     )
   end
 
+  # --- Check category: skill-lint (advisory only; intent 85b) ---
+  #
+  # Reports SkillLint's five structural checks over the skills/ tree as a
+  # single ADVISORY finding. Always status: "pass", so it can never contribute
+  # to doctor's warn/fail exit code (summarize buckets purely by status; the
+  # lint verdict belongs to a future ship gate, intent 100, not to doctor).
+  # Resolves the same repo skills/ directory `scripts/skill-lint` defaults to,
+  # relative to this script's own location. Skills install flat and renamed
+  # (plastic-<name>) under each agent's own skills/ dir, a different directory
+  # shape SkillLint's frontmatter name-check does not target, so an installed
+  # ~/.plastic/scripts/doctor.rb with no sibling skills/ tree has nothing in
+  # scope here and reports a silent pass rather than guessing at a mismatched
+  # layout.
+  def check_skill_lint
+    dir = File.expand_path("../skills", __dir__)
+    unless File.directory?(dir)
+      return [check(
+        category: "skill_lint", name: "skill_lint", status: "pass",
+        message: "No skills/ directory found at #{tilde(dir)} to lint (nothing in scope for this advisory check)"
+      )]
+    end
+
+    result = SkillLint.new(skills_dir: dir).run
+
+    if result.ok?
+      [check(
+        category: "skill_lint", name: "skill_lint", status: "pass",
+        message: "skill-lint: clean (0 violations across the skills/ tree)"
+      )]
+    else
+      by_check = result.violations.group_by { |v| v[:check] }.transform_values(&:size)
+      counts = by_check.map { |check_id, n| "#{check_id}: #{n}" }.join(", ")
+      details = result.violations.map { |v| "#{v[:check]} #{v[:skill]} #{v[:file]}:#{v[:line]}: #{v[:message]}" }
+      [check(
+        category: "skill_lint", name: "skill_lint", status: "pass",
+        message: "skill-lint: #{result.violations.size} advisory violation(s) found (#{counts}); " \
+                  "informational only, never affects doctor's exit code",
+        details: details
+      )]
+    end
+  end
+
   # --- Run all checks ---
 
   def run_checks(agent_key)
@@ -1817,6 +1860,7 @@ class Doctor
     all_checks += check_deprecations
     all_checks += check_qmd
     all_checks += check_done_signals
+    all_checks += check_skill_lint
 
     summarize(all_checks, agent_key)
   end

package/scripts/lib/bridge.rb

@@ -395,10 +395,24 @@ module Bridge
     File.exist?(path)
   end
 
+  # True iff actions/ holds AT LEAST ONE real action file: a non-empty *.md whose
+  # first line is not the placeholder sentinel. A `.gitkeep` (no .md extension)
+  # never counts, an empty *.md never counts, and a sentinel-only *.md never
+  # counts. Pure and side-effect-free so the gate stays unit-testable. Fail-open:
+  # a missing actions/ dir globs to nothing and returns false (the gate then
+  # reports it needs a real action file); it never raises.
+  def self.has_real_action?(intent_dir)
+    Dir.glob("#{intent_dir}/actions/*.md").any? do |f|
+      File.file?(f) && File.size(f) > 0 && stage_file_present?(f)
+    end
+  rescue StandardError
+    false
+  end
+
   def self.derive_stage(intent_dir)
     return "done" if stage_file_present?("#{intent_dir}/outcome.md")
     if stage_file_present?("#{intent_dir}/plan.md") &&
-       File.directory?("#{intent_dir}/actions") &&
+       has_real_action?(intent_dir) &&
        stage_file_present?("#{intent_dir}/checklist.md")
       return "exec"
     end
@@ -414,7 +428,7 @@ module Bridge
     ["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 << "actions/" if has_real_action?(intent_dir)
     files
   end
 
@@ -779,8 +793,13 @@ module Bridge
         return "Cannot start How — Why is incomplete (spec.md missing)"
       end
     when "checklist.md"
-      unless stage_file_present?("#{intent_dir}/plan.md") && File.directory?("#{intent_dir}/actions")
-        return "Cannot complete How — plan.md or actions/ missing"
+      unless stage_file_present?("#{intent_dir}/plan.md")
+        return "Cannot complete How — plan.md missing"
+      end
+      unless has_real_action?(intent_dir)
+        return "Cannot complete How — actions/ has no real action file (only .gitkeep or empty). " \
+               "The planner must write at least one actions/ACTION_N.md before checklist.md. " \
+               "See skills/intent-planning."
       end
     when "outcome.md"
       checklist = "#{intent_dir}/checklist.md"
@@ -1017,11 +1036,14 @@ module Bridge
     return nil unless store && dir
     intent_dir_abs = File.expand_path("#{store}/#{dir}")
 
-    # "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.
+    # "How reached" = plan.md + checklist.md are both present AND actions/ holds at
+    # least one real action file. 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 the planner has written a real action file, so an
+    # empty or .gitkeep-only actions/ never opens the code gate.
     reached_how = stage_file_present?("#{intent_dir_abs}/plan.md") &&
-                  stage_file_present?("#{intent_dir_abs}/checklist.md")
+                  stage_file_present?("#{intent_dir_abs}/checklist.md") &&
+                  has_real_action?(intent_dir_abs)
     return nil if reached_how
 
     file_abs = File.expand_path(file_path.to_s)
@@ -1030,9 +1052,9 @@ module Bridge
     return nil if file_abs == intent_dir_abs || file_abs.start_with?("#{intent_dir_abs}/")
 
     id = intent_info["id"]
-    "intent #{id} has not reached How — write plan.md + checklist.md before " \
-      "editing project code. Run plastic-auto or plastic-intent-planning first. " \
-      "(blocked edit: #{file_abs})"
+    "intent #{id} has not reached How — write plan.md + checklist.md and at least " \
+      "one real actions/ACTION_N.md before editing project code. Run plastic-auto or " \
+      "plastic-intent-planning first. (blocked edit: #{file_abs})"
   end
 
   # --- Solo-mode detection (intent 128) ---------------------------------------

package/scripts/lib/installer_core.rb

@@ -296,6 +296,8 @@ class InstallerCore
       "scripts/lib/legacy_bookend_amnesty.rb" => "scripts/lib/legacy_bookend_amnesty.rb",
       "scripts/doctor.rb" => "scripts/doctor.rb",
       "scripts/dashboard.rb" => "scripts/dashboard.rb",
+      "scripts/skill-lint" => "scripts/skill-lint",
+      "scripts/lib/skill_lint.rb" => "scripts/lib/skill_lint.rb",
     }
   end
 

package/scripts/lib/skill_lint.rb

@@ -0,0 +1,304 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "yaml"
+
+# SkillLint: deterministic, dependency-injected engine that runs five
+# structural checks over a directory of Agent Skills (intent 85b).
+#
+# Pure and DI: constructed with an injected `skills_dir`, performs no writes,
+# no `eval`, and reads no ambient config beyond the injected directory. Mirrors
+# the CLI-over-lib shape of `scripts/lib/intent_validator.rb`: the `skill-lint`
+# CLI (ACTION_2) is a thin wrapper, `scripts/doctor.rb` (ACTION_4) consumes the
+# same engine for an advisory finding, and `test/skill_lint_test.rb` (ACTION_3)
+# proves every check red-and-green plus a no-skip-list live-tree guard.
+#
+# Each violation is a Hash:
+#   { check:, skill:, file:, line:, rule:, message: }
+# `check` is one of the five check-ids below, `skill` is the skill directory
+# basename, `file` is the offending path, `line` is an Integer where locatable
+# else nil, `rule` cites the standard being enforced, `message` is an
+# actionable fix instruction.
+class SkillLint
+  # A binding keyword: a mention's paragraph carries an observable trigger
+  # condition when it names one of these (word-boundary, case-insensitive).
+  BINDING_KEYWORD_RE = /\b(when|if|before|after|while)\b/i
+
+  # A `to <verb>` or `for <noun-phrase>` purpose clause.
+  PURPOSE_RE = /\b(to|for)\s+\S/i
+
+  Result = Struct.new(:violations) do
+    def ok?
+      violations.empty?
+    end
+
+    # Slice violations down to one check-id, e.g. for a doctor finding or a
+    # red-proof assertion.
+    def violations_for(check_id)
+      violations.select { |v| v[:check] == check_id }
+    end
+  end
+
+  def initialize(skills_dir:)
+    @skills_dir = skills_dir
+  end
+
+  def run
+    violations = []
+
+    skill_md_paths.each do |skill_md|
+      skill_dir = File.dirname(skill_md)
+      content = File.read(skill_md)
+
+      violations.concat(check_body_budget(skill_dir, skill_md, content))
+      violations.concat(check_frontmatter_validity(skill_dir, skill_md, content))
+      violations.concat(check_bare_pointer(skill_dir, skill_md, content))
+      violations.concat(check_orphan_files(skill_dir))
+      violations.concat(check_references_depth(skill_dir))
+    end
+
+    Result.new(violations)
+  end
+
+  private
+
+  def skill_md_paths
+    Dir.glob(File.join(@skills_dir, "*", "SKILL.md")).sort
+  end
+
+  def skill_name(skill_dir)
+    File.basename(skill_dir)
+  end
+
+  def violation(check:, skill:, file:, line:, rule:, message:)
+    { check: check, skill: skill, file: file, line: line, rule: rule, message: message }
+  end
+
+  # Frontmatter split uses the shared convention (scripts/lib/intent_validator.rb):
+  # `content.split("---", 3)`; parts[1] is the frontmatter text, parts[2] is the
+  # body. Also computes the body's starting line number (0-based line count of
+  # everything before the body) so callers can report absolute file line
+  # numbers, not just body-relative ones.
+  def frontmatter_and_body(content)
+    parts = content.split("---", 3)
+    return { frontmatter: nil, body: content, body_offset_lines: 0 } if parts.length < 3
+
+    prefix_len = parts[0].length + 3 + parts[1].length + 3
+    prefix = content[0...prefix_len]
+    { frontmatter: parts[1], body: parts[2], body_offset_lines: prefix.count("\n") }
+  end
+
+  # --- 1. body-budget ---
+
+  def check_body_budget(skill_dir, skill_md, content)
+    violations = []
+    body = frontmatter_and_body(content)[:body]
+    name = skill_name(skill_dir)
+
+    line_count = body.lines.count
+    if line_count >= 500
+      violations << violation(
+        check: "body-budget", skill: name, file: skill_md, line: nil,
+        rule: "body under 500 lines",
+        message: "SKILL.md body is #{line_count} lines; move detail into references/*.md to get under 500"
+      )
+    end
+
+    tokens = (body.split(/\s+/).reject(&:empty?).length * 1.3).round
+    if tokens >= 5000
+      violations << violation(
+        check: "body-budget", skill: name, file: skill_md, line: nil,
+        rule: "body under about 5000 tokens (word-based estimate)",
+        message: "SKILL.md body is about #{tokens} tokens (word-based estimate); move detail into references/*.md to get under 5000"
+      )
+    end
+
+    violations
+  end
+
+  # --- 2. frontmatter-validity ---
+
+  def check_frontmatter_validity(skill_dir, skill_md, content)
+    violations = []
+    name = skill_name(skill_dir)
+    frontmatter_text = frontmatter_and_body(content)[:frontmatter]
+
+    begin
+      fm = YAML.safe_load(frontmatter_text.to_s)
+    rescue Psych::SyntaxError
+      violations << violation(
+        check: "frontmatter-validity", skill: name, file: skill_md, line: nil,
+        rule: "frontmatter must survive strict YAML.safe_load",
+        message: "SKILL.md frontmatter fails YAML.safe_load; quote scalar values that contain an unquoted \": \" sequence"
+      )
+      return violations
+    end
+    fm = {} unless fm.is_a?(Hash)
+
+    expected_name = "plastic-#{name}"
+    if fm["name"] != expected_name
+      violations << violation(
+        check: "frontmatter-validity", skill: name, file: skill_md, line: nil,
+        rule: "name: must equal plastic-<directory>",
+        message: "frontmatter name: is #{fm["name"].inspect}; expected #{expected_name.inspect}"
+      )
+    end
+
+    user_invocable = fm["user-invocable"]
+    unless user_invocable == true || user_invocable == false
+      violations << violation(
+        check: "frontmatter-validity", skill: name, file: skill_md, line: nil,
+        rule: "user-invocable: must be present and boolean",
+        message: "frontmatter user-invocable: is #{user_invocable.inspect}; must be present and true or false"
+      )
+    end
+
+    violations
+  end
+
+  # --- 3. bare-pointer ---
+
+  def check_bare_pointer(skill_dir, skill_md, content)
+    violations = []
+    ref_files = Dir.glob(File.join(skill_dir, "references", "*.md")).sort
+    return violations if ref_files.empty?
+
+    parsed = frontmatter_and_body(content)
+    body_lines = parsed[:body].lines
+    offset = parsed[:body_offset_lines]
+    blocks = paragraph_blocks(body_lines)
+    name = skill_name(skill_dir)
+
+    ref_files.each do |ref_file|
+      base = File.basename(ref_file)
+      mention_indices = (0...body_lines.length).select { |i| body_lines[i].include?(base) }
+      next if mention_indices.empty? # zero mentions is an orphan (check 4), not a bare pointer
+
+      bound = mention_indices.any? { |i| bound_mention?(body_lines[i], i, blocks, base) }
+      next if bound
+
+      first = mention_indices.first
+      violations << violation(
+        check: "bare-pointer", skill: name, file: skill_md, line: offset + first + 1,
+        rule: "every reference link must bind to an observable trigger condition, never a bare pointer",
+        message: "#{base} is only ever a bare pointer; add a when/if/before/after/while clause or a " \
+                  "to/for purpose so the trigger is observable"
+      )
+    end
+
+    violations
+  end
+
+  def bound_mention?(line, index, blocks, base)
+    stripped = line.strip
+    return table_row_bound?(stripped, base) if stripped.start_with?("|")
+
+    block = blocks.find { |b| index.between?(b[:start], b[:end]) }
+    block_text = block ? block[:text] : line
+
+    # Narrow to the unit(s) that actually mention the reference, so an
+    # unrelated unit elsewhere in the same paragraph cannot launder a
+    # genuinely bare pointer through an incidental "to"/"for" (an ordinary
+    # preposition, not a binding purpose clause). Split on BOTH sentence
+    # boundaries (.!?) AND list-item starts, so a bullet list (which has no
+    # terminal punctuation between items) does not collapse into one unit
+    # whose bound siblings launder a bare bullet -- the trailing "References"
+    # list pattern (most bullets bound, one forgotten) this linter exists to
+    # catch. Keep only units that mention `base`. Falls back to the whole
+    # block when no unit boundary contains the mention (e.g. a mid-sentence
+    # line wrap with no terminal punctuation nearby), so the legitimate
+    # multi-line-wrapped case still binds.
+    #
+    # Known conservative limitation (documented, not closed): a bare mention
+    # with NO unit boundary of its own (no leading list marker, no preceding
+    # terminal punctuation) immediately followed by an unrelated sentence
+    # carrying "to"/"for" can still borrow that neighbor's binding via the
+    # empty-fallback path. Closing this structurally risks re-breaking the
+    # legitimate wrapped-sentence case (which also relies on the fallback),
+    # so it stays open; see intent 85b insights.
+    units = block_text.split(/(?<=[.!?])\s+|\n(?=\s*(?:[-*+]|\d+[.)])\s)/)
+    mentioning = units.select { |s| s.include?(base) }
+    scoped_text = mentioning.empty? ? block_text : mentioning.join(" ")
+
+    scoped_text.match?(BINDING_KEYWORD_RE) || scoped_text.match?(PURPOSE_RE)
+  end
+
+  # A table row is bound when some OTHER cell (not the one carrying the
+  # reference path) has visible text (the trigger-condition column).
+  def table_row_bound?(stripped_line, base)
+    cells = stripped_line.split("|").map(&:strip).reject(&:empty?)
+    other_cells = cells.reject { |c| c.include?(base) }
+    !other_cells.empty?
+  end
+
+  # Group body lines into blank-line-delimited paragraph blocks so a mention
+  # that trails a wrapped sentence (the binding keyword on the line above) is
+  # still evaluated against its full paragraph, not just its own physical line.
+  def paragraph_blocks(lines)
+    blocks = []
+    start = nil
+    lines.each_with_index do |line, i|
+      if line.strip.empty?
+        blocks << { start: start, end: i - 1, text: lines[start..(i - 1)].join } if start
+        start = nil
+      else
+        start ||= i
+      end
+    end
+    blocks << { start: start, end: lines.length - 1, text: lines[start..-1].join } if start
+    blocks
+  end
+
+  # --- 4. orphan-files ---
+
+  def check_orphan_files(skill_dir)
+    violations = []
+    ref_files = Dir.glob(File.join(skill_dir, "references", "*.md")).sort
+    return violations if ref_files.empty?
+
+    other_files = Dir.glob(File.join(skill_dir, "**", "*")).select { |p| File.file?(p) }
+    name = skill_name(skill_dir)
+
+    ref_files.each do |ref_file|
+      base = File.basename(ref_file)
+      mentioned = other_files.any? do |other|
+        next false if other == ref_file
+
+        File.read(other).include?(base)
+      end
+      next if mentioned
+
+      violations << violation(
+        check: "orphan-files", skill: name, file: ref_file, line: nil,
+        rule: "every references/ file must be routed from the skill",
+        message: "#{base} is never mentioned anywhere in the skill directory; route it from SKILL.md or delete it"
+      )
+    end
+
+    violations
+  end
+
+  # --- 5. references-depth ---
+
+  def check_references_depth(skill_dir)
+    violations = []
+    refs_root = File.join(skill_dir, "references")
+    return violations unless File.directory?(refs_root)
+
+    name = skill_name(skill_dir)
+    Dir.glob(File.join(refs_root, "**", "*")).each do |path|
+      next unless File.file?(path)
+
+      rel = path.sub("#{refs_root}/", "")
+      next unless rel.include?("/")
+
+      violations << violation(
+        check: "references-depth", skill: name, file: path, line: nil,
+        rule: "references stay one level deep",
+        message: "#{rel} is nested under references/; move it to a flat references/*.md file"
+      )
+    end
+
+    violations
+  end
+end

package/scripts/skill-lint

@@ -0,0 +1,50 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# skill-lint: deterministic CLI over SkillLint (intent 85b).
+#
+# Runs the five structural skill checks (body-budget, frontmatter-validity,
+# bare-pointer, orphan-files, references-depth) over a directory of Agent
+# Skills and reports every violation. Mirrors `scripts/validate-intent`'s
+# CLI-over-lib shape and exit-code contract.
+#
+# Usage:
+#   skill-lint [--skills-dir <path>]
+#
+# Exit codes: 0 (clean), 1 (violations found; reported on stderr), 2 (usage).
+# --skills-dir defaults to the repo skills/ directory next to this script.
+
+require_relative "lib/skill_lint"
+
+def resolve_skills_dir(args)
+  if (i = args.index("--skills-dir"))
+    args[i + 1]
+  else
+    File.expand_path("../skills", __dir__)
+  end
+end
+
+if ARGV.any? { |a| a.start_with?("--") && a != "--skills-dir" }
+  warn "usage: skill-lint [--skills-dir <path>]"
+  exit 2
+end
+
+if ARGV.include?("--skills-dir") && ARGV[ARGV.index("--skills-dir") + 1].nil?
+  warn "usage: skill-lint [--skills-dir <path>]"
+  exit 2
+end
+
+dir = File.expand_path(resolve_skills_dir(ARGV))
+result = SkillLint.new(skills_dir: dir).run
+
+if result.ok?
+  puts "OK: #{dir}"
+  exit 0
+end
+
+warn "VIOLATIONS: #{dir}"
+result.violations.each do |v|
+  warn "#{v[:check]} #{v[:skill]} #{v[:file]}:#{v[:line].nil? ? "-" : v[:line]} #{v[:message]}"
+end
+exit 1

package/skills/auto/SKILL.md

@@ -70,8 +70,10 @@ and artifact depth to that size. Extended walkthrough: `references/tiers.md`.
    every tier and in both modes. A three-line spec.md is still a spec.md, in the same
    place, under the same gate.
 3. **Per-tier topology.** S/M: one thinker agent, one boot, two stations, sonnet
-   executor, `actions/` skipped; S may also skip the QMD discovery deposit when chain and
-   sources are both empty. L: today's full team (`## Team Spin-Up` below).
+   executor; the thinker writes at least one real action file (one consolidated
+   `actions/ACTION_1.md`), never an empty `actions/`. S may also skip the QMD discovery
+   deposit when chain and sources are both empty. L: today's full team (`## Team Spin-Up`
+   below), one `actions/ACTION_N.md` per task.
 4. **Never-cut list**, any tier or mode: the independent reviewer (separate agent, fresh
    context, never the maker), `outcome.md` as truth of delivery, the delivery lock,
    worktree isolation, intent creation via skill, INDEX as status truth, the QMD reindex
@@ -203,14 +205,15 @@ Then proceed to How.
 
 ## How Phase
 
-This is the L-tier shape (see `## Tiers` above); S/M skip step 3 and fold the checklist
-rationale into plan.md inline. The `actions/` directory itself is scaffolded empty at
-intent birth and persists at every tier; only writing `ACTION_N.md` files into it is L
-only (S/M leave the directory empty).
+Every tier runs all four steps below (see `## Tiers` above). The `actions/` directory is
+scaffolded (with a `.gitkeep`) at intent birth; the planner then writes at least one REAL
+`ACTION_N.md` into it at every tier. The tier only changes step 3's granularity: S/M write
+one consolidated `actions/ACTION_1.md`, L writes one `actions/ACTION_N.md` per task. A
+`.gitkeep`-only or empty `actions/` fails the How gate.
 
 1. If `superpowers:writing-plans` is available as a skill, delegate plan creation to it. Tell it the plan saves to the active intent's directory (not `docs/superpowers/plans/`).
 2. Otherwise, write `plan.md` directly - implementation plan with numbered tasks
-3. Write `ACTION_N.md` files into the existing `actions/` directory (one per task, self-contained) - L only
+3. Write at least one real `ACTION_N.md` into the existing `actions/` directory, self-contained (S/M: one consolidated `ACTION_1.md`; L: one per task)
 4. Write `checklist.md` - execution registry with checkboxes covering all actions
 5. Notify user (How briefing): brief per `references/human-report-contract.md`
    (State: the plan shape, task count and what it builds; Risk: the riskiest task or

package/skills/auto/references/tiers.md

@@ -30,9 +30,10 @@ the savepoint ledger.
 One thinker agent boots ONCE and stays in a single context for two stations:
 
 1. Station 1 — writes `spec.md` (collapsed sections allowed, one line each is valid).
-2. Station 2 — writes `plan.md` + `checklist.md` in the SAME context (no reboot). plan.md
-   carries the checklist rationale inline instead of separate `actions/ACTION_N.md` files.
-   `actions/` is not created for S/M.
+2. Station 2 — writes `plan.md` + `checklist.md` + at least one real action file in the
+   SAME context (no reboot). At S/M the thinker consolidates the whole delivery into one
+   `actions/ACTION_1.md` (rather than one file per task); `actions/` is populated at every
+   tier, and a `.gitkeep`-only or empty `actions/` fails the How gate.
 
 Then a sonnet executor (a fresh dispatch, this is the one topology split that always
 happens) implements from plan.md + checklist.md, checks off items, appends `## Insights`,

package/skills/intent-planning/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: plastic-intent-planning
-description: "Write implementation plans from a spec. Produces plan.md, checklist.md, and (L tier only) actions/ in the active intent directory."
+description: "Write implementation plans from a spec. Produces plan.md, checklist.md, and at least one real actions/ACTION_N.md (every tier) in the active intent directory."
 user-invocable: true
 ---
 
@@ -31,12 +31,12 @@ If the spec covers multiple independent subsystems, it should have been broken i
 
 ## Tier shapes
 
-Read the spec's stamped `Tier:` line (written by intent-speccing) and pick the plan shape it calls for:
+Read the spec's stamped `Tier:` line (written by intent-speccing) and pick the action shape it calls for. Every tier produces at least one REAL action file in `actions/`; the tier only changes how many:
 
-- **S or M (default):** an inline plan-as-checklist. Tasks live directly in `plan.md` with rationale inline; `checklist.md` mirrors the task list. Do NOT create any `actions/` files. Leave the `actions/` directory empty (or absent).
+- **S or M (default):** write ONE consolidated `actions/ACTION_1.md` that carries the whole ordered delivery (the steps plus the exact changes). `plan.md` still holds the overall map and `checklist.md` still mirrors the task list. You may split into a few action files when that reads cleaner, but one real action file is the floor.
 - **L (many independent tasks, dispatched in parallel):** self-contained `actions/ACTION_N.md`, one per task, each readable without the plan (see `references/plan-format.md`).
 
-Default to inline for S and M. Reserve `actions/` for L, where tasks are independent enough to hand to separate subagents in parallel. When in doubt, prefer inline; creating unnecessary `actions/` files is a plan failure at S/M tier.
+A `.gitkeep` never counts as an action, and an empty `actions/` fails the How gate at every tier. At S/M, keep it to a single consolidated action file rather than one-per-task; over-splitting a small intent is the S/M failure mode, an empty `actions/` is the tier-wide one.
 
 ## File Structure
 
@@ -97,11 +97,11 @@ If you find issues, fix them inline. No need to re-review, just fix and move on.
 ## Plastic Artifacts
 
 After writing `plan.md`, create `checklist.md` (execution registry following the
-FORM: `## In Progress`, `## Completed`, `## Session Log`) in the intent directory.
-For L tier only, also create `actions/ACTION_N.md` (one self-contained file per
-task, in an `actions/` directory inside the intent directory). For S/M tier, do
-not create `actions/` files at all (see Tier shapes above). For the exact format
-of both, read `references/plan-format.md`.
+FORM: `## In Progress`, `## Completed`, `## Session Log`) and at least one real
+`actions/ACTION_N.md` (self-contained, in an `actions/` directory inside the intent
+directory). At S/M write one consolidated `actions/ACTION_1.md`; at L write one
+`actions/ACTION_N.md` per task (see Tier shapes above). For the exact format of
+both, read `references/plan-format.md`.
 
 ## Owner-decision hard-gate items
 
@@ -118,12 +118,12 @@ When collecting owner rulings for `[ORCHESTRATOR]` hard-gate items, read
 ## Gate position
 
 - **Before:** `spec.md` exists.
-- **Produces:** `plan.md` and `checklist.md` (plus `actions/` for L tier only).
+- **Produces:** `plan.md`, `checklist.md`, and at least one real `actions/ACTION_N.md` (every tier; one consolidated file at S/M, one per task at L).
 - **Next:** /plastic-intent-executing.
 
 ## Git Commit
 
-After writing all artifacts (plan.md, checklist.md, actions/ for L tier), commit to the store:
+After writing all artifacts (plan.md, checklist.md, and the actions/ACTION_N.md files), commit to the store:
 
 ```bash
 cd {store_root} && git add . && git commit -m "docs: plan for intent {id}: {name}"

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

@@ -1,18 +1,18 @@
 {
   "skill_name": "plastic-intent-planning",
-  "notes": "Intent 164. New evals.json for the writing-plans skill: tier-shape enforcement (S/M inline vs L actions/) and the checklist FORM plus [ORCHESTRATOR] hard-gate item convention. All assertions are pending a real observed run per the plastic-evaluating-skills convention.",
+  "notes": "Intent 164, updated by 133a. Evals for the writing-plans skill: action-file enforcement at every tier (S/M consolidate the delivery into one real actions/ACTION_1.md, L writes one actions/ACTION_N.md per task) and the checklist FORM plus [ORCHESTRATOR] hard-gate item convention. All assertions are pending a real observed run per the plastic-evaluating-skills convention.",
   "evals": [
     {
       "id": 1,
       "scope": "behavior",
       "set": "train",
       "prompt": "spec.md is stamped Tier: M and describes a single subsystem change touching four files across two tasks. Write the plan.",
-      "expected_output": "Produces an inline plan-as-checklist: all tasks with rationale live directly in plan.md, and checklist.md mirrors the task list. No actions/ACTION_N.md files are created; the actions/ directory stays empty or absent.",
+      "expected_output": "Produces plan.md plus checklist.md plus at least one real actions/ACTION_N.md. At M the planner consolidates the whole delivery into a single actions/ACTION_1.md (it may split into a few files if that reads cleaner); the actions/ directory is never left empty or .gitkeep-only. checklist.md mirrors plan.md's task list.",
       "files": [],
       "assertions": [
         {
           "type": "code",
-          "check": "no files created under actions/ for this intent; checklist.md exists and mirrors plan.md's task list",
+          "check": "at least one real (non-empty, non-.gitkeep) file exists under actions/ for this intent; checklist.md exists and mirrors plan.md's task list",
           "result": "expect-pass"
         }
       ]
@@ -22,12 +22,12 @@
       "scope": "behavior",
       "set": "train",
       "prompt": "spec.md is stamped Tier: S and describes a single-file config change. Write the plan.",
-      "expected_output": "Produces an inline plan-as-checklist. No actions/ files are created, matching the S/M default.",
+      "expected_output": "Produces plan.md plus checklist.md plus one consolidated actions/ACTION_1.md carrying the whole ordered delivery (the steps plus the exact changes). The actions/ directory is never left empty or .gitkeep-only, matching the every-tier action-file rule.",
       "files": [],
       "assertions": [
         {
           "type": "code",
-          "check": "no files created under actions/ for this intent",
+          "check": "at least one real (non-empty, non-.gitkeep) actions/ACTION_N.md exists under actions/ for this intent; no empty or .gitkeep-only actions/ dir remains",
           "result": "expect-pass"
         }
       ]
@@ -61,6 +61,21 @@
           "result": "expect-pass"
         }
       ]
+    },
+    {
+      "id": 5,
+      "scope": "behavior",
+      "set": "validation",
+      "prompt": "spec.md is stamped Tier: S. A prior draft left actions/ with only a .gitkeep. Write the plan and its actions.",
+      "expected_output": "Writes at least one real actions/ACTION_1.md (non-empty, not the placeholder sentinel, not a .gitkeep) that consolidates the whole S-tier delivery. Leaving actions/ empty or .gitkeep-only is a plan failure that would block the How gate; the planner never does this at any tier.",
+      "files": [],
+      "assertions": [
+        {
+          "type": "code",
+          "check": "actions/ contains at least one real action file (non-empty *.md, first line not the placeholder sentinel); no .gitkeep-only or empty actions/ dir remains",
+          "result": "expect-pass"
+        }
+      ]
     }
   ]
 }

package/skills/intent-planning/references/plan-format.md

@@ -28,8 +28,9 @@ plan.md so the shape matches on the first pass.
 
 **Intent:** {id}: {name}
 
-**Tier:** S|M|L, copied from the spec's stamped `Tier:` line. S and M plans are
-inline plan-as-checklist (no `actions/`); L plans use `actions/ACTION_N.md`.
+**Tier:** S|M|L, copied from the spec's stamped `Tier:` line. Every tier produces at
+least one real `actions/ACTION_N.md`; S and M consolidate the delivery into one action
+file, L uses one `actions/ACTION_N.md` per task.
 
 ---
 ```
@@ -112,10 +113,13 @@ of tier (S, M, or L):
 
 ## actions/ACTION_N.md format
 
-L tier only. S and M plans skip this file type entirely; their tasks live
-inline in `plan.md` (see the parent SKILL.md's `## Tier shapes`).
+Every tier writes at least one real action file here (see the parent SKILL.md's
+`## Tier shapes`): S and M consolidate the whole delivery into a single
+`actions/ACTION_1.md`, L writes one file per task.
 
-One file per task. Each action is self-contained: a subagent can execute it without reading the plan.
+Each action is self-contained: a subagent (or a solo executor) can execute it without
+reading the plan. It carries the ordered steps to deliver the task plus the exact changes
+to make (for code, the anchor or `file:line` and the old/new text).
 
 ```markdown
 # Action {N}: {task title}

package/skills/tutorial/references/track-1-guided.md

@@ -71,10 +71,11 @@ an answer given in station 3.
 
 Type `/plastic-intent-planning`.
 
-Artifact: `plan.md` and `checklist.md`. At the S tier used here, `actions/` stays empty and
-the task rationale lives inline in `plan.md` instead of separate action files; only the L
-tier (many independent tasks, dispatched in parallel) gets one `actions/ACTION_N.md` file
-per task. `checklist.md` follows a fixed form: tasks start under `## In Progress`, move to
+Artifact: `plan.md`, `checklist.md`, and at least one real `actions/ACTION_N.md`. At the S
+tier used here, the planner consolidates the whole delivery into a single
+`actions/ACTION_1.md` (the ordered steps plus the exact changes); the L tier (many
+independent tasks, dispatched in parallel) instead gets one `actions/ACTION_N.md` file per
+task. `checklist.md` follows a fixed form: tasks start under `## In Progress`, move to
 `## Completed` as they land, and a `## Session Log` table records what happened each session.
 A task that depends on an owner decision landing first (a destructive step, a structural
 ruling) gets an `[ORCHESTRATOR]` prefix and blocks every other item until that decision is