@zalom/plastic 2.0.0-alpha.8 → 2.0.1

package/{skills/tutorial/references → docs/help}/track-3-projects-and-roadmaps.md

@@ -9,7 +9,7 @@ will exist with more than one intent inside it and a roadmap file describing the
 
 ## Before you start
 
-Run `/plastic-update` first (`$plastic-update` on Codex), so the commands below match what is
+Run `plastic update` first, so the commands below match what is
 actually installed.
 
 Work in a sandbox: this whole track is a walked example. It creates a real project directory
@@ -20,11 +20,11 @@ one this tutorial keeps or ships.
 
 ### 1. Start from a founding implementation intent
 
-Create and board an intent the same way as track 1, stations 1 and 2: `/plastic-intent-creating`,
-then `/plastic-intent-continuing`. Describe something meant to grow into a small real project,
+Create and board an intent the same way as track 1, stations 1 and 2: `plastic intent new`,
+then `plastic continue`. Describe something meant to grow into a small real project,
 for example "build a personal todo app."
 
-Then type `/plastic-intent-speccing` and record a couple of real rulings on this founding
+Then type `plastic intent spec` and record a couple of real rulings on this founding
 intent, for example the language or how tasks get stored. Keep it short: this intent only
 needs enough decisions for the new project to inherit, not a full design.
 
@@ -33,17 +33,21 @@ into a whole new project.
 
 ### 2. Grow it into a project
 
-Type `/plastic-project-creating`.
+Make the project directory yourself and write its `AGENTS.md`, carrying forward at least one
+decision from the founding intent. Plastic does not create the directory or fill that file;
+that is ordinary agent work, done once, before the project exists. Once the directory exists,
+run `plastic project new SLUG --path PATH` to register it in `projects.yml` and provision and
+validate its store.
 
-Artifact: a new project directory, an `AGENTS.md` file carrying the founding intent's
-decisions, the project's own intent store, and a new entry in `projects.yml` registering it.
+Artifact: a new project directory with its `AGENTS.md`, the project's own intent store, and a
+new entry in `projects.yml` registering it.
 
 Checkpoint: open `AGENTS.md` and find at least one line that traces back to a decision
 recorded in the founding intent back in station 1.
 
 ### 3. Add more intents inside the project
 
-Type `/plastic-intent-creating` at least twice, from inside the project, describing two
+Run `plastic intent new` at least twice, from inside the project, describing two
 pieces of real work, for example "add a task list model" and "add a due date field."
 
 Artifact: two or more intent directories inside the project's own store, separate from the
@@ -54,13 +58,16 @@ in the global store.
 
 ### 4. Plan a delivery batch
 
-Type `/plastic-roadmap`.
+Copy `templates/roadmap.md` to `roadmaps/<slug>.md`, next to the project's `INDEX.md`, and fill
+it by hand: a title and short meta header, a `## Goal` section in prose describing what "done"
+looks like for the whole batch, a `## Batches` section (an ordered list of groups of intents;
+intents inside one batch are safe to run in parallel, batches themselves run one after another),
+and an append-only, dated `## Log`. `INDEX.md` stays the single source of truth for each
+intent's status; the roadmap only mirrors it. List the two or more intents from station 3
+across one or more batches.
 
-Teach the roadmap file shape exactly: a title and short meta header, a `## Goal` section in
-prose describing what "done" looks like for the whole batch, a `## Batches` section (an
-ordered list of groups of intents; intents inside one batch are safe to run in parallel,
-batches themselves run one after another), and an append-only, dated `## Log`. `INDEX.md`
-stays the single source of truth for each intent's status; the roadmap only mirrors it.
+Run `plastic roadmap check <slug>` to confirm the file parses, then `plastic roadmap show
+<slug>` to see it rendered as a report.
 
 Artifact: a new `roadmaps/<slug>.md` file, sitting next to the project's `INDEX.md`, listing
 the two or more intents from station 3 across one or more batches.
@@ -93,8 +100,8 @@ sections you turned into the condition above.
 
 No command run here; describe the step instead. Each delivered intent's code merges to main
 as it lands. When the batch (or a meaningful slice of it) is ready to ship, cutting a release
