@zalom/plastic 1.0.0-alpha.19 → 1.0.0-alpha.20

package/PLASTIC.md

@@ -19,7 +19,7 @@ store/
     outcome.md            # optional — detailed result (Exec deliverable)
     actions/              # optional — individual work items
     resources/            # optional — research, references, screenshots, diagrams
-    savepoint.md          # optional — session state for resume
+    savepoint.md          # optional — deterministic cycle-step ledger (auto-written)
 ```
 
 Lifecycle files (`spec.md`, `plan.md`, `checklist.md`, `outcome.md`) have defined
@@ -66,9 +66,18 @@ The connection: an intent's `## Insights` feeds the Coordinator's Observe phase.
 | **How** | Planning | `plan.md` + `actions/` + `checklist.md` | `plastic-writing-plans` |
 | **Exec** | Execution | `outcome.md` | `plastic-executing-plan` |
 
-`## Insights` — append-only work log captured throughout ALL stages.
+`## Insights` — append-only work log captured throughout ALL stages. **Append-only means
+newest entry at the bottom; never prepend.** This ordering is a hard convention: Insights
+are the semantic trace of an intent, and a consistent newest-last order keeps that trace
+readable across every intent.
 For full lifecycle detail, the skills in the Detail column have references/.
 
+`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
+succession at a glance (last line = where we are).
+
 ## Gotchas
 
 - **Artifacts go in the intent directory.** Never create `docs/plans/`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zalom/plastic",
-  "version": "1.0.0-alpha.19",
+  "version": "1.0.0-alpha.20",
   "description": "Intent-driven idea development system for AI coding agents",
   "type": "module",
   "bin": {

package/scripts/hook-gate-check

@@ -98,6 +98,14 @@ if is_stage_file || is_action_file
 
   Bridge.write(session, bridge_data)
 
+  # Cycle-step savepoint ledger (intent 34) — record this stage-file milestone.
+  # Best-effort: the ledger is derived sugar, so a failure must never block.
+  begin
+    Bridge.append_savepoint(intent_dir_abs, file_path_abs)
+  rescue StandardError
+    # ignore — rebuildable from disk
+  end
+
   # Build transition context
   stage_labels = { "what" => "What", "why" => "Why", "how" => "How", "exec" => "Exec", "done" => "Done" }
   next_hints = {
@@ -129,7 +137,14 @@ if is_stage_file || is_action_file
   puts JSON.generate(payload)
   exit 0
 else
-  # Regular file in intent dir — just update last_activity
+  # Regular file in intent dir — just update last_activity. The intent file
+  # (What milestone) lands here, so still offer it to the savepoint ledger;
+  # non-milestone files self-filter to a no-op (intent 34).
+  begin
+    Bridge.append_savepoint(intent_dir_abs, file_path_abs)
+  rescue StandardError
+    # ignore — rebuildable from disk
+  end
   bridge_data["build"]["last_activity"] = Time.now.utc.iso8601
   Bridge.write(session, bridge_data)
   exit 0

package/scripts/lib/bridge.rb

@@ -70,6 +70,68 @@ module Bridge
     end
   end
 
+  # --- Cycle-step savepoint ledger (intent 34) ------------------------------
+  #
+  # savepoint.md is a deterministic, append-only, one-line-per-milestone ledger
+  # (newest at the bottom). It is sugar on top of the conventions: derived from
+  # files-on-disk, rebuildable, never a source of truth. Milestones are
+  # file-event boundaries only; action/resource files record nothing.
+
+  SAVEPOINT_FILE = "savepoint.md"
+
+  # Map a written filename to [stage_label, milestone_text], or nil if the file
+  # is not a lifecycle milestone.
+  def self.savepoint_milestone(intent_dir, basename)
+    return ["What", basename] if basename == File.basename(intent_file(intent_dir))
+
+    case basename
+    when "spec.md"      then ["Why", "spec.md created"]
+    when "plan.md"      then ["How", "plan.md created"]
+    when "checklist.md" then ["How", "checklist.md created"]
+    when "outcome.md"   then ["Exec", "outcome.md created"]
+    end
+  end
+
+  # Milestones already recorded in the ledger (field 3 of each line).
+  def self.savepoint_recorded_milestones(intent_dir)
+    f = File.join(intent_dir, SAVEPOINT_FILE)
+    return [] unless File.exist?(f)
+    File.read(f).each_line.map do |line|
+      parts = line.strip.split(/\s{2,}/)
+      parts.length >= 3 ? parts[2] : nil
+    end.compact
+  end
+
+  # Append a milestone line for file_path if (and only if) it is a milestone
+  # not already recorded. Returns true when a line was written, false otherwise.
+  def self.append_savepoint(intent_dir, file_path, now: Time.now)
+    stage, milestone = savepoint_milestone(intent_dir, File.basename(file_path))
+    return false unless milestone
+    return false if savepoint_recorded_milestones(intent_dir).include?(milestone)
+
+    line = "#{now.utc.iso8601}  #{stage}  #{milestone}\n"
+    File.open(File.join(intent_dir, SAVEPOINT_FILE), "a") { |io| io.write(line) }
+    true
+  end
+
+  # Reconstruct the ledger from files on disk (timestamps from mtimes), in
+  # stage order, overwriting savepoint.md. Returns the number of lines written.
+  def self.rebuild_savepoint(intent_dir)
+    ordered = [
+      File.basename(intent_file(intent_dir)),
+      "spec.md", "plan.md", "checklist.md", "outcome.md",
+    ]
+    lines = ordered.filter_map do |basename|
+      path = File.join(intent_dir, basename)
+      next unless File.exist?(path)
+      stage, milestone = savepoint_milestone(intent_dir, basename)
+      next unless milestone
+      "#{File.mtime(path).utc.iso8601}  #{stage}  #{milestone}\n"
+    end
+    File.write(File.join(intent_dir, SAVEPOINT_FILE), lines.join)
+    lines.length
+  end
+
   def self.derive(session, intent_id:, intent_dir:, store:, name:)
     stage = derive_stage(intent_dir)
     has = has_files(intent_dir)

package/skills/savepoint/SKILL.md

@@ -1,61 +1,66 @@
 ---
 name: plastic-savepoint
-description: Use when context is being compacted (PreCompact hook), user says "save" or "savepoint", or before ending a session. Saves the active intent's state so work can resume after /clear.
+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.
 ---
 
 # Savepoint
 
-## When to Use
-- PreCompact hook fires (automatic)
-- User says "save", "savepoint", or "save progress"
-- Before ending a long session
-- Before switching to a different intent
+`savepoint.md` is a deterministic, append-only ledger of an intent's cycle steps, one line
+per lifecycle milestone, newest at the bottom:
 
-## Workflow
+```
+2026-06-16T14:02Z  What  34--cycle-step-savepoints.md
+2026-06-16T14:20Z  Why   spec.md created
+2026-06-16T15:10Z  How   plan.md created
+2026-06-16T15:11Z  How   checklist.md created
+2026-06-16T16:40Z  Exec  outcome.md created
+```
 
-### 1. Find Active Intent(s)
-Read `~/.plastic/INDEX.md` (or the project INDEX.md) and extract all intents listed under `## Active`.
+It is **sugar on top of the conventions**, not a source of truth. The gate hook
+(`hook-gate-check`) writes each line automatically when a stage file is created, so there is
+nothing to save by hand. State is always derivable from files-on-disk; the ledger just lets
+a resuming agent read the cycle's succession from one glance (last line = where we are).
 
