@zalom/plastic 1.1.1 → 1.1.3

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/feedback/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: plastic-feedback
+description: Use when the user hits a Plastic quirk, bug, or feature idea in a project and wants to report it back to the Plastic project. Builds a sanitized report file and a prefilled GitHub issue URL the user reviews and submits. Only the user sends.
+disable-model-invocation: true
+user-invocable: true
+---
+
+# Plastic Feedback
+
+Turn a described Plastic problem into a local report file and a prefilled GitHub
+issue URL. The script does the mechanics (redaction, naming, URL building); the
+user alone opens the URL and submits it. This skill has no send step, by design.
+
+Because `disable-model-invocation` hides this skill's description from your own
+context, you cannot discover it by browsing available skills mid-task. If the
+user hits a Plastic quirk, bug, or missing feature, offer to run
+`/plastic-feedback` yourself; do not wait for the user to ask for it by name.
+
+## Procedure
+
+### 1. Gather the narrative
+
+Ask the user for:
+- What happened (the observed behavior).
+- The root cause, if they already know it.
+- The expected behavior.
+
+Keep it to about one page. Do not pad it with speculation; a short, accurate
+report beats a long, padded one.
+
+### 2. Obfuscate before it leaves this session
+
+Before filling the template, strip anything that identifies the user's project
+or its content:
+- Remove project names, directory paths, and file names specific to the user's
+  codebase.
+- Turn any Plastic intent names into their bare numeric or slug ids (drop the
+  descriptive title if it leaks project context).
+- Keep only Plastic's own operational content: what Plastic did, what it should
+  have done, which command or hook was involved.
+
+Read `references/transport-and-privacy.md` before filling the template, for the
+full obfuscation checklist and the reasoning behind it.
+
+### 3. Fill the report template
+
+Read `report.md` from this skill's directory (`~/.plastic/skills/feedback/report.md`
+at runtime, or the plugin source `skills/feedback/report.md` during development).
+Fill every placeholder except `{{plastic_version}}`, which the script fills.
+Assemble the final markdown body from the filled template.
+
+### 4. Run the script
+
+```bash
+ruby ~/.plastic/scripts/feedback-report --title "<short title>"
+```
+
+Pipe the filled body on STDIN. Parse the JSON on stdout:
+
+| Key | Meaning |
+|---|---|
+| `report_path` | Local file the full, uncapped report was written to |
+| `url` | Prefilled GitHub new-issue URL |
+| `encoded_url_bytes` | Byte length of the encoded URL |
+| `truncated` | Whether the URL body is a capped page-one, not the full report |
+| `page_break_note` | The end-marker text appended when `truncated` is true, else null |
+
+The script only ever writes a local file and prints a URL. It has no network
+call, no token, and no way to open a browser or submit anything on its own.
+
+### 5. Present the result
+
+Show the user:
+- The local file path (`report_path`).
+- A short preview of the report.
+- The URL.
+
+If `truncated` is true, tell the user plainly: the URL carries page one of the
+report, and the full report is in the local file at `report_path`. They can
+paste more from the local file into the opened issue if they want.
+
+Then tell them, in these words or close to them: open the URL, review it, drag
+a screenshot onto the form if they have one, and submit it under their own
+GitHub account. Or, if they would rather edit first, copy the local file
+contents into a new issue themselves.
+
+### 6. Never submit
+
+State plainly that this skill has no send step: it never posts to GitHub, never
+runs `gh issue create`, and never opens a browser on the user's behalf. The user
+is the only one who can submit the report.
+
+## Gotchas
+
+- If the described report is long, the script may hand back `truncated: true`.
+  This is expected, not an error: the local file always holds the full text.
+- Do not try to route around the missing send step (no `gh` call, no API POST).
+  The absence of a send path is the point of this skill, not a gap to fill.

package/skills/feedback/references/transport-and-privacy.md

