@zalom/plastic 1.0.0-beta.34 → 1.0.0-beta.36

package/PLASTIC-reference.md

@@ -0,0 +1,133 @@
+# Plastic - Reference
+
+> **This file is maintained by Plastic.** It will be overwritten when the
+> plugin is updated. It holds reference material: read it on demand, it is
+> not injected at session start.
+
+### Structural maintenance and revisions.md
+
+When a delivered intent accumulates structural junk (an unsanctioned section, a stray file, a
+frontmatter edge to an intent that no longer exists), the intent-curator relocates it into
+`revisions.md` instead of reopening the work. Each entry is a versioned, dated header
+(`## Revision vN - YYYY-MM-DD-HH:MM`) plus `Why` (one sentence naming the broken rule, ending
+with `[rule: <tag>]`), `Prior location`, and either `Content held` (the verbatim removed
+content) or, for a frontmatter edit, a one-line `Change` (before and after). A stray file has
+its full content embedded and the original is deleted.
+
+Violation tags (starter set, free-text tags allowed):
+- `unsanctioned-section`: a top-level section the sanctioned-section rule now rejects
+- `phantom-section`: a section referenced but not present or not sanctioned
+- `stray-file`: a file that does not belong in the intent directory
+- `dangling-ref`: a link or reference to something that no longer exists
+- `broken-chain`: a chain frontmatter edge to an intent that no longer exists
+- `broken-source`: a sources frontmatter edge to an intent that no longer exists
+- `misplaced-content`: content that belongs in a different artifact or section
+
+## Two Processes
+
+| Process | Scope | Type | Actor |
+|---|---|---|---|
+| **Build → Observe → Repeat** | The system | Continuous loop | Coordinator |
+| **What → Why → How → Exec** | One intent | Finite lifecycle | Agent |
+
+B→O→R is the Coordinator's heartbeat. W→W→H→E is what happens inside each intent.
+The connection: an intent's `## Insights` feeds the Coordinator's Observe phase.
+
+## Defaults-First
+
+Plastic stands on its own. Skills and agents use Plastic's own defaults; an
+external skill (for example `superpowers:*`) is opt-in, never load-bearing.
+
+- **Default to Plastic, delegate by exception.** Name the Plastic-native path as
+  the default. Delegate to an external skill only when (a) it is available in the
+  harness, or (b) the user explicitly asks for it. A user without that plugin must
+  still get the core behavior.
+- **Phrase external skills as enhancements.** Write "use Plastic's native X by
+  default; if `superpowers:<skill>` is available, or the user prefers it, delegate
+  to it" never "delegate to `superpowers:<skill>`" as the only path.
+- **Optional dependencies detect then degrade.** `qmd` is the reference shape:
+  `scripts/lib/qmd_sync.rb` detects the binary first and every verb no-ops cleanly
+  when it is absent (see `scripts/qmd-sync`). Optional CLIs and MCP servers follow
+  the same detect-then-skip pattern, so a missing tool never crashes a session.
+- **Legitimate hard dependencies are exempt.** Ruby, Node, git, and POSIX tools are
+  the cost of running Plastic, not silent coupling. The principle targets accidental
+  dependence on external skills doing work Plastic should do itself.
+
+## Roadmaps
+
+Roadmaps exist for planned parallel delivery of intents in a coherent and organized way. A roadmap
+is a named, ordered, delivery-side collection of intents: the delivery-side counterpart to a
+release (completion-side, tracked in `CHANGELOG.md`). Use `plastic-roadmap` to create, order,
+close, and consume one.
+
+File location: `roadmaps/{slug}.md`, a sibling of `INDEX.md`, wherever `INDEX.md` lives, never
+inside `store/` (store holds intent directories, not project artifacts). For a project that is its
+root, `~/.plastic/projects/{slug}/roadmaps/`, beside `project.yml`; for the global tier it is
+`~/.plastic/roadmaps/`, beside `~/.plastic/INDEX.md`. `roadmaps/` lists only live (open or
+in-flight) roadmaps: once a roadmap's goal is reached, it moves to `roadmaps/archived/{slug}.md`,
+a sibling subdirectory scaffolded once with a `.gitkeep`.
+
+A roadmap file has four sections, in order: a title/meta header, `## Goal`, `## Waves`, and an
+append-only dated `## Log`. `## Goal` is a checkable prose condition read by a human or agent, not
+an executable checker. `## Waves` holds ordered waves; entries inside a wave are parallel-safe,
+waves run sequentially, top to bottom.
+
+Each wave entry carries a status token (`queued`/`delivering`/`delivered`/`abandoned`/`blocked`)
+that mirrors that intent's status in `INDEX.md`. `INDEX.md` is the single writer of intent status;
+on any conflict INDEX wins and the roadmap entry is corrected to match.
+
+**Human-comprehension surface.** A roadmap is also written to be read cold. Wave entries render as
+checkboxes (checked once delivered, unchecked otherwise) next to the status token, and each `## Log`
+line is one plain-language sentence, starting `YYYY-MM-DD HH:MM UTC`, written the way an
+engineering manager would brief a non-expert executive: what shipped and why it matters, no jargon
+or codenames, ending with a link
+to that intent's `outcome.md`. The log points at the detail instead of repeating it, so a person
+opening the file with no other context can tell what shipped, what is running now, and what is
+next in under a minute.
+
+**Relationship to loop engineering (intent 69).** A roadmap is the planning half of the work; the
+loop is its runtime. Waves lay out the parallelism plan: what can run together, and in what order.
+Loop engineering (intent 69, not yet delivered) is expected to consume that plan and supply the
+running parts, the heartbeat, how many dispatches run at once, checking the goal, and resuming
+after a stop. This section only states the relationship and points to intent 69 as the future
+consumer; it does not change intent 69's own design.
+
+## Context-economy measurement buckets (84a)
+
+Intent 84 defines three buckets for sibling 84a to audit against; 84 does not run the audit.
+
+- (a) gate-hook prose tokens: the per-transition narration emitted by the gate hook.
+- (b) main-loop store-read tokens: tokens the main agent spends reading or grepping the store
+  in the transcript.
+- (c) authored-section sizes: sizes of authored artifacts (INDEX entries and the like).
+
+## Deprecation Process
+
+Deprecations live in `deprecations.yml` and are shown at SessionStart. While Plastic is
+pre-1.0, a satisfied deprecation (its migration is already done on installed machines) may be
+removed immediately instead of waiting for its declared `removal` version. From `1.0.0` on,
+the steady-state grace rule applies (removal at least two minors ahead). For the full process,
+severity levels, and the pre-1.0 exception, see the `plastic-releasing` skill.
+
+## Skills Reference
+
+Detailed conventions live inside the skills that use them, not in this file.
+
+| Topic | Skill | References in skill |
+|-------|-------|-------------------|
+| Creating intents, lifecycle | `plastic-creating-intent` | lifecycle, wikilinks |
+| Brainstorming, spec writing | `plastic-brainstorming` | — |
+| Planning, actions | `plastic-writing-plans` | — |
+| Execution, delivery | `plastic-executing-plan` | — |
+| Autonomous delivery | `plastic-auto` | agent architecture |
+| Save/restore state | `plastic-savepoint`, `plastic-continuing` | context management |
+| Knowledge graph, linking | `plastic-linking-intents` | zettelkasten, wikilinks |
+| Projects, hubs | `plastic-creating-project` | hubs, project stores |
+| Provision a project store | `plastic-add-project-store` | project stores |
+| Index maintenance | `plastic-managing-index` | — |
+| 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 |
+| Authoring skills, agents, hooks | `plastic-creating-skills` | progressive disclosure, agentskills.io spec |
+| Evaluating skills, evals | `plastic-evaluating-skills` | eval methodology, convention checks |
+| Create, order, and consume a roadmap of intents | `plastic-roadmap` | file format, operations |
+

