@zalom/plastic 1.7.1 → 1.9.0

package/skills/doctor/SKILL.md

@@ -16,36 +16,67 @@ Doctor has three scopes. Pick the right one for the situation:
 | Store check | `--store [global\|<slug>]` | Dashboard load, `plastic-project-continuing` | Three-state: pass / warn / fail |
 | Full check | (no flag) | After every update (automatic), or `/plastic-doctor` | Three-state: pass / warn / fail |
 
-### `--core` (binary, manifest-backed)
+### `--core` (binary, operational-readiness only)
 
-Verifies that every core file is present and content-matches what the installed
-version shipped. It checks two install manifests:
+Checks ONLY that Plastic is loaded and ready for work: agent registration (skills,
+subagents, hooks/harnesses present and registered), core files (manifest-backed
+presence/hash checks, excluding `agent_model_drift`, which is a non-boot
+config-honoring check, never run at core), manifest sync (global + agent manifest
+SHA256), every registered project's path resolving to a real, existing directory,
+and the global store being reachable (`INDEX.md` present; no orphan/ghost content
+scanning). Result is binary: exit 0 on pass, non-zero on error. It never produces
+warnings, and it never scans store content.
+
+It checks two install manifests as part of core files and manifest sync:
 
 - `~/.plastic/manifest.json` (global manifest, covers PLASTIC.md and global scripts)
 - `~/.claude/plastic/manifest.json` (agent-side manifest, covers agent scripts and hooks)
 
-Each manifest maps a file path to its SHA256. The core check also confirms hooks
-are registered, scripts are present and executable, and the installed version
-matches. Result is binary: exit 0 on pass, non-zero on error. It never produces
-warnings.
+Each manifest maps a file path to its SHA256.
 
-### `--store [global|<slug>]`
+**On failure**, the report states this guided route, in order:
 
-Checks store state: intents are well-formed, INDEX sections are present, conventions
-are followed, and links are valid. Scope options:
+1. Run `plastic doctor --fix` (the Fix all / Select individually / Skip router from
+   Step 4-5 below).
+2. If that does not resolve it, roll back to the last known-good version via
+   `plastic-rollback` (restores from the local, append-only `versions.json` ledger of
+   versions actually run).
+3. Optionally report the issue via the feedback command (`scripts/feedback-report`,
+   backing the `plastic-feedback` skill), which composes a local report plus a
+   prefilled GitHub issue URL and never holds a credential or contacts GitHub
+   directly.
 
-- No argument: checks all stores (global and all projects)
-- `global`: checks only the global store
-- A project slug (e.g. `--store plastic`): checks only that project's store
+### `--store [global|<slug>]`
 
-Produces three-state results (pass / warn / fail) and is run per-scope at dashboard
-load time: the global board uses `--store global`, a project board uses `--store <slug>`.
+Checks the operations Plastic itself depends on in one store: QMD search reachability (scoped
+to that store's own collection; global uses `plastic-global`, a project slug uses
+`plastic-<slug>`), sources/chain resolution, cross-store resolution, INDEX parsing, and links
+projection. A project slug also checks tool readiness (Serena, Enola): each is a pass whether
+present or absent, present naming it available, absent noting it as an optional integration
+never installed by doctor. Scope options:
+
+- No argument (`:all`): checks all stores (global and all project stores), QMD reachability
+  unscoped across every collection.
+- `global`: checks only the global store, QMD scoped to `plastic-global`, no tool-readiness
+  checks (code-navigation tools have no meaning against the global store).
+- A project slug (e.g. `--store plastic`): checks only that project's store, QMD scoped to
+  `plastic-<slug>`, plus Serena/Enola readiness for that project.
+
+Produces three-state results (pass / warn / fail) and is run per-scope at dashboard load time:
+the global board uses `--store global`, a project board uses `--store <slug>`. **This IS the
+load-time full project check** named by 219's doctrine: no separate mechanism exists or is
+needed, since a project slug's scan already carries every per-project finding scoped to that
+project alone.
 
 ### Full doctor (no flag)
 