-### 2. For Each Active Intent
-Read the intent directory at `~/.plastic/store/ID--slug/`:
+## When to Use
+- A PreCompact hook fires, or the user says "save" / "savepoint": verify the ledger is current.
+- Resuming an intent: read the ledger to learn the cycle's succession quickly.
+- The ledger looks stale, empty, or missing: rebuild it from the filesystem.
 
-**a. Update checklist.md** (if exists):
-- Check off completed items
-- Add any new items discovered during the session
+## What this skill does NOT do
+- It does not write prose, "in progress", "next step", or "blockers". The old 50%-context
+  prose savepoint is retired. The semantic trace lives in `## Insights` (append-only,
+  newest at the bottom); the byte history lives in git.
 
-**b. Create/update savepoint.md:**
-```markdown
-# Savepoint
+## Workflow
 
-## Last Updated
-{{DATE}} — Session #{{N}}
+### 1. Find Active Intent(s)
+Read the active store's `INDEX.md` and extract intents under `## Active`.
 
-## In Progress
-- (what was being worked on when savepoint triggered)
-- Next: (immediate next step)
+### 2. For Each Active Intent — verify the ledger
+- Read `savepoint.md`. Confirm it exists and is non-empty.
+- Confirm the **last line's stage** matches the stage derived from files-on-disk
+  (`Bridge.derive_stage`). If they disagree, or the file is missing/empty, the ledger has
+  drifted.
 
-## Blockers
-(any blockers or open questions)
+### 3. Rebuild on drift
+Reconstruct from the filesystem rather than hand-editing:
 
-## Key Discoveries This Session
-- (important things learned)
+```bash
+ruby -r ~/.plastic/scripts/lib/bridge -e \
+  'Bridge.rebuild_savepoint("<intent_dir>")'
 ```
 
-**c. Update `{ID}--{slug}.md`:**
-- Add observations to `## Insights` section
-
-### 3. Update INDEX.md
-Verify the `## Active` section is accurate.
+This rewrites `savepoint.md` from the milestone files present (timestamps from mtimes),
+in stage order. Safe to run anytime: the ledger is derived.
 
-### 4. Commit
+### 4. Commit (store only)
+If a rebuild changed the ledger, commit it in the store repo:
 ```bash
-git add .plastic/
-git commit -m "chore: savepoint — [active intent name]"
+cd <store-root> && git add . && git commit -m "chore: rebuild savepoint ledger — [intent]"
 ```
-
-### 5. Notify User
-Tell the user: "Context is getting large. I've saved progress to intent [ID] — [name]. Please run `/clear` and say `continue` to resume."
+Never push `~/.plastic/`.
 
 ## References
 
-- Read `references/context-management.md` for the full save/continue protocol when the save flow needs debugging or you need to understand the full resume sequence
+- Read `references/context-management.md` for the full save/continue protocol and how the
+  resume flow consumes the ledger.

package/templates/savepoint.md

@@ -1,13 +1,14 @@
-# Savepoint
-
-## Last Updated
-{{DATE}} — Session #{{N}}
-
-## In Progress
-- ...
-
-## Blockers
-None
-
-## Key Discoveries This Session
-- ...
+# Deterministic cycle-step ledger, written automatically by the gate hook.
+# One line per lifecycle milestone, append-only, newest at the bottom:
+#
+#   {UTC-iso8601}  {Stage}  {milestone}
+#
+# Example:
+#   2026-06-16T14:02:00Z  What  ID--slug.md
+#   2026-06-16T14:20:00Z  Why   spec.md created
+#   2026-06-16T15:10:00Z  How   plan.md created
+#   2026-06-16T15:11:00Z  How   checklist.md created
+#   2026-06-16T16:40:00Z  Exec  outcome.md created
+#
+# This file is sugar on top of the conventions, not a source of truth. It is
+# rebuildable from files-on-disk via Bridge.rebuild_savepoint. Do not hand-edit.