@zalom/plastic 2.0.0-alpha.26 → 2.0.0-alpha.28

package/skills/dashboard/SKILL.md

@@ -1,180 +0,0 @@
----
-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 the intent store(s) as Markdown prose, the global board as a narrative of work done, each project board as a short summary plus its most-valuable next work, and emits a machine-readable queue that auto mode consumes.
-user-invocable: false
----
-
-# Dashboard — Plastic Work Cockpit
-
-A deterministic overview of the intent store(s). It answers three questions at a glance:
-**where we are** (recently worked; `Graph ID | Intent | Stage | Progress | Lead`),
-**where we go next** (the most-valuable next work; `Rank | Graph ID | Intent | Reason`), and
-**how to conduct it** (a disposition per intent). The human-facing surface is **Markdown**,
-because the user's UI renders Markdown natively but collapses raw tool-call stdout.
-
-The script does all the data work. The agent fills a Markdown template from the script's
-payload with near-zero reasoning and **presents the filled board in its reply**. Same store
-state → byte-identical payload, regardless of model. Do NOT hand-summarize intents.
-
-## When to Use
-
-- User invokes `/plastic-dashboard`
-- User asks "where are we", "what's next", "what should I work on", "show me the intents"
-- `plastic-intent-continuing` lands on the board on a bare resume
-- `plastic-auto` reads `--json` to choose the next dispatchable intent
-
-## The screen surface (intent 331d/331f)
-
-`dashboard.rb project <slug> --screen` (or `continue --screen` for the global board) is the
-default surface on every invocation: print it as the first characters of the reply, nothing
-before it, no fence, or the hook cannot paint it. It carries a title, six fields (Active, In
-delivery, Delivered, Roadmap, Sessions, Changed), then the Where-we-are and Where-we-go-next
-tables, its own grammar and painted form standing in for the filled Markdown template below.
-`plastic-intent-continuing`'s project route prints it this way. The Markdown board (Step 1-4
-below) stays available as the deeper prose surface a reader can ask for.
-
-## Procedure (the Markdown board — default human surface)
-
-### Step 1 — Get the data payload
-
-```bash
-ruby ~/.plastic/scripts/dashboard.rb [continue|project <slug>] --data
-```
-
-- `continue` (default) → the **global** board payload (`mode: "global"`).
-- `project <slug>` → that **project** board payload (`mode: "project"`).
-
-The payload is read-only JSON. Global-board fields: `date`, `store_health`, `summary`,
-`next_work`, `next_total`, `next_shown`, `counts`, `projects`, `project_totals`, `footer`.
-Project-board fields: `slug`, `store_health`, `description`, `summary`, `counts`, `active`,
-`active_total`, `active_shown`, `next_work`, `next_total`, `next_shown`, `footer`. `summary`
-and `footer` are finished prose strings (2-3 sentences and one line respectively), built in
-`dashboard.rb` and substituted verbatim, exactly like `{{date}}`/`{{description}}` already
-are - never re-worded or re-derived by the skill. Each list carries cell-ready fields for
-its table: `next_work` rows are
-`{id, intent, scope, lifecycle, value, disposition, flags, what, flags_label, line}`;
-`active` rows carry
-`{id, intent, created, bullet, scope, what, stage, worker, activity, line}`. The `what`,
-`scope`, `worker`, `activity`, and `flags_label` cell fields arrive pipe-escaped and
-whitespace-normalized.
-
-Each board load runs the scoped store check (`doctor --store <scope>`): the global board runs
-`--store global` and a project board runs `--store <slug>`. The result rides in the payload as
-`store_health` (`{scope, status, summary, failing_checks}`). Surface it as a one-line
-store-health note on the board (for example `store health: pass (3/3)` or
-`store health: warn (orphaned_intents)`). It is non-fatal: a warn or fail is shown as data and
-never blocks the board.
-
-### Step 2 — Fill the matching template
-
-Templates live in this skill's `templates/` directory:
-`~/.claude/skills/plastic-dashboard/templates/dashboard-global.md` and
-`dashboard-project.md`.
-
-Fill mechanically, no rewriting, no re-sorting:
-- `{{a.b.count}}` → the integer (e.g. `counts.active` = that count).
-- `{{<list>.rows}}` → the two intent lists (`active`, `next_work`) render as **Markdown table
-  rows**. The template hard-codes each table's header and separator; this placeholder becomes
-  one data row per list entry, joined with real newlines, in that table's fixed column order
-  (below). Drop each cell from the named payload field **verbatim**: cells arrive pre-escaped
-  and whitespace-normalized from the script (pipes escaped as `\|`), so never re-escape,
-  re-truncate, or reword them. Never emit `<br>`.
-  - `next_work` → `| {id} | {what} | {value} | {disposition} | {flags_label} |`
-  - `active` → `| {id} | {what} | {stage} | {worker} | {activity} |`
-  Empty list → one full-width row with `_(none)_` in the Graph ID column and every other cell blank,
-  matching that table's column count (e.g. `| _(none)_ | | | | |` for the 5-column next_work
-  table, `| _(none)_ | | | |` for the 5-column active table). Neither list carries an overflow
-  "+N more" row anymore (D5, intent 202): the true pool size rides on the payload as
-  `active_total`/`next_total` (shown counts as `active_shown`/`next_shown`), and `{{footer}}`
-  states it in prose instead.
-- `{{projects.lines}}` (global board only) → the project rollup stays **prose**, one line per
-  project (not a table):
-  `- **{slug}**: {description}, active {active}, done {done}, future {future}, last accessed {last_accessed_at[0,10]}`.
-- Scalars (`{{date}}`, `{{slug}}`, `{{summary}}`, `{{footer}}`) → substitute verbatim. `summary`
-  and `footer` are finished prose built in `dashboard.rb`; do not rewrite, shorten, or
-  re-derive them from the counts - that is exactly the non-determinism D5 rules out.
-
-### Paging (conversational, D4)
-
-The board shows a short page by default (Active capped at 3, Next-work at 5). When the
-user asks for "more" or "all", re-invoke Step 1 with an explicit flag and re-fill the
-template with the new payload - nothing is persisted to disk, the offset lives only in the
-chat turn:
-- "all" → add `--all` (lifts both caps to unbounded; the footer then shows equal shown/total).
-- "more" → add `--limit-active N`/`--limit-next N` with a larger `N` for whichever list the
-  user is paging.
-
-For a real, own-terminal pager instead, point the owner at `--plain`:
-`ruby ~/.plastic/scripts/dashboard.rb project <slug> --plain | less` (or `continue --plain`
-for the global board). `--plain` prints the full, uncapped board as plain text with no
-Markdown table syntax; it is a separate CLI mode from `--data`, not something this skill
-fills a template from.
-
-### Step 3 — Present it (mandatory, every invocation)
-
-**Paste the filled Markdown into your reply.** This is non-optional: if the reply does not
-contain the filled Markdown, the user sees nothing — tool-call stdout and hook
-`additionalContext` are both invisible to them. Never describe the board instead of showing
-it, and never assume a hook already showed it for you.
-
-`hook-continue` also emits a one-line `systemMessage` summary (counts, and the next big thing
-when there is one) as a hook-owned fallback, independent of the agent's reply. Treat that line
-as a floor only, not a substitute for this step: it carries no matrix, no recently-worked
-section, and no entry-flow prompt. Presenting the full board here remains mandatory regardless
-of whether the summary line fired. This stays a soft, agent-followed mechanism — there is no
-stronger enforcement for a full multi-section Markdown document in this harness today.
-
-### Step 4 — Entry flow (the board is the menu)
-
-QMD-first (when available): when the user navigates by describing an intent rather than giving its
-id, before scanning the store with grep/Read run `ruby ~/.plastic/scripts/qmd-sync search "<terms>"`
-to surface the candidate intent, then open the authoritative intent file for the hit. The command is
-a no-op when QMD is absent, so fall back to the existing INDEX.md / file scan.
-
-The board lists everything; the user navigates by free prose (no capped picker):
-- On the **global** board, the user replies with an **intent id** (work it), a **project
-  name** (re-run `project <slug> --data` and present that board), or **"new"** (start a new
-  intent in global via `plastic-intent-creating`).
-- On a **project** board, the user replies with an **intent id**, or **"global"** to return.
-
-## Auto-mode contract (`--json`)
-
-`plastic-auto` consumes a separate machine-readable manifest (unchanged):
-
-```bash
-ruby ~/.plastic/scripts/dashboard.rb [continue|project <slug>|all] --json
-```
-
-```json
-{ "generated_for": "auto-mode", "scope": "<scope|all>",
-  "next_big_thing": "<id|null>",
-  "dispatchable_queue": [ {"id","scope","disposition","type","value","effort","flags","rank"} ],
-  "human_only": ["<id>", "..."] }
-```
-
-Work `dispatchable_queue` in `rank` order (`defer`/`research`); leave `human_only` for the user.
-
-## Text modes (terminal / legacy)
-
-`dashboard.rb [continue|project <slug>|all]` with no flag still prints the ASCII cockpit for
-a raw terminal. The Markdown board (`--data` + template) is the surface for the chat UI.
-
-## How classification works (deterministic)
-
-The script computes Effort/Value/Flags/Override/Caps; the agent never re-derives them.
-To explain or debug a ranking or disposition, read `references/classification.md`.
-
-## Eval
-
-The eval is the payload + golden snapshots: run the engine against the fixture store and
-assert the `--data` payload shape/sorting/classification and the byte-identical `--json` +
-text goldens in [`test/fixtures/dashboard/`](https://github.com/zalom/plastic/tree/main/test/fixtures/dashboard). See [`dashboard_test.rb`](https://github.com/zalom/plastic/blob/main/test/dashboard_test.rb). Drift without an
-intentional change means the skill is broken.
-
-## Notes
-
-- The two intent lists (active, next work) render as Markdown tables; the prose summary,
-  footer, counts, and the project rollup stay prose (intent 202). No Value x Effort grid
-  returns. Never emit `<br>`.
-- Clusters (Zettelkasten grouping in INDEX.md) are intentionally not rendered.
-- Additive: changes no core lifecycle, gate, or cycle logic.

package/skills/dashboard/evals/evals.json

@@ -1,38 +0,0 @@
-{
-  "skill_name": "plastic-dashboard",
-  "notes": "Intent 66a. Spec for the QMD-first step in the entry flow (resolve a free-prose intent reference before grep/Read). Runner is intent 76; spec only.",
-  "evals": [
-    {
-      "id": 1,
-      "scope": "behavior",
-      "set": "validation",
-      "prompt": "QMD is present. On the board, the user navigates by describing an intent (the search verb work) instead of giving its id.",
-      "expected_output": "Before scanning the store with grep/Read to resolve the free-prose reference, runs `ruby ~/.plastic/scripts/qmd-sync search \"search verb\"` to surface the candidate intent, then opens the authoritative intent file for the hit. No-op fallback to INDEX.md / file scan when QMD is absent.",
-      "files": [],
-      "assertions": [
-        {
-          "type": "human",
-          "check": "qmd-sync search is run before grep/Read when the user navigates by description; authoritative file opened for the hit",
-          "observed": "SKILL.md (or agent file) carries the QMD-first step: run qmd-sync search before grep/Read, then open the authoritative file; no-op fallback when QMD is absent",
-          "result": "pass"
-        }
-      ]
-    },
-    {
-      "id": 2,
-      "scope": "behavior",
-      "set": "validation",
-      "prompt": "How does the project board render after intent 202 (short by default, paged on request)?",
-      "expected_output": "The project board shows, in order, and nothing else: a 2-3 sentence prose summary of what was delivered most recently (built in dashboard.rb from completed/completed_on data, not the 24h-windowed recently_worked), an Active table capped at 3 rows (Id|What|Stage, ordered lifecycle-stage descending with a savepoint tie-break), a Next-work table capped at 5 rows (Id|What|Value|Disposition|Flags), and a one-line footer stating true totals (e.g. '3 of 12 active, 5 of 47 next work') plus how to see everything. The raw Future table and its {{future.rows}} placeholder, and the separate Recently-worked table, are both gone from dashboard-project.md. dashboard-global.md carries the equivalent fix (D6): a prose summary in place of its recently-worked table, the same honest footer, and the same --limit-active/--limit-next/--all/--plain mechanics.",
-      "files": ["skills/dashboard/templates/dashboard-global.md", "skills/dashboard/templates/dashboard-project.md", "skills/dashboard/SKILL.md"],
-      "assertions": [
-        {
-          "type": "convention",
-          "check": "project board template has summary+active+next_work+footer only (no future, no recently_worked table); global template has summary+footer added; SKILL.md documents the new payload fields and CLI flags",
-          "observed": "templates carry {{summary}}, {{active.rows}} (Id|What|Stage), {{next_work.rows}} (Id|What|Value|Disposition|Flags), {{footer}}; {{future.rows}} and the recently-worked table are removed from both; SKILL.md Step 1/2 document summary/footer/active_total/active_shown/next_total/next_shown and --limit-active/--limit-next/--all/--plain",
-          "result": "pass"
-        }
-      ]
-    }
-  ]
-}

package/skills/dashboard/references/classification.md

@@ -1,22 +0,0 @@
-# How Classification Works (Deterministic)
-
-The script (`dashboard.rb`) computes Effort/Value/Flags/Override/Caps deterministically;
-the agent never re-derives them. Read this to explain or debug a ranking or disposition.
-
-- **Effort** — small for `research`/`exploration`/`bugfix`, for already-scoped intents
-  (plan/checklist exists), or a **branch id** (folgezettel depth ≥ 2, e.g. `4a`, `12b3`); big
-  otherwise. A root id (a bare number) is always depth 1, so it is never demoted by this rule.
-- **Value → high** when any of: explicit `value: high`; a human-authored **root** intent; or
-  an intent that is a `source` of ≥1 other intent (it has spawned follow-on work). A purely
-  relational `chain` entry alone is **not** a value signal (intent 68) — else low.
-- **Flags** — `unblocked` only when a **future** intent has **all** its `sources` done AND at
-  least one source's completion date is strictly later than the intent's own `created` date (a
-  genuine wait, not a birth-time default); `in-progress` only when the savepoint ledger shows
-  real post-birth activity, not just the creation stamp; `stale` only on future intents past
-  the staleness threshold. All three kept low-noise by design.
-- **Override** — a `value: high|low` frontmatter field always wins (pre-stamped data, never
-  model judgment at render time).
-- **Caps**: the next-work list and the project board's `active`/`future` lists are capped at
-  8 entries plus a trailing "+N more" line; each entry's text is truncated to 120 characters
-  with a trailing ellipsis. Applies to the Markdown board only (the ASCII renderer has its own
-  separate `CELL_CAP`).

package/skills/dashboard/templates/dashboard-global.md

@@ -1,20 +0,0 @@
-# 🧩 Plastic · Global Board, {{date}}
-
-{{summary}}
-
-## Where we are
-
-{{counts.active}} intents active, {{counts.done}} done, {{counts.future}} queued for later.
-
-## Projects, active {{project_totals.active}}, done {{project_totals.done}}, future {{project_totals.future}}
-{{projects.lines}}
-
-## Most-valuable next work
-
-| Graph ID | Intent | Value | Disposition | Flags |
-| --- | --- | --- | --- | --- |
-{{next_work.rows}}
-
-{{footer}}
-
-**What would you like to work on next?** (type an **intent id**, a **project name**, or anything **new** you'd like to start)

package/skills/dashboard/templates/dashboard-project.md

@@ -1,19 +0,0 @@
-# 📦 {{slug}} · Project Board, {{date}}
-
-{{summary}}
-
-**Active**
-
-| Graph ID | Intent | Stage | Worker | Activity |
-| --- | --- | --- | --- | --- |
-{{active.rows}}
-
-**Most-valuable next work**
-
-| Graph ID | Intent | Value | Disposition | Flags |
-| --- | --- | --- | --- | --- |
-{{next_work.rows}}
-
-{{footer}}
-
-**What would you like to work on next?** (type an **intent id**, or **global** to go back)

package/skills/direct/SKILL.md

@@ -1,66 +0,0 @@
----
-name: plastic-direct
-description: Use when a prompt asks for a change, a fix, an edit, a file, or an answer, and no thinking conversation is open on an intent. Judges whether the work is small enough to run right now, asks one clarifying question when one answer would settle it, or offers a thinking intent when it would not. Do not use for a prompt that says "auto" or "continue", a prompt asking to start a new intent, or a prompt inside an open thinking conversation, which belong to plastic-auto, plastic-intent-continuing, plastic-intent-creating, and plastic-intent-speccing.
-user-invocable: false
----
-
-# Direct mode
-
-Route the prompt in one read, then act. Direct work runs inline in this session, never through a
-dispatched agent, unless the user asks for agents.
-
-## 1. Estimate before you start
-
-Judge the prompt alone, before doing any of the work:
-
-1. Count the targets the prompt names, or that one grep finds.
-2. Require each change to be a named operation on a known target (rename this, add a check there,
-   delete that line), not an outcome ("clean it up", "make it faster").
-3. Budget about one minute per target and sum.
-4. At or under five minutes, run it now. Five minutes is an owner ruling, not a measured
-   threshold.
-5. A bounded sum above five minutes, offer a dedicated intent.
-6. An unknown target, or a change described only by its outcome, cannot be bounded. Ask one
-   question when one answer would supply the missing operation or target. Otherwise offer a
-   thinking intent. A target that only investigation can find is never settled by one
-   question.
-
-Tests or a build the prompt implies do not count against the budget. Verification is part of
-direct work, not a reason to leave direct mode.
-
-## 2. One question, then run
-
-A clarifying question is allowed in direct mode and does not by itself turn the request into a
-thinking intent. Ask one, then run. If the answer is still vague, offer a thinking intent rather
-than asking a second question or guessing.
-
-## 3. The routes
-
-| What the prompt looks like | Where it goes |
-|---|---|
-| Clear, and bounded at or under five minutes | Run it now, inline |
-| Clear, but the bounded estimate is above five minutes | Offer a dedicated intent, `plastic-intent-creating` |
-| Vague, and one answer would resolve it | Ask one clarifying question, then run |
-| Still vague after that one answer | Offer a thinking intent, `plastic-intent-speccing` |
-| Phrased as needing help rather than as an instruction | Offer grill plus a thinking conversation, `plastic-intent-speccing` |
-| Says "auto" explicitly | Hand off to `plastic-auto` |
-
-Read `references/request-signals.md` when a prompt sits on the boundary between two routes, for
-the 15 observable signals and the response each one selects.
-
-## 4. Record and verify
-
-- Verification in direct mode is the UI, the tests, or the user. There is no reviewer agent per
-  item.
-- Only a prompt that changes something on disk or produces an artifact becomes a checklist item.
-  A pure question is answered inline and recorded nowhere.
-- Direct work records into the day ledger for the session's day (the oldest day in the last
-  seven whose checklist carries the session's line, else today). Never write that lookup by hand.
-
-## 5. What direct does not take
-
-The capture hook detects `auto` and `continue` before you read the prompt, so defer rather than
-keyword-match them yourself. `auto` goes to `plastic-auto`, and `continue` goes to
-`plastic-intent-continuing`. On `auto` with no registered intent, route through
-`plastic-intent-creating` first, because auto requires a registered intent. A prompt that arrives
-inside an open thinking conversation belongs to that conversation, not here.

package/skills/direct/references/request-signals.md

@@ -1,59 +0,0 @@
-# Request signals
-
-The table below is reproduced from
-`296--make-plastic-faster-small-work/resources/research--request-analysis.md`, the
-request-analysis research deposit of intent 296, with its source column renumbered against the
-eight-source list below. Read it when a prompt sits on the boundary between two routes. That
-deposit also carries seven worked examples, one per boundary, for a reader who wants them.
-
-## The signal table
-
-| Signal | What it looks like in a real prompt | Response it selects | Source or ruling |
-|---|---|---|---|
-| A concrete file and a concrete operation are named | "Rename `foo` to `bar` in `app/models/user.rb` and update its three callers." | execute now | D13, D14 |
-| The target is a single, already-known location | "Fix the typo in README.md line 12." | execute now | D14 |
-| The change is described only by its outcome, with no operation named | "Clean up the user model, it's gotten messy." | ask one clarifying question | Kamsties, "Understanding Ambiguity in Requirements Engineering" (source 5); D13 |
-| The prompt uses weak, hedging modal language ("might", "could", "maybe", "somewhere") | "This might need better error handling somewhere in the payment flow." | ask one clarifying question | "Automatic Detection of Ambiguous Terminology for Software Requirements" (weakness ambiguity, source 6); D13 |
-| The prompt admits several equally plausible readings with no cue that favors one | "Make the form better." (styling, validation, and accessibility are all live readings) | ask one clarifying question | "Knowing but Not Showing" (source 3); "Ask or Assume?" (source 1) |
-| One answer to the clarifying question fully resolves scope | User answers: "Just the null check on line 42, nothing else." | execute now | D10 |
-| The answer to the clarifying question is itself vague or open-ended | User answers: "I don't know, whatever seems right." | offer a thinking intent | D13; "Ask or Assume?" (source 1) |
-| The prompt is phrased as a request for help rather than an instruction | "I need help figuring out how to structure the billing refactor, not sure where to start." | offer a thinking intent | D13 |
-| The number of named or discoverable targets is small (roughly one to three) and each change is additive | "Update the copyright year in these three footer partials." | execute now | D14 |
-| The number of targets is large, or the work is described as spanning many files | "Migrate all 40 view partials to the new component library." | offer a thinking intent | D14 |
-| The target is not yet known and must be found by investigation before any edit is possible | "Something is causing the checkout page to be slow, find it and fix it." | offer a thinking intent | D14; sources 7 and 8 |
-| The action is destructive or hard to reverse and its scope is ambiguous | "Delete the old migrations directory." | ask one clarifying question | "Structured Uncertainty guided Clarification for LLM Agents" (source 4) |
-| The action is destructive but small, self-contained, and obviously scoped | "Delete the unused `tmp_debug.rb` file I just created." | execute now | D14 |
-| The request implies running tests or a build step the agent can run itself as part of verification | "Fix the failing test in user_test.rb." | execute now | D15 |
-| The prompt changes nothing on disk and produces no artifact | "What does the PaymentProcessor class do?" | execute now (answered inline; never admitted as a checklist item) | D17 |
-
-Row 8 uses the deposit's wording. Ruling D13 makes the help-needed route grill plus a
-thinking conversation, as `SKILL.md` section 3 states.
-
-## Rulings, not findings
-
-Four things in the table above are owner rulings with no literature behind them. Apply
-them, and know they are policy knobs the owner can turn, not measured results.
-
-- The five-minute total and the one-minute-per-target budget. Task-complexity research (sources 7
-  and 8) correlates target count and search depth with lower agent success, which supports
-  counting targets, but no source sets these numbers.
-- The one-question cap. The clarification research (sources 1, 2, and 4) treats question count as
-  a calibrated, cost-weighted choice that can be zero, one, or more. A hard cap of one is the
-  owner's choice.
-- "Auto" meaning auto mode. It is an interface convention, a keyword that names the mode instead
-  of asking for a judgement.
-- "Help needed" phrasing meaning grill plus a thinking conversation. It is a register cue
-  specific to how this owner phrases requests, not a general finding.
-
-## Sources
-
-1. "Ask or Assume? Uncertainty-Aware Clarification-Seeking in Coding Agents." https://arxiv.org/abs/2603.26233
-2. "Learning to Ask: When LLM Agents Meet Unclear Instruction." EMNLP 2025. https://aclanthology.org/2025.emnlp-main.1104.pdf
-3. "Knowing but Not Showing: LLMs Recognize Ambiguity but Rarely Ask Clarifying Questions." https://arxiv.org/pdf/2605.25284
-4. "Structured Uncertainty guided Clarification for LLM Agents." https://openreview.net/forum?id=dc8ebScygC
-5. Kamsties, Erik. "Understanding Ambiguity in Requirements Engineering." https://link.springer.com/chapter/10.1007/3-540-28244-0_11
-6. "Automatic Detection of Ambiguous Terminology for Software Requirements." https://www.eecis.udel.edu/~yuewang/paper/nldb2013.pdf
-7. "An Approach for Systematic Decomposition of Complex LLM Tasks." https://arxiv.org/html/2510.07772v1
-8. "On the Importance of Task Complexity in Evaluating LLM-Based Multi-Agent Systems." https://arxiv.org/html/2510.04311
-
-All eight were accessed 2026-08-29. The D-numbers in the table are decisions in `296/spec.md`.