-Runs core plus all store checks plus deprecation checks. This is what `/plastic-doctor`
-invokes. It also runs automatically after every `plastic-update` (informational,
-does not block or revert the update).
+Runs the install-wide surface: agent registration, core files (including config-honoring
+drift), manifest sync is core-only and not part of this run, deprecation checks, config-ask
+checks, install-integrity checks, skill-lint (advisory), QMD reachability (unscoped, every
+collection), and the global store's own conventions/done-signals content. **Never carries a
+per-project finding**; that is `--store <slug>`'s job (see above). This is what
+`/plastic-doctor` invokes, and it also runs automatically after every `plastic-update`
+(informational, does not block or revert the update).
 
 ## When to Use
 
@@ -54,6 +85,10 @@ does not block or revert the update).
 - When hooks aren't firing, skills aren't loading, or something seems broken
 - When the user says "check plastic", "diagnose", "what's wrong with plastic"
 
+Read `../plastic-conventions/references/gates-and-enforcement.md` for the transition-gate
+mechanics, the audited escape, and gate logging before diagnosing a stuck or misbehaving gate.
+This path resolves relative to this skill's own installed directory.
+
 ## Procedure
 
 ### Step 1: Run the diagnostic script
@@ -125,7 +160,8 @@ 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-store-provisioning` skill) to create the missing store |
 | "Re-run installer" | Run `npx -y @zalom/plastic@<channel> install --agent <agent>` (channel: -alpha->@alpha, -beta->@beta, else @latest) |
-| "Dispatch plastic-store-curating ... revisions.md ..." | Invoke the `plastic-store-curating` (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. |
+| "Run the Plastic installer to bootstrap the store" | Run `npx -y @zalom/plastic@<channel> install --agent <agent>` (channel: -alpha->@alpha, -beta->@beta, else @latest) to restore the global store's plastic_home directory or INDEX.md |
+| "Dispatch plastic-store-curating ... revisions.md ..." | Invoke the `plastic-store-curating` (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-conventions > references/maintenance-and-revisions.md. For a missing required section, restore or reproject it instead. |
 | "Run scripts/project-links ... PRESERVES ... --drop-unbacked-links" | Run `ruby ~/.plastic/scripts/maintenance-run --tool project-links --intent <id> --apply` for the one flagged id (never run bare `project-links` against a real store outside the rare owner-approved batch exception, D2) |
 
 For fixes the agent cannot handle automatically, explain what the user needs
@@ -133,6 +169,10 @@ 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.
 
+Read `../plastic-conventions/references/maintenance-and-revisions.md` for WORK versus
+MAINTENANCE, the `revisions.md` move-and-record contract, and the violation-tag catalog behind
+the `revisions.md` remedy above.
+
 ### Step 6: Verify
 
 After applying fixes, re-run the diagnostic script:

package/skills/intent-brainstorming/SKILL.md

@@ -106,6 +106,10 @@ Do not author spec.md here.
 - **Produces:** the enriched Why (`## Context`, `### Decisions`, one `## Insights` entry per ruling).
 - **Next:** /plastic-intent-speccing consolidates the enriched Why into spec.md.
 
+Read `../plastic-conventions/references/lifecycle-and-savepoints.md` for the subagent
+report-home contract this handoff relies on. This path resolves relative to this skill's own
+installed directory.
+
 ## Key Principles
 
 - **One question at a time** - Don't overwhelm with multiple questions

package/skills/intent-continuing/SKILL.md