-runs through `/plastic-releasing`, which merges, bumps the version, tags, and completes the
-intents it collects.
+is a push to `alpha`, `beta`, or `main`: the version files are bumped in that push, and CI
+tags, publishes, and completes the intents it collects.
 
 Releases and any npm publish step are described here, not run: this walkthrough stays in a
 sandbox and never touches a real package registry.
@@ -108,4 +115,4 @@ This is the same What, Why, How, Exec cycle from tracks 1 and 2, repeated across
 and gathered by a roadmap. Read
 [`using-plastic-with-claude-code.md`](https://github.com/zalom/plastic/blob/main/docs/guides/using-plastic-with-claude-code.md) for roadmap-driven delivery in more depth,
 including a real worked roadmap. For the exact roadmap file format beyond what this
-walkthrough covers, the `plastic-roadmap` skill itself is the reference.
+walkthrough covers, [`docs/help/roadmaps.md`](roadmaps.md) is the reference.

package/hooks/call-budget

@@ -0,0 +1,4 @@
+#!/bin/bash
+INPUT=$(cat)
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+echo "$INPUT" | env -u RUBYOPT ruby --disable-gems "$SCRIPT_DIR/../scripts/hook-call-budget"

package/hooks/hooks.json

@@ -17,6 +17,18 @@
         ]
       }
     ],
+    "PreToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook\" call-budget",
+            "statusMessage": ""
+          }
+        ]
+      }
+    ],
     "PreCompact": [
       {
         "matcher": "",
@@ -76,6 +88,18 @@
           }
         ]
       }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook\" stop",
+            "statusMessage": ""
+          }
+        ]
+      }
     ]
   }
 }

package/hooks/message-display

@@ -49,8 +49,26 @@ if [ "$is_index_zero" = 1 ]; then
   # single "#", not "##" — a real screen's own first delta can be as short
   # as "## " — a "##" glob would filter out exactly the message this hook
   # exists to recognize.
+  # 317a (B11): a screen can open with "## " (state, delivered), a bare "▶"
+  # (roster), or a bare "✔" (delay); the JSON may carry the glyph raw or
+  # \u-escaped depending on the encoder. All globs are literal bytes - case
+  # matching is byte-wise, so multibyte literals are safe under bash 3.2.
   case $INPUT in
     *'"delta":"#'*|*'"delta": "#'*) handoff=1 ;;
+    *'"delta":"▶'*|*'"delta": "▶'*) handoff=1 ;;
+    *'"delta":"✔'*|*'"delta": "✔'*) handoff=1 ;;
+  esac
+  # 331a review fix (M12e): chunk 0 is not exempt from D5 either. The
+  # intent's own flagship shape -- a lead-in sentence and the opener in the
+  # SAME first chunk -- never starts with "#", "▶", or "✔", so the arm
+  # above alone never sees it. Joins it with the identical opener-anywhere
+  # globs used for a later chunk (M12a) rather than replacing anything:
+  # same reasoning as the comment at that site applies verbatim here.
+  case $INPUT in
+    *'"delta":"'*'▶'*|*'"delta": "'*'▶'*) handoff=1 ;;
+    *'"delta":"'*'✔'*|*'"delta": "'*'✔'*) handoff=1 ;;
+    *'"delta":"'*'\u25b6'*|*'"delta": "'*'\u25b6'*) handoff=1 ;;
+    *'"delta":"'*'\u2714'*|*'"delta": "'*'\u2714'*) handoff=1 ;;
   esac
 else
   # A later chunk: hand off when this message's directory already exists
@@ -62,12 +80,55 @@ else
   [ "$is_final" = 1 ] && handoff=1
   case $INPUT in
     *'"delta":"|'*|*'"delta": "|'*) handoff=1 ;;
-    *'"delta":"**Steps**'*|*'"delta": "**Steps**'*) handoff=1 ;;
+    *'"delta":"**'*|*'"delta": "**'*) handoff=1 ;;
     *'"delta":""'*|*'"delta": ""'*) handoff=1 ;;
     *'"delta":"\n"'*|*'"delta": "\n"'*) handoff=1 ;;
   esac
