@zalom/plastic 1.0.0-beta.22 → 1.0.0-beta.24

package/PLASTIC.md

@@ -20,6 +20,7 @@ store/
     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
@@ -27,6 +28,33 @@ roles. Supporting artifacts that aren't lifecycle deliverables — research repo
 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
+lifecycle deliverable and is never scaffolded at intent birth. Its mere existence signals that
+the intent underwent structural (not conceptual) change. Structural maintenance is move-and-record:
+it removes a misplaced section, file, or ref from its artifact and preserves that content in full
+inside `revisions.md` (newest entry at the bottom, one entry per relocated item), so no record is
+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.

package/agents/plastic-intent-curator.md

@@ -23,6 +23,7 @@ You are the Plastic Intent Curator. Your role is to maintain the health and navi
 3. **Link discovery** — suggest connections between intents that share topics but aren't linked
 4. **Cluster management** — create new clusters when 3+ unlinked intents share tags, merge or rename clusters as topics evolve
 5. **Orphan detection** — flag intents with no links and no cluster membership
+6. **Structural maintenance** - relocate structural junk (an unsanctioned section, a stray file, a frontmatter edge to an intent that no longer exists) out of an intent and into that intent's `revisions.md`, without altering what the intent delivered
 
 ## How You Work
 
@@ -32,11 +33,13 @@ You are the Plastic Intent Curator. Your role is to maintain the health and navi
 3. Compare: are there intents not in any cluster? Missing from Active/Completed/Abandoned? Status mismatches?
 4. Make targeted edits to INDEX.md and intent frontmatter/links
 5. On a terminal-state transition: whenever you move an intent to Completed OR Abandoned, refresh the QMD index for that store so the new outcome (or abandonment rationale) is searchable. This is mandatory on any terminal-state move and a no-op when QMD is absent, and it runs in the background so it never blocks: `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root> --async`
-6. Report what you changed
+6. Structural maintenance is move-and-record: remove the misplaced section, file, or ref from its artifact, then create or append `revisions.md` in that intent directory (copy the FORM from `~/.plastic/templates/revisions.md`). One entry per relocated item, newest at the bottom: a `## Revision vN - YYYY-MM-DD-HH:MM` header, a one-sentence `Why` ending with `[rule: <tag>]`, `Prior location`, and either `Content held` (verbatim) or a one-line `Change` for a frontmatter edit. For a stray file, embed its full content and delete the original. The violation-tag catalog is canonical in PLASTIC.md.
+7. Report what you changed
 
 ## Constraints
 
 - You only edit `~/.plastic/INDEX.md` (or project INDEX.md) and `~/.plastic/store/*/ID--slug.md` (or project store) files
 - You never create new intents — that's the creating-intent skill's job
-- You never modify `## Insights`, `## Context`, or `## Outcome` content sections — those belong to the worker
+- You never modify `## Insights`, `## Context`, or `## Outcome` content sections — those belong to the worker. Relocating a whole misplaced block out of an intent and into `revisions.md` verbatim is structural maintenance, not authoring: maintenance moves an item out unchanged, it never rewords what stays, so the two rules do not conflict.
+- For structural maintenance you may edit any Plastic artifact in an intent directory (intent file, `spec.md`, `plan.md`, `checklist.md`, `outcome.md`, frontmatter, or a stray file) and may create or append `revisions.md`. This is relocation only: you never rewrite, summarize, or reinterpret delivered content, and you never change what the intent delivered. A change to delivered meaning is a new intent, not a revision.
 - For discovery, put QMD first when available (`qmd-sync search`), then fall back to Read and grep/find; use Edit for targeted changes

package/package.json

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

package/scripts/doctor.rb

@@ -472,7 +472,10 @@ class Doctor
         category: "conventions", name: "section_structure", status: "warn",
         message: "#{bad_sections.size} intent file(s) have non-sanctioned ## sections",
         details: bad_sections.map { |b| "#{b[:dir]}: #{b[:issues].join(", ")}" },
-        fixable: false
+        fixable: true,
+        fix_hint: "Dispatch plastic-intent-curator to relocate each unsanctioned section into the " \
+                  "intent's revisions.md via move-and-record (a missing required section is restored " \
+                  "or reprojected instead); see PLASTIC.md > Structural maintenance and revisions.md"
       )
     end
 