@@ -0,0 +1,65 @@
+# Transport and Privacy
+
+Read this before filling `report.md` and before presenting the URL to the user.
+
+## Obfuscation checklist (do this before filling the template)
+
+Run through this list on the narrative gathered from the user, before it goes
+into `report.md`:
+
+- Strip project names. Refer to "the project" or "a consumer project", never
+  the user's actual project name.
+- Strip file paths and directory names specific to the user's codebase.
+- Turn Plastic intent names into their bare ids. Drop the descriptive title if
+  it names project content (an intent title like "Fix the checkout flow" leaks
+  what the user is building; "intent 42" does not).
+- Keep only Plastic's own operational content: which command, hook, or skill
+  ran, what it did, what it should have done instead.
+- Before presenting the URL, re-read the filled report once and confirm none
+  of the above slipped back in.
+
+## Mechanical redaction (what the script also strips)
+
+`scripts/lib/feedback_report.rb` redacts these patterns to `[REDACTED]` before
+the report ever touches disk, as a second, mechanical layer under the
+obfuscation above:
+
+| Secret kind | Pattern shape |
+|---|---|
+| GitHub tokens | `ghp_`, `gho_`, `ghs_`, `ghr_`, `ghu_`, `github_pat_` prefixes |
+| Anthropic/OpenAI keys | `sk-ant-...`, `sk-...` |
+| AWS access key id | `AKIA...` |
+| Bearer tokens | `Bearer <token>` |
+| Slack tokens | `xoxb-`, `xoxa-`, `xoxp-`, `xoxr-`, `xoxs-` prefixes |
+| Google API keys | `AIza...` |
+| PEM private key blocks | `-----BEGIN ... PRIVATE KEY----- ... -----END ... PRIVATE KEY-----` |
+| Key/value assignments | `api_key = ...`, `secret: ...`, `token = ...`, `password: ...` (value only) |
+
+Treat this list as a safety net, not the primary defense. The mechanical
+patterns catch a specific, known shape; the obfuscation pass above is what
+catches project-identifying context a regex cannot recognize.
+
+## Why a prefilled URL, and not something else
+
+The report is sent by opening a prefilled `https://github.com/zalom/plastic/issues/new`
+URL in the user's own browser. Submission happens in an authenticated session
+that belongs to the user, not to the agent or the script. Nothing in this
+skill or in `feedback-report` can complete that submission on its own: there
+is no send method, no token, and no network call anywhere in the code path.
+
+Other transports were considered and rejected:
+
+- **`gh issue create`**: the CLI can send on its own; only `--web` is
+  browser-submitted, and the plain form cannot be guaranteed not to send
+  directly. It also assumes `gh` auth, which a consumer-project user may not
+  have.
+- **An API POST with a token**: the agent could send it, and the token itself
+  becomes a credential worth stealing.
+- **An anonymous POST endpoint**: still agent-reachable, with no built-in spam
+  resistance, and it needs server infrastructure this project does not run.
+- **Email or `git send-email`**: the CLI sends the message, review is opt-in
+  rather than forced, and it needs a working mail transport most machines do
+  not have configured.
+
+Only the prefilled-URL approach makes "the agent cannot send" a structural
+fact instead of a rule the agent could break by taking a shortcut.

package/skills/feedback/report.md

@@ -0,0 +1,36 @@
+# Plastic feedback: {{title}}
+
+<!-- =======================================================================
+  AGENT INSTRUCTIONS -- How to fill this template
+  =========================================================================
+  1. Replace every {{placeholder}} below with real content gathered from the
+     user, except {{plastic_version}}: leave that token exactly as written,
+     the feedback-report script fills it from the installed VERSION file.
+  2. Obfuscate first (see references/transport-and-privacy.md): strip project
+     names, file paths, and anything else that identifies the user's
+     codebase. Keep only Plastic's own operational content.
+  3. Keep the report to about one page. Use tables or short lists where they
+     make the report clearer than prose.
+  4. Delete this entire HTML comment block before piping the body into
+     feedback-report. It is fill instructions only, not report content.
+  ======================================================================= -->
+
+## Environment
+
+| Field | Value |
+|---|---|
+| Plastic version | {{plastic_version}} |
+| Agent | {{agent_name}} |
+| OS | {{os}} |
+
+## What happened
+
+{{what_happened}}
+
+## Root cause (if known)
+
+{{root_cause_or_not_known}}
+
+## Expected behavior
+
+{{expected_behavior}}

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}"