package/PLASTIC.md

@@ -1,31 +1,33 @@
-# Plastic — Conventions
+# Plastic: Conventions
 
 > **This file is maintained by Plastic.** It will be overwritten when the
-> plugin is updated. Do not modify — your changes will be lost.
+> plugin is updated. Do not modify it: your changes will be lost.
 > For project-specific rules, use `AGENTS.md` instead.
 
+See `PLASTIC-reference.md` for reference material: read it on demand, it is not injected at session start.
+
 ## What is an Intent
 
 A directory in the store containing `{ID}--{slug}.md` and optional supporting files.
-It represents a desire — something a human or agent wants to accomplish, explore, or understand.
+It represents a desire: something a human or agent wants to accomplish, explore, or understand.
 
 ```
 store/
   ID--three-to-five-words/
-    {ID}--{slug}.md       # required — the intent itself
-    spec.md               # optional — specification (Why deliverable)
-    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
-    resources/            # optional — research, references, screenshots, diagrams
-    savepoint.md          # optional — deterministic cycle-step ledger (auto-written)
+    {ID}--{slug}.md       # required - the intent itself
+    spec.md               # optional - specification (Why deliverable)
+    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
+    resources/            # optional - research, references, screenshots, diagrams
+    savepoint.md          # optional - deterministic cycle-step ledger (auto-written)
     revisions.md          # optional - append-only structural-maintenance audit trail
 ```
 
 Lifecycle files (`spec.md`, `plan.md`, `checklist.md`, `outcome.md`) have defined