@@ -698,7 +701,9 @@ class Doctor
     checks << graph_finding_check(
       "graph_i4_danglers", i4,
       "Every sources/chain id resolves to a real intent (I4)",
-      "Fix or remove the dangling id reference"
+      "Dispatch plastic-intent-curator to record the dangling sources/chain edge as a " \
+      "broken-source/broken-chain move-and-record entry in the intent's revisions.md (see " \
+      "PLASTIC.md > Structural maintenance and revisions.md), or restore the missing intent"
     )
     checks
   end

package/scripts/lib/installer_core.rb

@@ -236,6 +236,7 @@ class InstallerCore
       "templates/plan.md" => "templates/plan.md",
       "templates/checklist.md" => "templates/checklist.md",
       "templates/outcome.md" => "templates/outcome.md",
+      "templates/revisions.md" => "templates/revisions.md",
       "scripts/spawn-preamble" => "scripts/spawn-preamble",
       "scripts/lib/store_provisioning.rb" => "scripts/lib/store_provisioning.rb",
       "scripts/provision-project-store" => "scripts/provision-project-store",

package/skills/doctor/SKILL.md

@@ -119,9 +119,12 @@ Use the `fix_hint` value to determine the correct action:
 | "Inject the missing required frontmatter field(s)" | Edit the intent's `{ID}--{slug}.md` frontmatter to add the missing key (e.g. `chain: []`) without touching other keys |
 | "Run: provision-project-store {slug}" | Run `provision-project-store <slug>` (or invoke the `plastic-add-project-store` skill) to create the missing store |
 | "Re-run installer" | Run `npx @zalom/plastic@latest --agent` |
+| "Dispatch plastic-intent-curator ... revisions.md ..." | Invoke the `plastic-intent-curator` (or the agent) to relocate the flagged section or ref into the intent's `revisions.md` via move-and-record (one dated, `[rule: <tag>]`-tagged entry per item), per PLASTIC.md > Structural maintenance and revisions.md. For a missing required section, restore or reproject it instead. |
 
 For fixes the agent cannot handle automatically, explain what the user needs
-to do manually.
+to do manually. The `revisions.md` remedy is curator-applied (a move-and-record
+relocation, not a mechanical edit) and stays human-gated by the Step 4
+Fix / Select / Skip prompt.
 
 ### Step 6: Verify
 

package/templates/revisions.md

@@ -0,0 +1,58 @@
+# revisions.md
+
+<!--
+FORM reference. A live revisions.md exists in an intent directory ONLY when structural
+maintenance actually happened. It is never scaffolded at intent birth, it carries no
+placeholder sentinel, and its mere presence signals that this intent underwent structural
+(not conceptual) change.
+
+Rules:
+- Append-only. Newest entry at the BOTTOM. Never edit or reorder past entries.
+- One entry per relocated item (one section, one file, or one ref per entry).
+- Move-and-record: remove the misplaced thing from its artifact and preserve it IN FULL
+  here. Never rewrite, summarize, or reinterpret delivered meaning. A change to delivered
+  meaning is a new intent, not a revision.
+- Header form: "## Revision vN - YYYY-MM-DD-HH:MM" (N increments by one per entry).
+
+Fields:
+- Why:            one sentence naming the broken rule, ending with "[rule: <tag>]".
+- Prior location: the artifact plus the section or path the content came from.
+- Content held:   the verbatim removed content, as an indented block (block form), OR
+- Change:         a one-line "removed X (before: ... -> after: ...)" for a frontmatter
+                  edit, used instead of a Content held block.
+
+Stray file: embed the file's full content as the Content held block and delete the
+original; Prior location names the filename. revisions.md is the single container.
+
+Violation-tag catalog (starter set; free-text tags are 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
+
+The examples below show the three variants. Delete them when you write the first real
+entry; keep the "# revisions.md" title line above.
+-->
+
+## Revision v1 - 2026-06-30-14:35
+- Why: unsanctioned top-level section left over from an early draft [rule: unsanctioned-section]
+- Prior location: intent.md - ## Scope
+- Content held:
+
+  ## Scope
+  <the full content that was removed, verbatim>
+
+## Revision v2 - 2026-06-30-15:02
+- Why: chain edge to an intent that no longer exists [rule: broken-chain]
+- Prior location: intent.md frontmatter - chain
+- Change: removed "99x"  (before: ["4a1a", "99x"]  ->  after: ["4a1a"])
+
+## Revision v3 - 2026-06-30-15:20
+- Why: a stray notes file that does not belong in the intent directory [rule: stray-file]
+- Prior location: notes-old.md
+- Content held:
+
+  <the full content of notes-old.md, verbatim; the original file is then deleted>