@zalom/plastic 1.1.2 → 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

@@ -243,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
 

package/package.json

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

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/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

@@ -298,6 +298,8 @@ class InstallerCore
       "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
 

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