+  # 331a (D5): the hook engages anywhere. An opener can now fall ANYWHERE
+  # inside a later chunk's own delta, not only at its start (the shape
+  # tests just above), so these globs search the delta value rather than
+  # anchor to its opening quote. Still anchored to the "delta":" key itself
+  # (never dropped, matrix M12d) so an ordinary field elsewhere in the
+  # payload can never be mistaken for the delta's own text; within that,
+  # every shipped opener (## ▶, ## ✔, ▶ In delivery, ✔ + digit) contains a
+  # bare ▶ or ✔, so matching the bare glyph anywhere covers all four at
+  # once. Prose that merely shapes like an opener still hands off this way
+  # (an accepted over-match: Ruby's own grammar is the final, stricter
+  # arbiter and fails open on anything that is not a real one). Raw glyph
+  # and \u-escaped forms both count, since the encoder's choice is not ours
+  # to predict.
+  case $INPUT in
+    *'"delta":"'*'▶'*|*'"delta": "'*'▶'*) handoff=1 ;;
+    *'"delta":"'*'✔'*|*'"delta": "'*'✔'*) handoff=1 ;;
+    *'"delta":"'*'\u25b6'*|*'"delta": "'*'\u25b6'*) handoff=1 ;;
+    *'"delta":"'*'\u2714'*|*'"delta": "'*'\u2714'*) handoff=1 ;;
+  esac
 fi
 
 [ "$handoff" = 1 ] || exit 0
 
+# 331a1 (D1): chunk 0 is about to hand off to Ruby, which takes on the
+# order of 150 ms to boot before it ever writes SCREEN or NOSCREEN. Claude
+# Code fires the per-chunk hook PROCESSES CONCURRENTLY (see the header
+# comment above), so a later chunk landing inside that window used to find
+# no message directory at all, fail this script's own cheap shape test,
+# and pass through as raw Markdown - measured at 15 to 21 chunks of every
+# screen, against a stream-realistic 5 ms stagger. Staking a PENDING
+# marker here, the instant the handoff gate above passes, closes that
+# window down to microseconds: a later chunk's own "does the directory
+# exist" check (below, unchanged) now finds it almost at once, and
+# MessageDisplay polls for the real decision instead of judging the
+# chunk's own shape. mkdir is the one non-builtin on this whole path - it
+# forks, unlike everything else in this file - but it runs ONLY here,
+# after the handoff gate, so the ordinary (non-candidate) chunk that is
+# the overwhelming common case still forks nothing (matrix L8). A failed
+# mkdir or printf (an unwritable tmp root, a race with another process) is
+# silently swallowed: it must never change this script's own exit status
+# or skip the Ruby handoff below - Ruby's own polling already fails open
+# (D5) when no decision ever appears.
+if [ "$is_index_zero" = 1 ]; then
+  mkdir -p "$MSGDIR" 2>/dev/null
+  printf '' > "$MSGDIR/PENDING" 2>/dev/null
+fi
+
 printf '%s' "$INPUT" | env -u RUBYOPT ruby "$SCRIPT_DIR/../scripts/hook-message-display"

package/hooks/session-start

@@ -1,5 +1,9 @@
 #!/bin/bash
-GLOBAL_INDEX="$HOME/.plastic/INDEX.md"
+if [ -d "$HOME/.plastic/stores" ]; then
+  GLOBAL_INDEX="$HOME/.plastic/stores/global/INDEX.md"
+else
+  GLOBAL_INDEX="$HOME/.plastic/INDEX.md"
+fi
 
 if [ ! -f "$GLOBAL_INDEX" ]; then
   exit 0

package/hooks/statusline

@@ -2,8 +2,8 @@
 # plastic-hook-version: 4.0.0
 # StatusLine hook - Plastic owns the full statusline (no chaining).
 # Renders: {model} - ctx {pct}% ({used}/{size}) - 5h {p}% - 7d {p}% - ${cost}
-#          - claudish {n} rw / {tok} - Plastic {version}[ -> {next}] - {path}
-# Every segment but claudish and the Plastic version comes from the stdin payload.
+#          - Plastic {version}[ -> {next}] - {path}
+# Every segment but the Plastic version comes from the stdin payload.
 # Pure bash (macOS 3.2 compatible). No ruby, no jq. Reads stdin once; small file reads
 # only. The stdin JSON is walked in a single awk pass (below); nothing else in this
 # script forks a second process per field, which is what keeps a render cheap.
