@zalom/plastic 1.0.1 → 1.0.3

package/PLASTIC.md

@@ -113,9 +113,9 @@ entries stay append-only, newest at the bottom; the prefix only stamps each line
 which stage, and who.
 
 The blessed write path is the `insight-append` helper
-(`scripts/insight-append <intent_dir> <text> --stage S --author A`), which formats the prefix,
-validates it, and appends at the bottom. Hand-editing `## Insights` is an escape hatch; the
-helper is the default so the format cannot drift.
+(`scripts/insight-append <intent_dir> <text> --stage S --author A`), which ships with every
+install and update, formats the prefix, validates it, and appends at the bottom. Hand-editing
+`## Insights` is an escape hatch; the helper is the default so the format cannot drift.
 
 Background sessions and dispatched sub-agents do not write the insight themselves. They carry
 each nugget home in the completion report's `insights:` field, and the orchestrator (or any
@@ -191,6 +191,13 @@ adapter layer that maps Plastic's hooks and model aliases onto each supported ag
 (Claude, Codex, Hermes) is the cross-harness portability layer; see
 docs/reference/harness-adapters.md for the adapter contract.
 
+**Spawn preamble (intent 152).** `scripts/spawn-preamble` emits a live-state block purely from
+filesystem state: the active intent, stage, role/cycle-step, the honor instruction, and the
+report contract. When the intent's code worktree is resolvable and exists on disk, it also
+appends the worktree's absolute path plus a verbatim instruction to `cd` there directly, for
+harnesses whose `EnterWorktree` cannot discover a nested repo from a non-repo launch directory.
+Output is byte-identical when no worktree resolves.
+
 **Orchestrator advisory.** At auto-mode start, the orchestrator recommends once that the user
 run the main session on the best available thinking model (Fable, Opus, or whatever supersedes
 them). This is advisory only: it changes no behavior and blocks nothing if ignored, and it
@@ -343,7 +350,7 @@ ALL work flows through intents.
 3. On completion, capture observations in `## Insights`.
 4. When done, write `outcome.md` + `## Outcome` summary. Update INDEX.md.
 5. Researches are intents. No separate folder.
-6. Intents are created only via `plastic-creating-intent`. Never hand-author an intent file. The skill self-verifies the written intent with `scripts/validate-intent` before announcing or committing, so every intent is born complete.
+6. Intents are created only via `plastic-creating-intent`. Never hand-author an intent file. The skill self-verifies the written intent with `scripts/validate-intent` before announcing or committing, so every intent is born complete. `--intent` text is escaped for double quotes and backslashes before it lands in frontmatter, so free-form text is safe to pass as-is, and a reciprocal `chain:` append preserves the target intent's existing flow- or block-style entries.
 
 ## House Style (self-check)
 
@@ -363,6 +370,36 @@ cache) over re-reading them from disk, which only widens context. QMD is for OTH
 intents, not for re-reading what you just wrote. Pairs with `/clear` plus savepoint-resume
 hygiene after each intent. Advisory self-check, not hard-verifiable.
 
+## Tabular-First Reporting (intent 160)
+
+**Default.** Tabular layout is the default shape for three surfaces: What-stage discovery
+deposits, all research reports, and all agent reporting or presentation surfaces.
+
+**Calibration.** Tables are REQUIRED for any listing or discussion of intents, and for
+explaining complex data, comparisons, or multi-factor reasoning. This is NOT a blanket
+tables-everywhere rule: simple data stays prose, and tables must not be overused.
+
+**Bullets-limit.** Use bullets only when a table genuinely does not fit the content, and
+never more than 3-5 items.
+
+**Why tables.**
+
+| # | Reason |
+|---|--------|
+| 1 | Parallel structure makes comparison a row-vs-row scan, not a re-read. |
+| 2 | Coverage is provable: N items means N rows, an empty cell exposes a gap while a missing bullet hides it. |
+| 3 | Schema stated once in the headers, no repeated labels, higher density. |
+| 4 | A column reads vertically to show every value at once. |
+| 5 | Cells force terseness where bullets sprawl and nest. |
+| 6 | A ruling or decision column turns the report into the decision worksheet. |
+| 7 | Rows stay machine-readable for downstream tooling. |
+| 8 | Uniform granularity: every item answers the same questions. |
+| 9 | Line-scoped git diffs. |
+
+**Exception.** The EM-to-CTO human briefing (`skills/auto/references/human-report-contract.md`)
+keeps its deliberate prose shape (fixed State/Risk/Call, single item, nothing to tabulate) and
+is exempt from this rule.
+
 ## Retrieval Gate
 
 Advisory. Hard gates guard writes, locks, and structure, never reads or searches. Read,