-roles. Supporting artifacts that aren't lifecycle deliverables — research reports,
-reference docs, external API snapshots, screenshots, diagrams — go in `resources/`.
+roles. Supporting artifacts that aren't lifecycle deliverables (research reports,
+reference docs, external API snapshots, screenshots, diagrams) go in `resources/`.
 Name files inside as `{type}--{description}.md` (e.g., `deep-research--gsd-core.md`).
 
 `revisions.md` is an optional, append-only structural-maintenance audit trail. It is not a
@@ -36,25 +38,6 @@ inside `revisions.md` (newest entry at the bottom, one entry per relocated item)
 lost and the delivered meaning is never altered. Changing what an intent delivered is a new intent,
 not a revision.
 
-### Structural maintenance and revisions.md
-
-When a delivered intent accumulates structural junk (an unsanctioned section, a stray file, a
-frontmatter edge to an intent that no longer exists), the intent-curator relocates it into
-`revisions.md` instead of reopening the work. Each entry is a versioned, dated header
-(`## Revision vN - YYYY-MM-DD-HH:MM`) plus `Why` (one sentence naming the broken rule, ending
-with `[rule: <tag>]`), `Prior location`, and either `Content held` (the verbatim removed
-content) or, for a frontmatter edit, a one-line `Change` (before and after). A stray file has
-its full content embedded and the original is deleted.
-
-Violation tags (starter set, free-text tags allowed):
-- `unsanctioned-section`: a top-level section the sanctioned-section rule now rejects
-- `phantom-section`: a section referenced but not present or not sanctioned
-- `stray-file`: a file that does not belong in the intent directory
-- `dangling-ref`: a link or reference to something that no longer exists
-- `broken-chain`: a chain frontmatter edge to an intent that no longer exists
-- `broken-source`: a sources frontmatter edge to an intent that no longer exists
-- `misplaced-content`: content that belongs in a different artifact or section
-
 ## Frontmatter
 
 Identity and knowledge graph only. Nothing operational.
@@ -106,16 +89,6 @@ tags: [plastic, architecture]
 - IDs use Luhmann's alternating convention: `1` → `1a` → `1a1` → `1a1a`
 - Multiple branches increment: `1a`, `1b`, `1c`
 
-## Two Processes
-
-| Process | Scope | Type | Actor |
-|---|---|---|---|
-| **Build → Observe → Repeat** | The system | Continuous loop | Coordinator |
-| **What → Why → How → Exec** | One intent | Finite lifecycle | Agent |
-
-B→O→R is the Coordinator's heartbeat. W→W→H→E is what happens inside each intent.
-The connection: an intent's `## Insights` feeds the Coordinator's Observe phase.
-
 ## Lifecycle Stages
 
 | Stage | Section | Deliverable | Detail |
