Refresh planning layer for backend fabric

docs/backend-fabric.md

@@ -75,6 +75,37 @@ The resulting `snapshot_id` is a stable hash over those identity fields. This
 lets future AST, JSONPath, FTS, SQL, vector, policy, and context-package
 backends invalidate derived data without guessing what changed.
 
+## Refresh Planning
+
+Before WP-0007 writes a local SQLite index, the backend fabric provides a
+read-only refresh planner. The planner compares current Markdown files with a
+portable snapshot-state inventory and reports:
+
+- unchanged files
+- files that need hashing
+- files that need parsing
+- files that need indexing
+- files that only need metadata updates
+- deleted sources
+- dependency-invalidated dependents
+
+The planner uses a cheap-first strategy:
+
+1. Compare path, size, mtime, parser version, parse options hash, and contract
+   hash.
+2. If cheap metadata is unchanged, skip hashing, parsing, and indexing.
+3. If metadata changed, either mark the file for hash/parse/index or, with
+   `--verify-hashes`, hash only those changed candidates to avoid parsing when
+   content is unchanged.
+4. Use dependency edges to invalidate direct and transitive dependents.
+
+This gives WP-0007 a performance contract before the storage engine exists.
+
+```bash
+mkt backend refresh-plan docs --state examples/backend-state/snapshot-state.yaml
+mkt backend refresh-plan docs --state .markitect/cache/snapshots.yaml --verify-hashes
+```
+
 ## Provenance Envelope
 
 The shared backend provenance envelope records:
@@ -113,6 +144,7 @@ Read-only inspection commands:
 mkt backend list --path examples/backends
 mkt backend inspect local-sqlite-cache --path examples/backends --require snapshots --require provenance
 mkt backend snapshot-id docs/content-references.md
+mkt backend refresh-plan docs --state examples/backend-state/snapshot-state.yaml
 ```
 
 The existing `mkt cache status` remains the lightweight file-manifest change

docs/workplan-planning-map.md

@@ -33,7 +33,7 @@ and descriptions mirror the operational view.
 | `MKTT-WP-0003` | complete | done | `MKTT-WP-0001`, `MKTT-WP-0002`, `MKTT-WP-0004` | Core toolkit implementation is complete. |
 | `MKTT-WP-0006` | complete | done | `MKTT-WP-0004`; task-level trigger: `MKTT-WP-0003-T005` | Optional backend fabric is complete: manifests, capabilities, snapshot identity, interfaces, registry, provenance, and read-only CLI scaffolding. |
 | `MKTT-WP-0010` | complete | done | `MKTT-WP-0004`; task-level trigger: `MKTT-WP-0003-T006` | Content references, processors, explode/implode, weave/tangle, content classes, and migration examples are complete as the first WP-0010 extension layer. |
-| `MKTT-WP-0007` | P2 | todo | `MKTT-WP-0006` | First practical cache backend use case: AST/JSONPath/SQLite/FTS. |
+| `MKTT-WP-0007` | P2 | todo | `MKTT-WP-0006` | First practical cache backend use case: AST/JSONPath/SQLite/FTS. Preliminary refresh planning is in place as the performance contract. |
 | `MKTT-WP-0005` | P2 | todo | `MKTT-WP-0003`, `MKTT-WP-0004` | Pick up when generation/form/context or semantic assessment pressure appears. |
 | `MKTT-WP-0011` | P2 | todo | `MKTT-WP-0003`; task-level triggers: `MKTT-WP-0010-T001`, `MKTT-WP-0010-T005` | Declarative Markdown dataflow workflows: source extraction, deterministic/assisted processing, and multi-output generation. |
 | `MKTT-WP-0009` | P2 | todo | `MKTT-WP-0006` | Establish access-control gateway before security-sensitive cache/context use. |