@@ -47,6 +47,10 @@ scanning the store with grep/Read run `ruby ~/.plastic/scripts/qmd-sync search "
 surface the candidate intent, then open the authoritative intent file for the hit you resume. The
 command is a no-op when QMD is absent, so fall back to the existing INDEX.md / file scan.
 
+Read `../plastic-conventions/references/lifecycle-and-savepoints.md` for the subagent
+report-home contract behind the resume below. This path resolves relative to this skill's own
+installed directory.
+
 For that intent's directory:
 
 1. **Read `savepoint.md` FIRST (intent 81).** It is a deterministic, append-only ledger

package/skills/intent-creating/SKILL.md

@@ -71,8 +71,9 @@ Having a "parent" in mind does NOT automatically mean branch. Choose by meaning:
 
 When a branch intent exists because a late ruling arrived AFTER its parent was already
 completed (the owner's late-ruling rule), the parent is restored to v1 via
-`scripts/restore-intent-v1`, never by a hand-run `git checkout`/revert. See `PLASTIC.md` >
-Terminal immutability for the rule and the tool.
+`scripts/restore-intent-v1`, never by a hand-run `git checkout`/revert. See
+`plastic-conventions > references/maintenance-and-revisions.md`, WORK vs MAINTENANCE, for the
+rule and the tool.
 
 `## Links` is a DERIVED view of `sources`/`chain`. Never hand-write a `## Links` line; add the
 frontmatter edge and reproject. Links are decided by context influence (a `chain` edge has a high
@@ -80,6 +81,10 @@ bar: the candidate's context must materially help deliver this intent), not by s
 similarity score. To gather candidates with their context and record an edge, use the
 `plastic-intent-linking` skill and `scripts/link-suggest`.
 
+Read `../plastic-conventions/references/knowledge-graph.md` for the full linking doctrine: the
+tiers of influence, sources versus chain, and how the `## Links` projection is derived. This path
+resolves relative to this skill's own installed directory.
+
 ### 3. Determine Intent Properties
 
 Ask or infer from context:

package/skills/intent-ending/SKILL.md

@@ -15,6 +15,10 @@ curator path, and releasing all call this skill (or its backing script,
 prose three times. `abandoned` is the SAME procedure as `delivered`, not a
 failure branch: only outcome.md content and the INDEX section differ.
 
+Read `../plastic-conventions/references/completion-and-done.md` for what "intent done" means and
+the End-stage tail behind the steps below. This path resolves relative to this skill's own
+installed directory.
+
 ## The 8 steps (0-7)
 
 | # | Step | Who does it |
@@ -52,9 +56,18 @@ for orchestrator-owned or completion-tracking items.
    the gate.
 2. Confirm every acceptance criterion in spec.md is verifiable (tests pass,
    or the manual check described in its HOW line was actually run).
-3. If checklist.md still has an unchecked box, stop here. Finish it first
-   (tick it if the described work is actually done, or do the remaining
-   work); do not attempt outcome.md and fight the gate's deny.
+3. The structure gate (intent 222) now enforces this: `scripts/end-intent`
+   refuses with exit 6 and names the exact unchecked box (or any other
+   structural gap: intent-file validity, lifecycle-artifact presence,
+   `## Links` projection). On a refusal, fix via the OWNING tool, never a
+   hand edit of the check's own output:
+   - checklist/outcome content - finish it yourself, the same as before.
+   - links projection - `scripts/project-links --intent <id> --apply` via
+     `maintenance-run`.
+   - a savepoint issue - advisory only (WARN, never blocks): run
+     `plastic-intent-savepoint` to rebuild via `Bridge.rebuild_savepoint` if
+     you want it clean, but it never refuses the close on its own.
+   Then re-run `scripts/end-intent`.
 
 ### Step 1-5. Run `scripts/end-intent`
 
@@ -78,9 +91,10 @@ ruby ~/.plastic/scripts/end-intent \
   --index-note "<rich Completed/Abandoned entry description>"
 ```
 
-This does all of steps 1-5 in order: guards outcome.md (refuses a missing,
-still-placeholder, or wrong-disposition file with exit 2 and authors
-nothing), stamps the intent file's `## Outcome` section, moves the INDEX.md
+This does all of steps 1-5 in order: guards outcome.md (a missing or
+still-placeholder file is caught by the structure gate first and exits 6; a
+wrong-disposition file exits 2; either way it authors nothing), stamps the
+intent file's `## Outcome` section, moves the INDEX.md
 line from `## Active` to `## Completed` or `## Abandoned` (dated today,
 idempotent, accepting either a real em dash or a plain hyphen as the id/
 title separator on read while always emitting the real em dash on write)

package/skills/intent-executing/SKILL.md

@@ -25,6 +25,10 @@ After syncing, verify the plan's target files exist at the paths plan.md names.
 If a named file or directory is missing (renamed or removed upstream), stop and
 report it rather than editing a stale path.
 
+Read `../plastic-conventions/references/locks-and-worktrees.md` for delivery isolation: the
+single-owner lock, claims, worktrees, solo mode, and the station ledger, before touching the
+worktree above. This path resolves relative to this skill's own installed directory.
+
 ## Mode Selection
 
 ### Check for superpowers first
@@ -138,6 +142,9 @@ the changed file, the installed output) rather than restating the intended
 change. Never present an unverified claim to the owner. If verification
 fails, fix it before the gate, not after.
 
+Read `../plastic-conventions/references/gates-and-enforcement.md` for the transition-gate
+mechanics, the audited escape, and gate logging behind every owner gate named here.
+
 ## Methods report (audits and sweeps)
 
 When the work is an audit or a sweep (checking many files or many instances of
@@ -166,6 +173,9 @@ persisting each ruling with `--stage Exec`.
 - **Produces:** code changes, a ticked checklist, and (for audits or sweeps) a methods report in `resources/`.
 - **Next:** intent-ending owns `outcome.md` (see intent 161). This skill's own Update-Intent-and-Complete step above is unchanged by this note.
 
+Read `../plastic-conventions/references/lifecycle-and-savepoints.md` for the subagent
+report-home contract this handoff relies on.
+
 ## Model Selection for Subagents
 
 Match model to task complexity:

package/skills/intent-linking/SKILL.md

@@ -26,6 +26,10 @@ Two distinct steps, do not conflate them:
 
 ## The three tiers (by context influence)
 
+Read `../plastic-conventions/references/knowledge-graph.md` for the full linking doctrine behind
+these tiers, the sources-versus-chain distinction, and the `## Links` projection. This path
+resolves relative to this skill's own installed directory.
+
 - **sources:** the foundational context that shaped this intent's CREATION (a split, an idea born
   during development, a merge). Earns an edge. Decided by origin, never inferred.
 - **chain:** the context that materially helps DELIVER this intent. HIGH bar: only the genuinely

package/skills/intent-locking/SKILL.md

@@ -12,6 +12,10 @@ session-keyed, liveness is a lease (the owner's hooks refresh the file mtime;
 stale means the heartbeat is older than the TTL). The /tmp bridge is only a
 cache; the lock file wins every disagreement.
 
+Read `../plastic-conventions/references/locks-and-worktrees.md` for delivery isolation in full:
+the single-owner lock, claims, worktrees, solo mode, and the station ledger behind every verb
+below. This path resolves relative to this skill's own installed directory.
+
 ## Verbs
 
 Run from the project (the intent resolves from this session's bridge), or pass

package/skills/intent-planning/SKILL.md

@@ -31,6 +31,10 @@ If the spec covers multiple independent subsystems, it should have been broken i
 
 ## Tier shapes
 
+Read `../plastic-conventions/references/tiers-and-dispatch.md` for tier sizing and the
+stage-to-agent dispatch rules behind this section. This path resolves relative to this skill's own
+installed directory.
+
 Read the spec's stamped `Tier:` line (written by intent-speccing) and pick the action shape it calls for. Every tier produces at least one REAL action file in `actions/`; the tier only changes how many:
 
 - **S or M (default):** write ONE consolidated `actions/ACTION_1.md` that carries the whole ordered delivery (the steps plus the exact changes). `plan.md` still holds the overall map and `checklist.md` still mirrors the task list. You may split into a few action files when that reads cleaner, but one real action file is the floor.
@@ -121,6 +125,9 @@ When collecting owner rulings for `[ORCHESTRATOR]` hard-gate items, read
 - **Produces:** `plan.md`, `checklist.md`, and at least one real `actions/ACTION_N.md` (every tier; one consolidated file at S/M, one per task at L).
 - **Next:** /plastic-intent-executing.
 
+Read `../plastic-conventions/references/lifecycle-and-savepoints.md` for the subagent
+report-home contract this handoff relies on.
+
 ## Git Commit
 
 After writing all artifacts (plan.md, checklist.md, and the actions/ACTION_N.md files), commit to the store:

package/skills/intent-savepoint/SKILL.md

@@ -22,6 +22,10 @@ It is **sugar on top of the conventions**, not a source of truth. The gate hook
 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).
 
+Read `../plastic-conventions/references/lifecycle-and-savepoints.md` for the subagent
+report-home contract that this ledger feeds. This path resolves relative to this skill's own
+installed directory.
+
 ## 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.

package/skills/intent-speccing/SKILL.md

@@ -47,6 +47,10 @@ not the Transition Gates table row). Writing `plan.md` is what opens the code ga
 writing `plan.md` is not this skill's job, that is `plastic-intent-planning`. State this to the user
 at step 6 so the handoff at step 8 is expected, not a surprise.
 