@@ -17,7 +17,6 @@ C_OK=''                             # default   - meter below 70%
 C_WARN=$'\033[33m'                  # yellow    - meter at 70% and above
 C_CRIT=$'\033[38;2;231;76;60m'      # red       - meter at 90% and above
 C_COST=$'\033[37m'                  # white     - session cost
-C_CLAUDISH=$'\033[38;2;249;140;30m' # orange    - claudish rewrites
 C_VER=$'\033[37m'                   # white     - "Plastic {version}" and update arrow
 C_NEXT=$'\033[33m'                  # yellow    - next version
 C_PATH=$'\033[38;2;128;134;144m'    # gray      - path (matches dim UI text)
@@ -188,6 +187,7 @@ FIELDS=$(printf '%s' "$INPUT" | awk '
     wanted["context_window.current_usage.cache_read_input_tokens"] = 1
     wanted["cost.total_cost_usd"] = 1
     wanted["rate_limits.five_hour.used_percentage"] = 1
+    wanted["rate_limits.five_hour.resets_at"] = 1
     wanted["rate_limits.seven_day.used_percentage"] = 1
   }
   { buf = buf $0 " " }
@@ -210,6 +210,7 @@ CU_CC=""
 CU_CR=""
 COST_RAW=""
 M5_PCT=""
+M5_RESETS=""
 M7_PCT=""
 
 while IFS=$'\t' read -r k v; do
@@ -225,6 +226,7 @@ while IFS=$'\t' read -r k v; do
     context_window.current_usage.cache_read_input_tokens) CU_CR="$v" ;;
     cost.total_cost_usd) COST_RAW="$v" ;;
     rate_limits.five_hour.used_percentage) M5_PCT="$v" ;;
+    rate_limits.five_hour.resets_at) M5_RESETS="$v" ;;
     rate_limits.seven_day.used_percentage) M7_PCT="$v" ;;
   esac
 done <<FIELDS_EOF