@@ -407,7 +444,9 @@ Each gate guards one thing. All are hard except the retrieval gate:
   `>` redirect, a `ruby -e` or `python -c` write), so the same rules apply whether an edit goes
   through the Write tool or a shell. A trailing `# plastic-ok` comment is an auditable escape that
   lets a deliberate command through, and every use is logged to
-  `~/.plastic/.cache/gate-escapes.log`.
+  `~/.plastic/.cache/gate-escapes.log`. The code gate (Write and Edit) carries the identical
+  audited `# plastic-ok` escape, logged to the same file. The escape does not extend to
+  `NotebookEdit` or MCP structural edits: they are still gated, just without an escape hatch.
 - **retrieval-gate** is advisory only (see the Retrieval Gate section): it hints at QMD and never
   blocks a read or search.
 

package/agents/plastic-intent-discovery.md

@@ -24,6 +24,7 @@ for the Why stage to consume.
    the intent file, spec.md, or any lifecycle deliverable: the lock-owner-only
    write rule stays intact, and the Why-stage `plastic-brainstorming` agent is
    the one that reads your deposit and enriches `## Context`.
+   Shape the deposit tabular-first per `PLASTIC.md` (## Tabular-First Reporting, intent 160).
 
 ## Constraints
 - Read-only with respect to the intent: your single output is

package/package.json

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

package/scripts/dashboard.rb

@@ -466,7 +466,7 @@ def render_continue(records)
   out.concat(matrix(open, scope_tag: true))
   out << ""
   out << LEGEND
-  out << "run     plastic-dashboard project <slug>  ·  plastic-auto  (works the dispatchable queue)"
+  out << "ask    for the <slug> project board  ·  plastic-auto  (works the dispatchable queue)"
   out.join("\n") + "\n"
 end
 

package/scripts/doctor.rb

@@ -676,9 +676,9 @@ class Doctor
         message: "#{stalled.size} stalled completion#{stalled.size == 1 ? "" : "s"} " \
                  "(terminal in INDEX but the End tail did not finish)",
         details: stalled, fixable: true,
-        fix_hint: "Finish the End tail via stale-lock reclaim: `plastic-lock reclaim`, then complete the " \
-                  "tail (Worktree.release -> Lock.release -> purge -> QMD reindex last). This FINISHES a " \
-                  "completion; it is NOT a reactivation of a done intent."
+        fix_hint: "Finish the End tail via stale-lock reclaim: run /plastic-doctor reclaim the lock, " \
+                  "then complete the tail (Worktree.release -> Lock.release -> purge -> QMD reindex " \
+                  "last). This FINISHES a completion; it is NOT a reactivation of a done intent."
       )
     end
 

package/scripts/lib/bridge.rb

@@ -741,17 +741,18 @@ module Bridge
       data["lock"] = lock_cache(lock_data)
     when :held
       raise LockHeldError, "delivery lock for intent #{intent_id} is held by " \
-        "session #{lock_data && lock_data['owner_session']}; run /plastic-lock status"
+        "session #{lock_data && lock_data['owner_session']}; run /plastic-doctor " \
+        "check the lock status"
     when :stale
       raise LockHeldError, "delivery lock for intent #{intent_id} is stale " \
-        "(owner #{lock_data && lock_data['owner_session']}); run /plastic-lock " \
-        "reclaim to take it over with an audit"
+        "(owner #{lock_data && lock_data['owner_session']}); run /plastic-doctor " \
+        "reclaim the lock to take it over with an audit"
     when :excluded
       raise LockHeldError, "a #{lock_data && lock_data['type']} lock is active on " \
-        "intent #{intent_id}; run /plastic-lock status"
+        "intent #{intent_id}; run /plastic-doctor check the lock status"
     when :corrupt
       raise LockHeldError, "delivery.lock for intent #{intent_id} is unreadable; " \
-        "run /plastic-lock fix"
+        "run /plastic-doctor fix the lock"
     end
 
     # Provision the per-intent worktrees (mandatory code worktree for project
@@ -861,7 +862,7 @@ module Bridge
       end
       return { "status" => "stale", "owner" => lock["owner_session"],
                "actions" => actions, "session" => key,
-               "hint" => "run /plastic-lock reclaim to take over with an audit" }
+               "hint" => "run /plastic-doctor reclaim the lock to take over with an audit" }
     end
 
     if lock
@@ -1002,16 +1003,16 @@ module Bridge
                "#{lock['owner_session']}. Back off; if you are the owner's " \
                "subagent, the owner must run: plastic-lock delegate " \
                "--intent-dir #{target_dir} --session <your-session-id>. " \