+Read `../plastic-conventions/references/lifecycle-and-savepoints.md` for the subagent
+report-home contract behind this handoff. This path resolves relative to this skill's own
+installed directory.
+
 ## Tier stamp (step 3, convention only)
 
 Write `Tier: S|M|L` as the literal first line of the file, above the `# Spec:` heading. This line

package/skills/intent-starting/SKILL.md

@@ -32,6 +32,10 @@ The lock is non-negotiable and comes before any mutating work. The ACTION-3 lock
 enforces it: without a held lock, mutating writes to this active intent's dir are denied with
 "run /plastic-intent-starting to lock and begin".
 
+Read `../plastic-conventions/references/locks-and-worktrees.md` for delivery isolation: the
+single-owner lock, claims, worktrees, solo mode, and the station ledger behind everything below.
+This path resolves relative to this skill's own installed directory.
+
 1. **Ensure the intent is in INDEX `## Active`.** If it sits in `## Future`, activate it
    (move it to `## Active`, auto-commit) before arming. Creation precedes activation, so a
    brand-new What intent is activated here, then locked.
@@ -106,12 +110,18 @@ Never re-ask at a later station.
 - **auto** → `arm_auto` (lock + auto), then hand off to `plastic-auto`. The auto branch's
   only remaining job is the handoff; `plastic-auto` runs the cycle from here.
 
