fix(dw-demo-foldback): record "read X, did not reach Y" and an Instructions used line per step (5.8.5)

.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Claude skills for Dynamicweb 10 — organized by task domain, bundled by role.",
-    "version": "5.8.4"
+    "version": "5.8.5"
   },
   "plugins": [
     {

CHANGELOG.md

@@ -3,6 +3,16 @@
 All notable changes to the Dynamicweb Skills plugin are recorded here. The
 `version` field in `.claude-plugin/marketplace.json` tracks these entries.
 
+## [5.8.5]
+
+- **`dw-demo-foldback` "read X, did not reach Y".** When the dedup check finds the missed lesson
+  already recorded, the fold records which file the agent read at the step and where the rule lives,
+  classifies the miss as routing, and fixes the route (symptom-index row, pointer, `SKILL.md` routing)
+  instead of adding a second copy. A miss with no record of the files read is reported as unclassified.
+- **`dw-demo-base` `orchestrator.md` "Instructions used".** The progress artifact example gains a
+  per-step `instructions_used` map (the files and sections read before acting), the same record a
+  run journal keeps as an `Instructions used:` line on every step.
+
 ## [5.8.4]
 
 - **`dw-demo-pim` `canonical-setup-order.md` step 8:** the catalog-rebuild traps (relations that

manifest.json

@@ -1,6 +1,6 @@
 {
   "version": 2,
-  "generatedAt": "2026-09-29T10:42:24.932Z",
+  "generatedAt": "2026-09-29T10:44:22.221Z",
   "worksOn": {
     "dw": {
       "ring": "R1",

skills/dw-demo-base/references/orchestrator.md

@@ -97,10 +97,21 @@ rules plus one artifact:
      "slug": "<prospect-slug>",
      "flow": "dw-demo-base",
      "steps": { "setup-checks": "pass", "scaffold": "pass", "mcp-setup": "pending" },
-     "gates_passed": ["setup-checks", "scaffold"]
+     "gates_passed": ["setup-checks", "scaffold"],
+     "instructions_used": {
+       "setup-checks": ["dw-demo-base/references/setup-checks.md §1"],
+       "scaffold": ["dw-demo-base/references/scaffold.md §3"]
+     }
    }
    ```
 
+   **The instructions-used map is the step's "Instructions used:" line.** Record, per step, the skill
+   files and sections actually read before acting (not the ones that exist). A human-readable run
+   journal carries the same thing as an `Instructions used: <file> <section>` line on every step.
+   It is what lets a later fold-back tell a rule that is missing from one that was documented and
+   not reached ([`dw-demo-foldback` `fold-back-workflow.md`](../../dw-demo-foldback/references/fold-back-workflow.md)
+   Step 1b "Dedup check").
+
 This is the **same** `.demo/<slug>/` state the native command set uses — the native `state.json`
 is a superset that adds `phase` and `impact_signed_off`. Running by hand and later adopting the
 `/demo:*` commands or GSD does not throw the progress away; the heavier orchestrator reads the

skills/dw-demo-foldback/references/fold-back-workflow.md

@@ -156,6 +156,17 @@ lesson's key tokens. If a version of the lesson already exists:
 
 One lesson, one home. Restatements drift independently and become contradictions later.
 
+**The build missed a rule that was already there: record "read X, did not reach Y".** When the
+dedup check finds the lesson already recorded, the miss is a **routing** defect, not a content one,
+and the fold is different. Record which file (and section) the agent read at the failing step and
+where the rule actually lives: *read `scaffold.md` §3, did not reach `setup-checks.md` §1*. The fix
+then goes where the agent was: a symptom-index row, a one-line pointer in the file it did read, or
+a sharper routing sentence in the `SKILL.md`, never a second copy of the rule. A learning with no
+record of the files read at the step cannot tell "rule missing" from "rule not reached": say so in
+the PR and treat it as unclassified instead of adding content by default. The run's per-step
+"Instructions used" record ([`dw-demo-base` `orchestrator.md`](../../dw-demo-base/references/orchestrator.md)
+"Persist progress") is where that evidence comes from.
+
 ### 3. Integrate, don't append
 
 The default move for a fold-back is to **rewrite the existing sentence or section**, not to