-               "Inspect with /plastic-lock status"
+               "Inspect with /plastic-doctor check the lock status"
       end
       return solo_allow(id, "stale delivery lock") if solo
       return "intent #{id} has a stale delivery lock (owner " \
-             "#{lock['owner_session']}); run /plastic-lock reclaim to take " \
-             "it over, or /plastic-lock fix"
+             "#{lock['owner_session']}); run /plastic-doctor reclaim the lock to " \
+             "take it over, or /plastic-doctor fix the lock"
     end
     if Lock.corrupt?(target_dir)
       return solo_allow(id, "unreadable delivery.lock") if solo
-      return "delivery.lock for intent #{id} is unreadable; run /plastic-lock fix"
+      return "delivery.lock for intent #{id} is unreadable; run /plastic-doctor fix the lock"
     end
     return solo_allow(id, "no delivery lock") if solo
     "no delivery lock held for intent #{id}; run /plastic-intent-starting " \

package/scripts/lib/dashboard_banner.rb

@@ -20,7 +20,7 @@ module DashboardBanner
     return nil unless counts.is_a?(Hash)
     active = counts["active"].to_i
     future = counts["future"].to_i
-    line = "Plastic: #{active} active · #{future} next · run /plastic-dashboard to see the board"
+    line = "Plastic: #{active} active · #{future} next · say \"show the dashboard\" to see the board"
     nbt = next_big_thing_id(payload)
     line += " · next big thing: #{nbt}" if nbt
     line

package/scripts/lib/lock.rb

@@ -368,8 +368,8 @@ module Claim
     holder = data && data["owner_session"]
     since = data && data["acquired_at"]
     "artifact #{artifact} is claimed by #{holder} since #{since}; another writer holds " \
-      "it. Back off or run /plastic-lock status. If you are a distinct delegate, the " \
-      "owner must register you: plastic-lock delegate --intent-dir #{intent_dir} " \
-      "--session <your-session-id>"
+      "it. Back off or run /plastic-doctor check the lock status. If you are a distinct " \
+      "delegate, the owner must register you: plastic-lock delegate --intent-dir " \
+      "#{intent_dir} --session <your-session-id>"
   end
 end

package/skills/add-project-store/SKILL.md

@@ -6,6 +6,7 @@ description: >-
   when you need to provision a store, or when doctor reports a missing project
   store (project_store_dir). Thin wrapper around provision-project-store plus an
   optional qmd register step.
+user-invocable: false
 ---
 
 # Add a Project Store

package/skills/auto/SKILL.md

@@ -4,6 +4,7 @@ description: >-
   Autonomous intent delivery — agent takes over How and Exec. Use when user says
   "auto", "take it from here", "deliver this", or when brainstorming-grill-me concludes
   and user confirms autonomous execution. Requires an active intent in INDEX.md.
+user-invocable: true
 ---
 
 # Auto — Autonomous Intent Delivery

package/skills/auto/references/agent-report-contract.md

@@ -47,6 +47,9 @@ Every role report, whatever the stage, carries these fields:
 
 ## Per-role payload
 