+Read `../plastic-conventions/references/tiers-and-dispatch.md` for tier sizing and the
+stage-to-agent dispatch rules behind the auto branch above.
+
 ## Board at the latest delivered station
 
 The station is derived from `savepoint.md` last line + real artifacts on disk. See
 `references/boarding-matrix.md` for the full table (last line → latest delivered → boards at →
 continue with) and the per-station notes. Summary of what "continue" means per station:
 
+Read `../plastic-conventions/references/gates-and-enforcement.md` for the transition-gate
+mechanics, the audited escape, and gate logging that govern moving between the stations below.
+
 - **What** → do what What requires (106-expanded), then brainstorm → `spec.md`.
 - **Why** → continue brainstorming → `spec.md`.
 - **How** → continue `plan.md` + `actions/` + `checklist.md`.

package/skills/project-creating/references/project-scaffolding.md

@@ -17,8 +17,8 @@ Create `AGENTS.md` in the project root with:
 ```markdown
 # <Project Name> — Agent Instructions
 
-Read `PLASTIC.md` in `~/.plastic/`. It contains all Plastic conventions.
-Follow it exactly.
+Read `PLASTIC.md` in `~/.plastic/` for the core conventions; deeper doctrine lives in
+the `plastic-conventions` skill's chapters. Follow it exactly.
 
 This file is the operating contract for this project. Any agent entering
 this project reads this file first.

package/skills/roadmap/SKILL.md

@@ -43,6 +43,10 @@ See `references/file-format.md` for the exact entry-line shape, status vocabular
 format, and a worked example. See `references/operations.md` for step-by-step mechanics of each
 verb above.
 
+Read `../plastic-conventions/references/roadmaps.md` for the roadmap file format, batch
+semantics, and the status-mirror rule that this skill's own file-format reference builds on. This
+path resolves relative to this skill's own installed directory.
+
 ## Notes
 
 - File location and the four-section shape are identical across tiers; do not invent a different

package/skills/roadmap-continuing/SKILL.md

@@ -45,6 +45,10 @@ roadmap handoff had to be resumed by hand, carried as a free-prose note in `171`
 4. A genuine tie (two candidates equally live) is presented to the user and resolved by the
    single ask below, not silently picked.
 
+Read `../plastic-conventions/references/roadmaps.md` for the roadmap file format, batch
+semantics, and the status-mirror rule behind the candidates gathered above. This path resolves
+relative to this skill's own installed directory.
+
 ## Present state
 
 Present the chosen roadmap's `## Goal`, the current batch with each entry's mirrored status, the