@@ -213,14 +186,16 @@ run the main session on the best available thinking model (Fable, Opus, or whate
 them). This is advisory only: it changes no behavior and blocks nothing if ignored, and it
 concerns the human's main session, never a dispatched subagent.
 
-**`plastic-intent-discovery`.** The What-stage agent. It fires at intent activation, before the
-delivery lock is armed and Why begins: it reads the intent's `chain`/`sources` frontmatter,
-runs QMD-first discovery over completed predecessor work and related parked or future intents,
-and deposits findings to `resources/discovery--<slug>.md` in the intent directory ONLY. It
-never writes the intent file, `spec.md`, or any other lifecycle deliverable; the Why-stage
-`plastic-brainstorming` agent reads its deposit and enriches `## Context`.
+**`plastic-intent-discovery`.** The What-stage agent. It fires at intent activation, after the
+delivery lock is armed and before Why begins, running under that lock as the owner session (it
+does not acquire the lock itself and is not blocked by it): it reads the intent's
+`chain`/`sources` frontmatter, runs QMD-first discovery over completed predecessor work and
+related parked or future intents, and deposits findings to `resources/discovery--<slug>.md` in
+the intent directory ONLY. It never writes the intent file, `spec.md`, or any other lifecycle
+deliverable; the Why-stage `plastic-brainstorming` agent reads its deposit and enriches
+`## Context`.
 