@@ -302,6 +304,31 @@ meter_seg() {   # $1 = label, $2 = raw percentage
 M5=$(meter_seg "5h" "$M5_PCT")
 M7=$(meter_seg "7d" "$M7_PCT")
 
+# --- Rate-limits cache for MeterWatch (graph.md D11) ---
+# Written only when the payload carries a meter at all; an API-key session
+# with no rate_limits section leaves the cache untouched. A present meter
+# with no matching value writes null rather than dropping the key, so
+# MeterWatch always sees the same three fields. Temp file in the cache
+# directory, then mv, so MeterWatch never reads a half-written file.
+if [ -n "$M5_PCT" ] || [ -n "$M7_PCT" ]; then
+  CACHE_DIR="$HOME/.plastic/.cache"
+  mkdir -p "$CACHE_DIR"
+  CACHE5=$(to_int "$M5_PCT")
+  CACHE7=$(to_int "$M7_PCT")
+  [ -z "$CACHE5" ] && CACHE5=null
+  [ -z "$CACHE7" ] && CACHE7=null
+  if [ -n "$M5_RESETS" ]; then
+    RESETS_JSON="\"$M5_RESETS\""
+  else
+    RESETS_JSON=null
+  fi
+  CACHE_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+  CACHE_TMP="$CACHE_DIR/.rate-limits.json.tmp.$$"
+  printf '{"five_hour":%s,"seven_day":%s,"resets_at":%s,"at":"%s"}\n' \
+    "$CACHE5" "$CACHE7" "$RESETS_JSON" "$CACHE_AT" > "$CACHE_TMP"
+  mv "$CACHE_TMP" "$CACHE_DIR/rate-limits.json"
+fi
+
 # --- Session cost (stdin cost.total_cost_usd); hidden when it renders as $0.00 ---
 COST_SEG=""
 if [ -n "$COST_RAW" ]; then
@@ -309,40 +336,18 @@ if [ -n "$COST_RAW" ]; then
   [ -n "$COST_FMT" ] && [ "$COST_FMT" != "0.00" ] && COST_SEG="${C_COST}\$${COST_FMT}${RST}"
 fi
 
-# --- claudish rewrites for THIS session (fork ledger, optional) ---
-# Tab separated, one call per line; column 11 is the session id. Rows written
-# before that column existed have 9 or 10 fields and never match, so an old
-# ledger renders no segment instead of a wrong one.
-CL_SEG=""
-CL_LOG="${CLAUDISH_LOCAL_DIR:-$HOME/.claude/claudish-local}/usage.log"
-if [ -n "$SID" ] && [ -f "$CL_LOG" ]; then
-  CL=$(awk -F'\t' -v sid="$SID" '
-    NF >= 11 && $11 == sid { n++; t += $5 + $6 }
-    END {
-      if (n > 0) {
-        if (t >= 1000) {
-          s = sprintf("%.1f", t / 1000); sub(/\.0$/, "", s); printf "%d %sk", n, s
-        } else {
-          printf "%d %d", n, t
-        }
-      }
-    }' "$CL_LOG" 2>/dev/null)
-  [ -n "$CL" ] && CL_SEG="${C_CLAUDISH}claudish ${CL%% *} rw / ${CL#* }${RST}"
-fi
-
 # --- Assemble segments in order, joined by " . " ---
 PARTS=""
 add() { [ -z "$1" ] && return; if [ -z "$PARTS" ]; then PARTS="$1"; else PARTS="$PARTS$SEP$1"; fi; }
 
-# Order: identity first (model), then this session's spend (context, meters, cost,
-# rewrites), then the volatile-length values last (version, path) so the line does
+# Order: identity first (model), then this session's spend (context, meters, cost),
+# then the volatile-length values last (version, path) so the line does
 # not visually jump as they change.
 [ -n "$MODEL" ] && add "${C_MODEL}${MODEL}${RST}"
 add "$CTX_SEG"
 add "$M5"
 add "$M7"
 add "$COST_SEG"
-add "$CL_SEG"
 if [ -n "$VERSION" ]; then
   vseg="${C_VER}Plastic ${VERSION}${RST}"
   [ -n "$NEXT" ] && vseg="${vseg}${C_VER} "$'\342\206\222'" ${RST}${C_NEXT}${NEXT}${RST}"

package/hooks/stop

@@ -0,0 +1,5 @@
+#!/bin/bash
+INPUT=$(cat)
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+echo "$INPUT" | env -u RUBYOPT ruby "$SCRIPT_DIR/../scripts/hook-stop" "$HOME/.plastic"
+exit 0

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@zalom/plastic",
-  "version": "2.0.0-alpha.8",
+  "version": "2.0.1",
   "description": "Intent-driven idea development system for AI coding agents",
   "type": "module",
   "bin": {
-    "plastic": "bin/plastic.js"
+    "plastic": "bin/plastic"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -27,13 +27,15 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/zalom/plastic"
+    "url": "git+https://github.com/zalom/plastic.git"
   },
   "homepage": "https://github.com/zalom/plastic",
   "files": [
+    "assets/",
     "bin/",
     "scripts/",
     "skills/",
+    "docs/help/",
     "hooks/",
     "agents/",
     "templates/",

package/scripts/append-ledger

@@ -30,6 +30,7 @@
 #   2 - usage error, or promote/tick found nothing to address (no write happens)
 #   3 - promote/tick could not take an exclusive lock (filesystem without flock support)
 
+require_relative "lib/store_layout"
 require_relative "lib/session_ledger"
 require_relative "lib/handoff"
 
@@ -162,7 +163,7 @@ def main(argv)
   usage_abort("verb must be one of #{VERBS.join(", ")}, got #{opts[:verb].inspect}") unless VERBS.include?(opts[:verb])
 
   plastic_home = expand(ENV.fetch("PLASTIC_HOME", "~/.plastic"))
-  store = opts[:store] ? expand(opts[:store]) : File.join(plastic_home, "store")
+  store = opts[:store] ? expand(opts[:store]) : Plastic::StoreLayout.global_store(plastic_home)
   templates = opts[:templates] ? expand(opts[:templates]) : default_templates_dir
   usage_abort("templates dir not found: #{templates}") unless Dir.exist?(templates)
   opts[:templates] = templates