+Multi-item payload fields (ordered actions, insights, checklist deltas) default to tables per
+`PLASTIC.md` (## Tabular-First Reporting, intent 160); single fields stay prose.
+
 Each role appends a payload that fulfils its place in the What, Why, How, Exec cycle (decision
 D2). The payload is what makes the report useful to the orchestrator beyond the envelope.
 

package/skills/brainstorming/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: plastic-brainstorming
 description: "Explore intent requirements and design before implementation. Produces spec.md in the active intent directory."
+user-invocable: true
 ---
 
 # Brainstorming Ideas Into Designs

package/skills/brainstorming-grill-me/SKILL.md

@@ -4,6 +4,7 @@ description: >-
   Deep brainstorming that interviews the user relentlessly about a plan or design until reaching shared understanding.
   Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".
   Pair with plastic-brainstorming for quick ideation and use grill-me for thorough interrogation. If superpowers:brainstorming is installed it complements this skill, but it is not required.
+user-invocable: true
 ---
 
 # Grill Me — Deep Brainstorming

package/skills/continuing/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: plastic-continuing
 description: Use when the user says "continue", "resume", or "pick up where we left off", or when starting a new session. Continues work with the latest project context: lands on the right dashboard, then presents choices. Boot (health check, core context, version, statusline) is owned by the SessionStart hook, not this skill. Does not drive work autonomously (that is plastic-auto).
+user-invocable: true
 ---
 
 # Continuing

package/skills/creating-intent/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: plastic-creating-intent
 description: Use when new work begins, the user expresses a new goal, says "new intent", or no active intent exists for the current task. Creates intents in the global store (~/.plastic/store/) or in a project's store (~/.plastic/projects/{slug}/store/) depending on context.
+user-invocable: true
 ---
 
 # Creating an Intent

package/skills/creating-project/SKILL.md

@@ -5,6 +5,7 @@ description: >-
   git init, AGENTS.md with founding intent decisions, plastic-install --local,
   tactical mirror, projects.yml registration, and framework scaffolding.
   Use when an implementation intent spawns a project, or manually by user.
+user-invocable: true
 ---
 
 # Creating a Project

package/skills/creating-skills/SKILL.md

@@ -9,6 +9,7 @@ description: >
   when an agent keeps missing a step or ignoring instructions, or when the user
   says "progressive disclosure", "write a skill", "thin router", "split into
   references", or "make this slim".
+user-invocable: true
 ---
 
 # Creating Skills

package/skills/creating-skills/references/skills.md

@@ -102,6 +102,7 @@ Use only the documented optionals below. Add nothing beyond them [A6].
 | `allowed-tools` | Space-separated tool list (experimental) |
 | `model` | Claude Code extension: pin the model for this skill |
 | `disable-model-invocation` | Claude Code extension: only the user may fire the skill |
+| `user-invocable` | Claude Code extension: set false to hide the skill from the user's / slash menu while leaving it agent-invocable; default true |
 | `context: fork` | Claude Code extension: run the body as a forked task |
 | `paths` | Claude Code extension: scope the skill to matching paths |
 

package/skills/dashboard/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: plastic-dashboard
 description: Use when the user wants an overview of intents, asks "where are we", "what's next", "what should I work on", "show the dashboard", or invokes /plastic-dashboard. Renders a deterministic Value×Effort work cockpit as Markdown across the global store and all projects, and emits a machine-readable queue that auto mode consumes.
+user-invocable: false
 ---
 
 # Dashboard — Plastic Work Cockpit

package/skills/doctor/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: plastic-doctor
 description: Use when diagnosing Plastic installation health, after updates, or when something seems broken. Runs checks and reports findings with fix options.
+user-invocable: true
 ---
 
 # Doctor: Plastic Health Check

package/skills/evaluating-skills/SKILL.md

@@ -8,6 +8,7 @@ description: >
   skill, checking if a description triggers correctly, or assessing
   whether a skill is still needed. Also use when the user says "evaluate",
   "test the skill", "run evals", "check conventions", or "write evals".
+user-invocable: true
 ---
 
 # Evaluating Skills

package/skills/executing-plan/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: plastic-executing-plan
 description: Use when you have a written implementation plan to execute. Default mode is subagent-driven (dispatches fresh subagent per task with two-stage review). Fallback mode is inline execution for environments without subagent support. If superpowers:subagent-driven-development or superpowers:executing-plans are available, delegates to them.
+user-invocable: true
 ---
 
 # Executing a Plan

package/skills/humanizer/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: plastic-humanizer
 description: Use to clean authored prose so it reads human and clutter-free. Removes AI tells and slop from a document, spec, outcome, README, report, or release note. Use when the user says "humanize", "de-slop", "remove the AI tells", or "clean up the wording". For documents, not for every chat reply, and not for code.
+user-invocable: true
 ---
 
 # Humanizer

package/skills/install/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: plastic-install
 description: Use when initializing Plastic globally (~/.plastic/) or locally in a project, or to re-install/repair a broken installation. Accepts channel flags (--alpha, --beta, --latest) to select release channel. First install defaults to --beta; reinstalls match the already-installed channel. Global install is recommended: it creates the global intent store as a git-backed repository. Local install creates .plastic/ in the current project for testing.
+user-invocable: true
 ---
 
 # Install Plastic

package/skills/intent-curator/SKILL.md

@@ -11,6 +11,7 @@ description: |
   user: "Organize the intents"
   assistant: "I'll use the intent-curator to review clusters, flag orphans, and suggest connections"
   <commentary>Periodic maintenance of the Zettelkasten structure.</commentary></example>
+user-invocable: false
 ---
 
 # Intent Curator

package/skills/intent-discovery/SKILL.md

@@ -6,6 +6,7 @@ description: >-
   resources/discovery--<slug>.md for the Why stage to consume. Use when an intent
   is activated (moved from Future to Active), after the lock is armed, under it,
   and before Why begins. Never writes the intent file itself.
+user-invocable: false
 ---
 
 # Intent Discovery — What-stage context deposit
@@ -33,6 +34,7 @@ lock. Dispatched as the `plastic-intent-discovery` background agent.
    the intent file, spec.md, or any lifecycle deliverable. The lock-owner-only
    write rule stays intact; the Why-stage `plastic-brainstorming` agent reads the
    deposit and enriches `## Context`.
+   Shape the deposit tabular-first per `PLASTIC.md` (## Tabular-First Reporting, intent 160).
 
 ## Stage coverage
 This is the What-stage agent in the one-agent-per-stage table (What:

package/skills/intent-starting/SKILL.md

@@ -5,6 +5,7 @@ description: >-
   guided ONCE, then resume at the latest delivered station and run the cycle to Done. Use on
   `continuing --intent {id}`, when a new intent is registered and the user asks to work it,
   or when the user picks an intent to work. Requires the intent in INDEX `## Active`.
+user-invocable: true
 ---
 
 # Intent Starting — board a session onto an intent

package/skills/linking-intents/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: plastic-linking-intents
 description: Use when creating connections between intents, the user says "link" or "connect", or when discovering that two intents are related. Manages sources, chain, and cross-reference links.
+user-invocable: false
 ---
 
 # Linking Intents

package/skills/lock/SKILL.md

@@ -1,6 +1,7 @@
 ---
-name: lock
+name: plastic-lock
 description: Inspect, repair, release, or reclaim an intent's delivery lock. Use when a lock-gate deny names /plastic-lock, when resuming interrupted work after a crash, reboot, or /tmp wipe, when a lock reads held or stale, or when the user says "fix the lock", "who holds the lock", or "reclaim the lock".
+user-invocable: false
 ---
 
 # Plastic Lock

package/skills/managing-index/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: plastic-managing-index
 description: Use after creating, completing, or abandoning intents, when the user says "index" or "organize", or when INDEX.md needs maintenance. Curates the INDEX.md structure note.
+user-invocable: false
 ---
 
 # Managing the Index

package/skills/releasing/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: plastic-releasing
 description: Use when merging a feature branch to main and tagging a release, bumping the version, or when the user says "release", "tag", or "ship it"
+user-invocable: true
 ---
 
 # Releasing

package/skills/research/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: plastic-research
 description: "Research a topic for the active intent. Agent decides shallow vs deep based on scope. Produces reports in the intent's resources/ directory."
+user-invocable: true
 ---
 
 # Research
@@ -81,6 +82,8 @@ Examples:
 
 ### Report Structure
 
+Default to tabular-first per `PLASTIC.md` (## Tabular-First Reporting, intent 160): tables for findings and comparisons, prose for simple summaries.
+
 ```markdown
 # {Type}: {Topic}
 

package/skills/roadmap/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: plastic-roadmap
 description: Use when the user wants to plan a delivery batch, order waves of intents, ship a batch of tickets in one go, track a named collection of intents toward a goal, or asks for a "roadmap". Creates and maintains a roadmap file, a delivery-side collection of intents (the counterpart to a release), separate from INDEX.md status tracking.
+user-invocable: true
 ---
 
 # Roadmap

package/skills/savepoint/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: plastic-savepoint
 description: Use when verifying or repairing an intent's savepoint ledger, when the user says "save" or "savepoint", or when a PreCompact hook fires. The ledger is written automatically by the gate hook at each lifecycle boundary; this skill only reads, verifies, and rebuilds it.
+user-invocable: false
 ---
 
 # Savepoint

package/skills/uninstall/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: plastic-uninstall
 description: Use when the user wants to remove Plastic from an agent. Runs the manifest-driven uninstaller (removes skills, hooks, statusline, and any legacy plugin layout), reports exactly what was removed and what was left behind, then gives verification steps. Optionally deletes the intent store.
+user-invocable: true
 ---
 
 # Uninstall Plastic

package/skills/update/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: plastic-update
 description: Use when updating Plastic. Runs the `update` verb, which reads the installed VERSION, derives its channel, queries npm dist-tags, and advances to the next version on that channel (or switches channel with a flag).
+user-invocable: true
 ---
 
 # Update Plastic

package/skills/versions/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: plastic-versions
 description: Use when the user wants to see their Plastic version history or roll back to a previously-installed version after a bad release. Manages the local, append-only versions.json ledger and steps between versions the user has actually run. For moving to a brand-new release, use plastic-update instead.
+user-invocable: true
 ---
 
 # Plastic Versions: local version time-machine

package/skills/writing-plans/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: plastic-writing-plans
 description: "Write implementation plans from a spec. Produces plan.md, checklist.md, and actions/ in the active intent directory."
+user-invocable: true
 ---
 
 # Writing Plans