package/skills/skill-creating/SKILL.md

@@ -49,6 +49,9 @@ routes each authoring task to the reference that holds the depth.
 | Deciding script versus prose, or writing a script | `references/scripts.md` |
 | Building evals for a skill | `references/evals.md` |
 
+Read `references/defaults-first.md` before naming an external skill as a default, for the
+Plastic-first, delegate-by-exception rule.
+
 ## Shrink context, or let a skill self-improve
 
 - When prompts or tool output blow the context budget, open `references/hooks.md` (E7) for

package/skills/skill-creating/references/defaults-first.md

@@ -0,0 +1,23 @@
+# Defaults First
+
+This chapter holds the Plastic-first, delegate-by-exception rule for naming an external skill as a default.
+
+### Defaults-First
+
+Plastic stands on its own. Skills and agents use Plastic's own defaults; an
+external skill (for example `superpowers:*`) is opt-in, never load-bearing.
+
+- **Default to Plastic, delegate by exception.** Name the Plastic-native path as
+  the default. Delegate to an external skill only when (a) it is available in the
+  harness, or (b) the user explicitly asks for it. A user without that plugin must
+  still get the core behavior.
+- **Phrase external skills as enhancements.** Write "use Plastic's native X by
+  default; if `superpowers:<skill>` is available, or the user prefers it, delegate
+  to it" never "delegate to `superpowers:<skill>`" as the only path.
+- **Optional dependencies detect then degrade.** `qmd` is the reference shape:
+  `scripts/lib/qmd_sync.rb` detects the binary first and every verb no-ops cleanly
+  when it is absent (see `scripts/qmd-sync`). Optional CLIs and MCP servers follow
+  the same detect-then-skip pattern, so a missing tool never crashes a session.
+- **Legitimate hard dependencies are exempt.** Ruby, Node, git, and POSIX tools are
+  the cost of running Plastic, not silent coupling. The principle targets accidental
+  dependence on external skills doing work Plastic should do itself.

package/skills/skill-creating/references/hooks.md

@@ -77,7 +77,10 @@ Notes that change the choice of event: [E2]
 - PreCompact fires before the runtime compacts the conversation. Use it to write a savepoint
   while the full context still exists.
 
-Plastic ships working instances of each: `scripts/hook-code-gate` (PreToolUse gate),
+Plastic ships working instances of each: `hooks/edit-gates` -> `scripts/hook-edit-gates`
+(PreToolUse, the merged dispatcher that runs code-gate, lock-gate, savepoint-pre, links-gate,
+and create-gate in one process; each gate's own logic lives in `scripts/lib/edit_gates.rb`
+and is also reachable through the standalone `scripts/hook-code-gate` CLI wrapper),
 `scripts/hook-session-start` (SessionStart boot and inject), `scripts/hook-savepoint-pre`
 (PreCompact savepoint). Read one before authoring a new hook of the same shape.
 

