@zalom/plastic 1.1.1 → 1.1.3

package/PLASTIC-reference.md

@@ -127,6 +127,7 @@ Detailed conventions live inside the skills that use them, not in this file.
 | Index maintenance | `plastic-store-indexing` | — |
 | Releases, deprecations | `plastic-releasing` | deprecation process |
 | Health diagnostics | `plastic-doctor` | three scopes: `--core` (binary install-integrity check, runs on SessionStart), `--store [global\|<slug>]` (per-store check, runs on dashboard load), no flag = full check (runs after every update); gate enforcement, stuck detection |
+| Report a Plastic quirk, bug, or feature idea | `plastic-feedback` | transport and privacy (redaction checklist, why a prefilled URL) |
 | Authoring skills, agents, hooks | `plastic-skill-creating` | progressive disclosure, agentskills.io spec |
 | Evaluating skills, evals | `plastic-skill-evaluating` | eval methodology, convention checks |
 | Create, order, and consume a roadmap of intents | `plastic-roadmap` | file format, operations |

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
@@ -242,6 +243,11 @@ Beyond the lifecycle agents, Plastic ships thin skills for day-to-day operation:
   `plastic-rollback`, intent 55) are thin wrappers over a single pinned
   `npx -y @zalom/plastic@<channel> <verb>` call: initialize or repair an install, advance a
   channel, remove Plastic, and step the local versions ledger.
+- **`plastic-feedback`** (intent 174) turns a described Plastic quirk, bug, or feature idea
+  into a redacted local report file and a prefilled GitHub issue URL; only the user can submit
+  it. `disable-model-invocation` hides its description from your own context, so if the user
+  hits a Plastic quirk, bug, or missing feature, offer to run `/plastic-feedback` yourself
+  instead of waiting to be asked; the user still sends it, you never do.
 
 ## Releases and Versioning
 
@@ -425,8 +431,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 +536,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.3",
   "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/feedback-report

@@ -0,0 +1,54 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# feedback-report - thin CLI over FeedbackReport (intent 174).
+#
+# Reads a redacted-ready markdown body from STDIN, composes a local report
+# file plus a prefilled GitHub new-issue URL, writes the file, and prints the
+# result as JSON. This script has no send path: it never contacts GitHub and
+# never holds a credential. Only the human, opening the printed URL in their
+# own browser, submits anything.
+#
+# Usage:
+#   feedback-report --title "<short title>" < body.md
+#
+# Exit codes: 0 (success), 1 (error composing/writing the report), 2 (usage).
+
+require "json"
+require_relative "lib/feedback_report"
+
+def parse_title(argv)
+  i = argv.index("--title")
+  return nil unless i && argv[i + 1]
+
+  argv[i + 1]
+end
+
+title = parse_title(ARGV)
+
+if title.nil? || title.strip.empty?
+  warn 'usage: feedback-report --title "<short title>" < body.md'
+  exit 2
+end
+
+body = $stdin.read
+
+begin
+  home = File.join(Dir.home, ".plastic")
+  engine = FeedbackReport.new(plastic_home: home)
+  result = engine.compose(title: title, body: body)
+  engine.persist(result)
+
+  puts JSON.pretty_generate(
+    report_path: result.report_path,
+    url: result.url,
+    encoded_url_bytes: result.encoded_url_bytes,
+    truncated: result.truncated,
+    page_break_note: result.page_break_note
+  )
+  exit 0
+rescue StandardError => e
+  warn "feedback-report error: #{e.message}"
+  exit 1
+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/feedback_report.rb