-`savepoint.md` — a deterministic, append-only ledger of cycle-step milestones (one line per
+`savepoint.md`: a deterministic, append-only ledger of cycle-step milestones (one line per
 lifecycle boundary, newest at the bottom), written automatically by the gate hook. It is
 sugar on top of the conventions, not a source of truth: state is always derivable from
 files-on-disk, and the ledger is rebuildable. It exists so a resuming agent reads the cycle's
@@ -232,7 +207,7 @@ succession at a glance (last line = where we are).
   `docs/specs/`, `researches/`, or similar. All meta-artifacts go in
   `~/.plastic/store/ID--slug/` or the project store equivalent.
 - **Code goes in the project. Everything else goes in the intent.**
-  Plans, specs, checklists, savepoints — all in the intent directory.
+  Plans, specs, checklists, savepoints: all in the intent directory.
 - **The global store is never pushed.** `~/.plastic/` is git-tracked locally
   but contains sensitive data. Never push to a remote.
 - **Agent-created repos are private by default.** Use `gh repo create --private`.
@@ -245,26 +220,6 @@ succession at a glance (last line = where we are).
   brainstorming, writing-plans, etc., Plastic's directory rules override
   their default output paths.
 
-## Defaults-First
-
-Plastic stands on its own. Skills and agents use Plastic's own defaults; an
-external skill (for example `superpowers:*`) is opt-in, never load-bearing.
-
-- **Default to Plastic, delegate by exception.** Name the Plastic-native path as
-  the default. Delegate to an external skill only when (a) it is available in the
-  harness, or (b) the user explicitly asks for it. A user without that plugin must
-  still get the core behavior.
-- **Phrase external skills as enhancements.** Write "use Plastic's native X by
-  default; if `superpowers:<skill>` is available, or the user prefers it, delegate
-  to it" never "delegate to `superpowers:<skill>`" as the only path.
-- **Optional dependencies detect then degrade.** `qmd` is the reference shape:
-  `scripts/lib/qmd_sync.rb` detects the binary first and every verb no-ops cleanly
-  when it is absent (see `scripts/qmd-sync`). Optional CLIs and MCP servers follow
-  the same detect-then-skip pattern, so a missing tool never crashes a session.
-- **Legitimate hard dependencies are exempt.** Ruby, Node, git, and POSIX tools are
-  the cost of running Plastic, not silent coupling. The principle targets accidental
-  dependence on external skills doing work Plastic should do itself.
-
 ## State System
 
 ```
@@ -298,10 +253,10 @@ Format: `ID--three-to-five-words` (all stores).
 - Intent file matches directory: `1a1--slug/1a1--slug.md`
 - Next ID: `"${CLAUDE_PLUGIN_ROOT}/scripts/folgezettel-id" <parent_id> <store_path>`
 
-**Branch vs root — the semantic decision.** The numbering is mechanics; choosing
+**Branch vs root: the semantic decision.** The numbering is mechanics; choosing
 *whether* to branch is meaning:
 
-- **Branch (`14a`, `14b`)** — a sub-task, refinement, or direct continuation of the
+- **Branch (`14a`, `14b`):** a sub-task, refinement, or direct continuation of the
   parent. It cannot stand on its own; it only makes sense as part of the parent's work.
 - **Root (`15`, `16`)**: an independent thought, even if inspired by another intent.
   Reserve `sources` for true created-from provenance (intents this was built out of). An
@@ -322,45 +277,6 @@ One-line entry convention. Each index entry is ONE line: `- [<id> <terse title>]
 The title is the title, not a summary: aim for about 80 characters, no multi-sentence
 descriptions. This is a self-check, not a gate.
 
-## Roadmaps
-
-Roadmaps exist for planned parallel delivery of intents in a coherent and organized way. A roadmap
-is a named, ordered, delivery-side collection of intents: the delivery-side counterpart to a
-release (completion-side, tracked in `CHANGELOG.md`). Use `plastic-roadmap` to create, order,
-close, and consume one.
-
-File location: `roadmaps/{slug}.md`, a sibling of `INDEX.md`, wherever `INDEX.md` lives, never
-inside `store/` (store holds intent directories, not project artifacts). For a project that is its
-root, `~/.plastic/projects/{slug}/roadmaps/`, beside `project.yml`; for the global tier it is
-`~/.plastic/roadmaps/`, beside `~/.plastic/INDEX.md`. `roadmaps/` lists only live (open or
-in-flight) roadmaps: once a roadmap's goal is reached, it moves to `roadmaps/archived/{slug}.md`,
-a sibling subdirectory scaffolded once with a `.gitkeep`.
-
-A roadmap file has four sections, in order: a title/meta header, `## Goal`, `## Waves`, and an
-append-only dated `## Log`. `## Goal` is a checkable prose condition read by a human or agent, not
-an executable checker. `## Waves` holds ordered waves; entries inside a wave are parallel-safe,
-waves run sequentially, top to bottom.
-
-Each wave entry carries a status token (`queued`/`delivering`/`delivered`/`abandoned`/`blocked`)
-that mirrors that intent's status in `INDEX.md`. `INDEX.md` is the single writer of intent status;
-on any conflict INDEX wins and the roadmap entry is corrected to match.
-
-**Human-comprehension surface.** A roadmap is also written to be read cold. Wave entries render as
-checkboxes (checked once delivered, unchecked otherwise) next to the status token, and each `## Log`
-line is one plain-language sentence, starting `YYYY-MM-DD HH:MM UTC`, written the way an
-engineering manager would brief a non-expert executive: what shipped and why it matters, no jargon
-or codenames, ending with a link
-to that intent's `outcome.md`. The log points at the detail instead of repeating it, so a person
-opening the file with no other context can tell what shipped, what is running now, and what is
-next in under a minute.
-
-**Relationship to loop engineering (intent 69).** A roadmap is the planning half of the work; the
-loop is its runtime. Waves lay out the parallelism plan: what can run together, and in what order.
-Loop engineering (intent 69, not yet delivered) is expected to consume that plan and supply the
-running parts, the heartbeat, how many dispatches run at once, checking the goal, and resuming
-after a stop. This section only states the relationship and points to intent 69 as the future
-consumer; it does not change intent 69's own design.
-
 ## Rules for Skills
 
 ALL work flows through intents.
@@ -402,25 +318,16 @@ one recommendation line per present tool. The legacy trailing `# qmd-ok` token i
 accepted on Bash commands and simply silences the hint. Scope stays the agent's own tool
 calls; Ruby `File.read` inside a script is invisible to the hook by design.
 
-## Context-economy measurement buckets (84a)
-
-Intent 84 defines three buckets for sibling 84a to audit against; 84 does not run the audit.
-
-- (a) gate-hook prose tokens: the per-transition narration emitted by the gate hook.
-- (b) main-loop store-read tokens: tokens the main agent spends reading or grepping the store
-  in the transcript.
-- (c) authored-section sizes: sizes of authored artifacts (INDEX entries and the like).
-
 ## Transition Gates
 
 | Transition | Trigger | Gate |
 |---|---|---|
-| What → Why | `spec.md` written | — |
+| 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 |
 | Exec → Done | `outcome.md` written | All checklist items checked |
 
-Hard blocking — hooks exit code 2 on gate failure.
+Hard blocking: hooks exit code 2 on gate failure.
 
 ## Delivery Isolation and the Single-Owner Lock
 
@@ -545,32 +452,3 @@ liveness surface, the lock-issue message, orchestrator auto-repair, and the fail
 behavior itself. Intent 112 owns the maintenance lock and the immutability gate (it inherits
 fail-open from 111). Intent 4a1b1 owns deep agent stuck-detection and is not superseded.
 
-## Deprecation Process
-
-Deprecations live in `deprecations.yml` and are shown at SessionStart. While Plastic is
-pre-1.0, a satisfied deprecation (its migration is already done on installed machines) may be
-removed immediately instead of waiting for its declared `removal` version. From `1.0.0` on,
-the steady-state grace rule applies (removal at least two minors ahead). For the full process,
-severity levels, and the pre-1.0 exception, see the `plastic-releasing` skill.
-
-## Skills Reference
-
-Detailed conventions live inside the skills that use them, not in this file.
-
-| Topic | Skill | References in skill |
-|-------|-------|-------------------|
-| Creating intents, lifecycle | `plastic-creating-intent` | lifecycle, wikilinks |
-| Brainstorming, spec writing | `plastic-brainstorming` | — |
-| Planning, actions | `plastic-writing-plans` | — |
-| Execution, delivery | `plastic-executing-plan` | — |
-| Autonomous delivery | `plastic-auto` | agent architecture |
-| Save/restore state | `plastic-savepoint`, `plastic-continuing` | context management |
-| Knowledge graph, linking | `plastic-linking-intents` | zettelkasten, wikilinks |
-| Projects, hubs | `plastic-creating-project` | hubs, project stores |
-| Provision a project store | `plastic-add-project-store` | project stores |
-| Index maintenance | `plastic-managing-index` | — |
-| 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 |
-| Authoring skills, agents, hooks | `plastic-creating-skills` | progressive disclosure, agentskills.io spec |
-| Evaluating skills, evals | `plastic-evaluating-skills` | eval methodology, convention checks |
-| Create, order, and consume a roadmap of intents | `plastic-roadmap` | file format, operations |

package/agents/plastic-brainstorming.md

@@ -1,12 +1,8 @@
 ---
 name: plastic-brainstorming
 description: |
-  Use this agent for the Why-stage exploration of an active intent in auto mode:
-  it enriches context and records decisions before a spec is written. Examples:
-  <example>Context: An intent has a What but a thin Why.
-  user: "Explore the requirements for the active intent"
-  assistant: "I'll use the brainstorming agent to enrich Context and record Decisions"
-  <commentary>Why-stage exploration runs before the spec-specialist.</commentary></example>
+  Use for the Why-stage exploration of an active intent in auto mode: enrich the
+  intent's Context and record its Decisions before the spec is written.
 model: opus
 ---
 

package/agents/plastic-enforcer.md

@@ -1,12 +1,8 @@
 ---
 name: plastic-enforcer
 description: |
-  Use this agent as the auto-mode orchestrator: it spins up the team, sequences the
-  specialists, owns every gate, and runs the final review. Examples:
-  <example>Context: User triggers auto on an active intent.
-  user: "auto"
-  assistant: "I'll use the plastic-enforcer to orchestrate the team through the cycle"
-  <commentary>The enforcer IS the orchestrator and gates each stage transition.</commentary></example>
+  Use as the auto-mode orchestrator: it spins up the team, sequences the
+  specialists, owns every gate, and runs the final review.
 model: opus
 ---
 
@@ -63,6 +59,15 @@ ceremony, never these guarantees.
 4. Dispatch and review by default through Plastic's native engine, `plastic-executing-plan` (implementer plus two-stage review, no external plugin). If `superpowers:subagent-driven-development` and `superpowers:dispatching-parallel-agents` are available, or the user asks for them, delegate to them as an enhancement
 5. At the final gate, dispatch an independent reviewer subagent, then complete the intent
 
+## Human-facing stage reporting
+
+At each gate, the orchestrator briefs the human in EM-to-CTO voice: impact first, the one risk
+that matters, then the decision left to them. The shape and per-stage content live in
+`skills/auto/references/human-report-contract.md`; follow it rather than improvising a report.
+This is separate from the intent 74 report contract (`skills/auto/references/agent-report-contract.md`),
+which is the internal, structured handoff a dispatched specialist sends back to the orchestrator.
+The orchestrator consumes that internal report to write the human briefing; the two never merge.
+
 ## Constraints
 
 - Enforce gates manually; do not rely on hooks, because the session id may be unset in headless or background runs

package/agents/plastic-executor.md

@@ -1,12 +1,8 @@
 ---
 name: plastic-executor
 description: |
-  Use this agent for the Exec stage in auto mode: it implements the actions, checks
-  off the checklist, and drives the test suite green. Examples:
-  <example>Context: plan.md and checklist.md exist for the active intent.
-  user: "Execute the plan for the active intent"
-  assistant: "I'll use the executor to implement each action and run the suite green"
-  <commentary>Exec turns the plan into code, one action at a time.</commentary></example>
+  Use for the Exec stage in auto mode: implement the actions, check off the
+  checklist, and drive the test suite green.
 model: sonnet
 ---
 

package/agents/plastic-future-intent-researcher.md

@@ -1,13 +1,8 @@
 ---
 name: plastic-future-intent-researcher
 description: |
-  Use this agent to research future intents autonomously. Picks up parked
-  intents from INDEX.md, investigates them via web search and codebase analysis,
-  and writes findings into the intent. Examples:
-  <example>Context: There are future intents parked in the index.
-  user: "Research my future intents"
-  assistant: "I'll use the future-intent-researcher to pick up a parked intent and investigate it"
-  <commentary>Agent autonomously researches a future intent and writes findings.</commentary></example>
+  Use to research a parked future intent autonomously via web search and codebase
+  analysis, writing the findings into the intent.
 model: sonnet
 ---
 

package/agents/plastic-intent-curator.md

@@ -1,16 +1,8 @@
 ---
 name: plastic-intent-curator
 description: |
-  Use this agent when completing or reviewing intents, reorganizing the index,
-  or when the intent store needs maintenance. Examples:
-  <example>Context: User has finished implementing a feature.
-  user: "This intent is done, clean up the index"
-  assistant: "I'll use the intent-curator agent to update the intent status and reorganize INDEX.md"
-  <commentary>Intent lifecycle change triggers curator for index maintenance.</commentary></example>
-  <example>Context: The intent store has grown and clusters need review.
-  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>
+  Use when completing or reviewing intents, reorganizing INDEX.md, or maintaining
+  the intent store.
 model: sonnet
 ---
 

package/agents/plastic-intent-discovery.md

@@ -1,19 +1,15 @@
 ---
 name: plastic-intent-discovery
 description: |
-  Use this agent for the What-stage context deposit when an intent is
-  activated: it primes Why with fresh QMD-sourced context before the spec is
-  written, and never writes the intent file itself. Examples:
-  <example>Context: An intent is being moved from Future to Active.
-  user: "Board this intent and gather what we already know"
-  assistant: "I'll use the intent-discovery agent to run QMD discovery and deposit findings to resources/"
-  <commentary>What-stage discovery runs at activation, before the lock and Why.</commentary></example>
+  Use for the What-stage context deposit when an intent is activated: run QMD
+  discovery and write findings to resources/, never the intent file itself.
 model: sonnet
 ---
 
 You are the Plastic Intent Discovery agent. You own the What stage: at intent
-activation, before the lock is armed and Why begins, you gather the context
-that already exists and deposit it for the Why stage to consume.
+activation, after the lock is armed and before Why begins, under the lock as
+the owner session, you gather the context that already exists and deposit it
+for the Why stage to consume.
 
 ## Responsibilities
 1. **Read the intent's links.** Load the activating intent file's `chain` and
@@ -32,6 +28,8 @@ that already exists and deposit it for the Why stage to consume.
 ## Constraints
 - Read-only with respect to the intent: your single output is
   `resources/discovery--<slug>.md`.
-- Never take the delivery lock; you run before it is armed.
+- You do not ACQUIRE the delivery lock; you run under the lock the
+  orchestrator armed (owner session, inherited session id) and are not
+  blocked by it.
 - End with a structured completion report per the spawn preamble's report
   contract.

package/agents/plastic-planner.md

@@ -1,12 +1,8 @@
 ---
 name: plastic-planner
 description: |
-  Use this agent for the How stage in auto mode: it turns a spec.md into a plan,
-  self-contained action files, and a checklist. Examples:
-  <example>Context: spec.md exists and the intent is ready to plan.
-  user: "Plan the work for the active intent"
-  assistant: "I'll use the planner to write plan.md, actions/, and checklist.md"
-  <commentary>The plan and checklist unlock the code gate for Exec.</commentary></example>
+  Use for the How stage in auto mode: turn spec.md into plan.md, self-contained
+  action files, and checklist.md.
 model: opus
 ---
 

package/agents/plastic-spec-specialist.md

@@ -1,12 +1,8 @@
 ---
 name: plastic-spec-specialist
 description: |
-  Use this agent at the Why-to-How boundary in auto mode: it consolidates an
-  enriched Why into a spec.md from the spec template. Examples:
-  <example>Context: Why exploration is complete and decisions are recorded.
-  user: "Write the spec for the active intent"
-  assistant: "I'll use the spec-specialist to produce spec.md from the template"
-  <commentary>The spec is the deliverable that gates the move into How.</commentary></example>
+  Use at the Why-to-How boundary in auto mode: consolidate the enriched Why into
+  spec.md from the spec template.
 model: sonnet
 ---
 

package/bin/plastic.js

@@ -50,8 +50,12 @@ try {
   })
 } catch (err) {
   if (err.status) process.exit(err.status)
-  console.error('Error: Ruby is required to run Plastic.')
-  console.error('  macOS: Ruby is pre-installed')
-  console.error('  Linux: sudo apt install ruby / dnf install ruby')
+  // Ruby cannot run to print its own message when it is missing, so this
+  // mirrors scripts/lib/preflight.rb's FATAL block word for word.
+  console.error('Plastic needs Ruby 3.0.0 or newer to run its scripts (found not found).')
+  console.error('Install a pinned Ruby with mise:')
+  console.error('  curl https://mise.run | sh        # only if mise is not installed yet')
+  console.error('  mise use --global ruby@3.3')
+  console.error('Then re-run the Plastic installer.')
   process.exit(1)
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zalom/plastic",
-  "version": "1.0.0-beta.34",
+  "version": "1.0.0-beta.36",
   "description": "Intent-driven idea development system for AI coding agents",
   "type": "module",
   "bin": {
@@ -38,6 +38,7 @@
     "agents/",
     "templates/",
     "PLASTIC.md",
+    "PLASTIC-reference.md",
     "deprecations.yml"
   ]
 }