package/skills/store-curating/SKILL.md

@@ -39,6 +39,10 @@ The agent handles:
 - Cluster management (create, merge, rename)
 - Orphan detection
 
+Read `../plastic-conventions/references/knowledge-graph.md` for the linking doctrine: tiers of
+influence, sources versus chain, and the `## Links` projection, before judging a link discovery or
+orphan finding. This path resolves relative to this skill's own installed directory.
+
 When an intent reaches a terminal state, moved to Completed OR Abandoned, do these things:
 
 1. Author a real `outcome.md` in the intent directory from `~/.plastic/templates/outcome.md`, with the frontmatter `disposition: delivered` for a completed intent or `disposition: abandoned` for an abandoned one. `outcome.md` is MANDATORY at every terminal, delivered and abandoned alike: on abandon it records the abandonment reason and replaces the scaffolded placeholder sentinel (never leave `outcome.md` a placeholder at a terminal).
@@ -54,3 +58,7 @@ follows its own step 7: it detects (never acquires) the target's delivery lock,
 clean working tree, and performs the fix on a fresh branch merged back to main as one closed
 operation, with an append-only `revisions.md` receipt in the same pass as the edit. See
 `agents/plastic-intent-curator.md` for the exact mechanics.
+
+Read `../plastic-conventions/references/maintenance-and-revisions.md` for WORK versus
+MAINTENANCE, the `revisions.md` move-and-record contract, and the violation-tag catalog before
+running a maintenance dispatch like this one.

package/skills/store-indexing/SKILL.md

@@ -75,8 +75,16 @@ When 3+ intents share tags but aren't in a cluster, suggest a new cluster headin
 ### Flag Orphans
 Intents with no links (empty `sources`, empty `chain`, no `## Links` entries, not in any cluster) should be flagged for curation.
 
+Before reclassifying a structural finding outside routine indexing, read
+`../plastic-conventions/references/maintenance-and-revisions.md` for WORK versus MAINTENANCE, the
+`revisions.md` move-and-record contract, and the violation-tag catalog.
+
 REQUIRED BACKGROUND: intent-linking (for understanding connection types and Zettelkasten theory)
 
+Read `../plastic-conventions/references/knowledge-graph.md` for the linking doctrine: tiers of
+influence, sources versus chain, and the `## Links` projection. This path resolves relative to
+this skill's own installed directory.
+
 ## References
 
 - Read `references/zettelkasten-linking.md` for the three structural layers (Folgezettel, directed graph, tags) and how they map to INDEX.md organization

package/skills/tutorial/references/track-2-auto.md

@@ -56,10 +56,9 @@ Checkpoint: name one thing auto will always stop and ask about, rather than deci
 No new command. Auto still honors every hard gate a guided session would hit: the delivery
 lock (one owner at a time), the code gate (shut until `plan.md` and `checklist.md` exist),
 and the create gate (intents only come from the tool that makes them, never hand-authored).
-One gate, retrieval, is advisory only and never blocks anything; it just adds a note.
 
-Checkpoint: read one gate message from the run so far and say whether it is one of the hard
-gates or the one advisory note.
+Checkpoint: read one gate message from the run so far and name which of the three gates it
+came from.
 
 ### 4. Reading the per-stage reports
 

package/templates/agents.md

@@ -7,6 +7,14 @@
 
 You are working on this project as part of a strategic intent. Your governing intent is tracked in the global Plastic store at `~/.plastic/store/`.
 
+## Tools
+
+Plastic detects the tools it can use to work faster on this project: QMD (search this
+project's intent store instead of grep), and Serena or Enola (symbolic code navigation
+instead of grep). None is required. Whichever are present, their readiness is checked every
+time this project loads (`doctor --store <slug>`), so working through Plastic on this project
+means preferring a detected tool's own search or navigation over a generic file scan.
+
 ## How to Work
 
 1. **Check active tactical intents** in `.plastic/store/` — these are your current tasks