@@ -0,0 +1,168 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "cgi"
+require "fileutils"
+
+# FeedbackReport: deterministic, dependency-injected engine that turns a
+# title and an agent-assembled markdown body into a redacted local report
+# file plus a prefilled GitHub new-issue URL (intent 174).
+#
+# Constructor DI, no `eval`, no ENV reads, no globals, stdlib only. Pure
+# methods (`redact`, `fill_version`, `slug_for`, `report_path`, `build_url`,
+# `apply_cap`, `compose`) plus one explicit side-effecting `persist`. Mirrors
+# the engine-in-lib shape of `scripts/lib/skill_lint.rb`: the `feedback-report`
+# CLI is a thin wrapper, `test/feedback_report_test.rb` proves the engine
+# hermetically against an injected `plastic_home` and a fixed `now`.
+#
+# Trust model: this class never sends anything anywhere. `compose` returns a
+# Result carrying a local file path and a browser URL; only the human, in
+# their own authenticated browser, submits it. There is no send method here
+# and there must never be one (see skills/feedback/references/transport-and-privacy.md).
+class FeedbackReport
+  GITHUB_REPO = "zalom/plastic"
+  CAP_BYTES = 7500
+
+  Result = Struct.new(:report_path, :body, :url, :encoded_url_bytes, :truncated, :page_break_note, keyword_init: true)
+
+  # Ordered [Regexp, replacement] pairs. Order matters: `sk-ant-` must be
+  # tried before the shorter `sk-` pattern so the longer form wins, and the
+  # generic key/value assignment pattern runs last as a catch-all so it does
+  # not steal a match a more specific pattern would have redacted more
+  # precisely. Each pattern replaces the matched secret span with
+  # `[REDACTED]`; the assignment pattern keeps the key name and separator and
+  # redacts only the value.
+  REDACTIONS = [
+    [/\bgh[posru]_[A-Za-z0-9]{20,}\b/, "[REDACTED]"],
+    [/\bgithub_pat_[A-Za-z0-9_]{20,}\b/, "[REDACTED]"],
+    [/\bsk-ant-[A-Za-z0-9\-]{20,}\b/, "[REDACTED]"],
+    [/\bsk-[A-Za-z0-9]{20,}\b/, "[REDACTED]"],
+    [/\bAKIA[0-9A-Z]{16}\b/, "[REDACTED]"],
+    [/\bBearer\s+[A-Za-z0-9._\-]{20,}/, "[REDACTED]"],
+    [/\bxox[baprs]-[A-Za-z0-9\-]{10,}/, "[REDACTED]"],
+    [/\bAIza[0-9A-Za-z_\-]{35}\b/, "[REDACTED]"],
+    [/-----BEGIN[ A-Z]*PRIVATE KEY-----[\s\S]*?-----END[ A-Z]*PRIVATE KEY-----/, "[REDACTED]"],
+    [/\b(api[_-]?key|secret|token|password)\b(\s*[:=]\s*)\S+/i, '\1\2[REDACTED]'],
+  ].freeze
+
+  def initialize(plastic_home:, now: Time.now, github_repo: GITHUB_REPO, cap_bytes: CAP_BYTES)
+    @plastic_home = plastic_home
+    @now = now
+    @github_repo = github_repo
+    @cap_bytes = cap_bytes
+  end
+
+  # Apply every redaction pattern in order and return the cleaned string.
+  def redact(text)
+    REDACTIONS.reduce(text) { |acc, (pattern, replacement)| acc.gsub(pattern, replacement) }
+  end
+
+  # Replace the `{{plastic_version}}` token with the injected VERSION file's
+  # content, or the literal string "unknown" when the file is absent.
+  def fill_version(body)
+    version_file = File.join(@plastic_home, "VERSION")
+    version = File.exist?(version_file) ? File.read(version_file).strip : "unknown"
+    body.gsub("{{plastic_version}}", version)
+  end
+
+  # Kebab-case a title: downcase, collapse any run of non [a-z0-9] into one
+  # hyphen, trim leading/trailing hyphens, cap at ~50 chars. Empty input (or
+  # a title with no alphanumerics) falls back to "feedback".
+  def slug_for(title)
+    slug = title.to_s.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-+|-+\z/, "")
+    slug = slug[0, 50].gsub(/-+\z/, "")
+    slug.empty? ? "feedback" : slug
+  end
+
+  # `{plastic_home}/feedback/{YYYY-MM-DD}--{slug}.md`, first free path. A
+  # same-day same-slug collision tries `--2`, `--3`, ... until a free name
+  # is found. This only reads the filesystem to check for a collision; it
+  # never writes (that is `persist`'s job).
+  def report_path(title)
+    dir = File.join(@plastic_home, "feedback")
+    base = "#{@now.strftime('%Y-%m-%d')}--#{slug_for(title)}"
+
+    candidate = File.join(dir, "#{base}.md")
+    return candidate unless File.exist?(candidate)
+
+    n = 2
+    loop do
+      candidate = File.join(dir, "#{base}--#{n}.md")
+      return candidate unless File.exist?(candidate)
+
+      n += 1
+    end
+  end
+
+  # Build the prefilled GitHub new-issue URL. ONLY `title` and `body` params,
+  # percent-encoded. No `template`, no `labels`.
+  def build_url(title, body)
+    enc = ->(s) { CGI.escape(s) }
+    "https://github.com/#{@github_repo}/issues/new?title=#{enc.call(title)}&body=#{enc.call(body)}"
+  end
+
+  # If the full body fits under the byte cap once encoded, return it as-is.
+  # Otherwise binary-search the largest prefix of the body that, plus an
+  # honest end-marker naming the local (uncapped) report file, still fits,
+  # and return that page-one body instead. Returns
+  # [url, url_body, truncated, page_break_note].
+  def apply_cap(title, redacted_body, path)
+    full_url = build_url(title, redacted_body)
+    return [full_url, redacted_body, false, nil] if full_url.bytesize <= @cap_bytes
+
+    end_marker = "\n\n---\nFull report continues in your local file: #{path}\n" \
+                 "Paste the rest below if relevant."
+
+    lo = 0
+    hi = redacted_body.length
+    best_n = 0
+    while lo <= hi
+      mid = (lo + hi) / 2
+      candidate_url = build_url(title, redacted_body[0...mid] + end_marker)
+      if candidate_url.bytesize <= @cap_bytes
+        best_n = mid
+        lo = mid + 1
+      else
+        hi = mid - 1
+      end
+    end
+
+    page_one = redacted_body[0...best_n] + end_marker
+    final_url = build_url(title, page_one)
+    raise "feedback report exceeds cap_bytes even at page one (#{final_url.bytesize} > #{@cap_bytes})" if final_url.bytesize > @cap_bytes
+
+    [final_url, page_one, true, end_marker.strip]
+  end
+
+  # Orchestrate: redact the title, fill the version token and redact the
+  # body, resolve the report path from the REDACTED title (so a secret in
+  # the title never lands in the filename either), then cap the URL. The
+  # title is redacted before it ever reaches build_url/apply_cap, so a
+  # secret pasted into the title cannot ride the `title=` URL param
+  # unredacted. The FULL redacted body always goes to disk; only the URL's
+  # body may be the capped page-one.
+  def compose(title:, body:)
+    redacted_title = redact(title)
+    filled = fill_version(body)
+    redacted_body = redact(filled)
+    path = report_path(redacted_title)
+    url, _url_body, truncated, note = apply_cap(redacted_title, redacted_body, path)
+
+    Result.new(
+      report_path: path,
+      body: redacted_body,
+      url: url,
+      encoded_url_bytes: url.bytesize,
+      truncated: truncated,
+      page_break_note: note
+    )
+  end
+
+  # Write the FULL redacted body to disk. The only side-effecting method on
+  # this class.
+  def persist(result)
+    FileUtils.mkdir_p(File.dirname(result.report_path))
+    File.write(result.report_path, result.body)
+    result
+  end
+end

package/scripts/lib/installer_core.rb

@@ -296,6 +296,10 @@ 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",
+      "scripts/feedback-report" => "scripts/feedback-report",
+      "scripts/lib/feedback_report.rb" => "scripts/lib/feedback_report.rb",
     }
   end