Document autonomous memory curation workflow

codex-plugin/skills/architecture-overview/SKILL.md

@@ -17,6 +17,7 @@ This skill **maps structure**. Its companion `tracedecay:code-health-report` **s
 ## Guardrails
 
 - All tools here are read-only and parallel-safe. This skill maps and explains; it does not edit and it does not rank tech debt.
+- For broad repo maps, dispatch scoped read-only subagents by top-level directory, layer, or dependency question. Each subagent reports only cited TraceDecay findings; the parent agent owns the final architecture synthesis.
 
 ## Output
 

codex-plugin/skills/assessing-test-coverage/SKILL.md

@@ -17,6 +17,7 @@ Read-only coverage intelligence from the graph (structural test↔source edges,
 ## Guardrails
 
 - All read-only and parallel-safe; nothing here executes tests. Coverage is structural (call/use edges), so integration tests that reach code indirectly (through a binary, fixture, or IO boundary) can be missed — an empty `test_map` is strong but not absolute evidence of "untested".
+- For many targets or changed paths, use scoped read-only subagents per file group, package, or risk bucket. Require each subagent to return the exact target, TraceDecay coverage tools used, affected tests, and uncertainty; the parent agent chooses the final recommendation.
 
 ## Output
 

codex-plugin/skills/code-health-report/SKILL.md

@@ -23,6 +23,7 @@ Quality-scorecard companion to `tracedecay:architecture-overview` (which maps st
 ## Guardrails
 
 - Discovery/analysis tools are read-only and parallel-safe. `tracedecay_session_start` / `tracedecay_session_end` write/remove `.tracedecay/session_baseline.json`; use them only when a before/after delta is relevant and respect Cursor approval/run-mode.
+- For large audits, use scoped read-only subagents by path, weak health dimension, or requested scan. Keep any `tracedecay_session_start` / `tracedecay_session_end` calls in the parent agent; subagents only gather cited analysis.
 - `tracedecay_redundancy` is computed lazily and cached; the first call on a fresh index can be slow on large repos — keep `path`/`max_pairs` tight.
 - This skill reports and prioritizes; it does not edit. To fix findings, hand off to `tracedecay:atomic-code-edits` / `tracedecay:cleaning-up-dead-code`; to verify, `tracedecay:running-impacted-tests`. For a focused ship-readiness sweep (panic sites, risk markers, dead code, untested high-risk symbols) use `tracedecay:auditing-code-safety` instead of the full scorecard.
 

codex-plugin/skills/curating-project-memory/SKILL.md

@@ -5,27 +5,67 @@ description: 'Use when reviewing, updating, merging, deleting, pruning, or repai
 
 # Curating project memory
 
-This skill owns memory lifecycle changes. For read-only recall, start with `tracedecay:recalling-project-memory`. To add a researched subject from scratch, use the research-then-`add` flow in the Handoff section.
+Destructive curation is a parent-agent responsibility. Use subagents only for scoped inspection or recommendation work, with explicit project selectors and non-overlapping ownership; do not delegate delete/apply/merge/retention actions to subagents. TraceDecay should progressively expose registered-project selectors in its own MCP and CLI surfaces, so this skill documents the workflow rather than being the sole routing mechanism.
+
+This skill owns memory lifecycle changes. For read-only recall, start with `tracedecay:recalling-project-memory`. For autonomous curation, begin read-only, gather evidence, propose a mutation plan, then write only narrow durable changes. The installed Codex plugin ships this skill as the required operator runbook, so follow the workflow below without depending on external `docs/` files.
 
 ## Workflow
 
-1. **Start read-only:** `tracedecay_fact_store` with `action: "search"`, `"list"`, `"probe"`, `"related"`, `"reason"`, or `"contradict"`; use `tracedecay_memory_status` when the user asks for memory counts/health; use `tracedecay_dashboard` (`action: "start"`) when they want visual curation.
-2. **Classify the change:** update stale content/trust/tags, remove confirmed duplicates or wrong facts, or record `tracedecay_fact_feedback` only when the user rates a fact that was actually used.
-3. **Confirm destructive actions:** before `action: "remove"`, show the fact id, content/source, and reason, unless the user already named the exact fact to delete.
-4. **Apply narrowly:** `tracedecay_fact_store` `action: "update"` / `"remove"` / `"add"` only for the approved fact set. Re-run a read-only search/list to verify the final state.
+1. **Resolve scope:** confirm the active project root/store before touching memory. Project-bound profiles use the user-level TraceDecay store scoped to the current project by default.
+2. **Start read-mostly:** use TraceDecay MCP context/search first for code/session orientation, then `tracedecay_fact_store` with `action: "get"`, `"contradict"`, `"search"`, `"list"`, `"probe"`, `"related"`, or `"reason"`; note that search/list/probe/related/reason may update retrieval/access metadata. Use `tracedecay_memory_status` only when the user asks for memory counts/health because it may repair vectors/banks. Use `tracedecay_dashboard` (`action: "start"`) only when they want visual curation.
+3. **Run native dry-run:** prefer `tracedecay memory curate` or `POST /api/plugins/holographic/curate` with `{"dry_run": true}`. Dry-run is the default and returns `actions`, `hygiene_candidates`, `counts`, `coverage`, `provider`, and `mode`.
+4. **Inventory candidates:** group facts into add, update, merge/dedupe, stale, contradiction, secret-like, transient, supersession, and possible hard-delete buckets. Keep fact ids, source/provenance, trust, tags, entities, evidence links, and counterevidence with each candidate.
+5. **Research gaps:** use TraceDecay graph/search plus LCM/session/message tools to mine past sessions, raw messages, summary DAGs, branch/PR context, docs, and tests. For multi-step evidence gathering, scoped subagents may research bounded read-only questions only; the parent agent is the sole memory writer and must review raw findings before trusting them.
+6. **Propose changes:** summarize durable additions, stale-fact updates, trust/tag/source changes, dedupe merges, and delete candidates. Prefer update/merge over removal when useful provenance should survive.
+7. **Apply narrowly:** add/update only facts supported by evidence. Use `/curate/apply` or `tracedecay memory curate --llm-ops <file> --apply` only for reviewed operations. Require explicit approval immediately before every `action: "remove"`, dashboard hard delete, or merge loser removal, showing fact id, content/source summary, reason, and permanent-delete warning.
+8. **Verify read-only:** re-run search/list/probe/related/contradict/get as appropriate, inspect apply results/oplog when used, and report final facts changed, skipped, or still needing human judgment.
 
 ## Guardrails
 
-- Search/list/probe/related/reason/contradict are read-only. Add/update/remove, feedback, memory status repair, and dashboard start/stop mutate state or launch a local process; respect Cursor approval/run-mode.
-- Deletion is permanent: there is no archive, soft-delete, restore, or undo path. Prefer update/merge when useful provenance should survive; delete only confirmed stale, duplicate, wrong, secret-like, or user-requested facts.
+- `get` and `contradict` are non-destructive recall. Search/list/probe/related/reason are read-mostly but can update access/retrieval counters. Add/update/remove, feedback, memory status repair, and dashboard start/stop mutate state or launch a local process; respect host approval/run-mode.
+- Deletion is permanent: there is no archive, soft-delete, restore, or undo path. Prefer update/merge when useful provenance should survive; delete only approved stale, duplicate, wrong, secret-like, or user-requested facts.
 - Never store secrets, credentials, API keys, or PII. Do not lower trust merely because a fact is old; cite the newer evidence or contradiction.
-- Dashboard curation can apply hard deletes. Use preview/dry-run first when available and surface high-risk delete/merge operations before applying them.
+- Dashboard curation can apply hard deletes. Use preview/dry-run first when available and surface high-risk delete/merge operations before applying them. `POST /api/plugins/holographic/curate` with `dry_run=false` applies deterministic duplicate deletion; `/curate/apply` applies explicit delete/merge ops.
+- Do not let subagents call add/update/remove/feedback tools, apply curation ops, start dashboard mutation flows, or run memory health repair. Ask them for cited evidence, candidate facts, suspected duplicates, and stale/conflicting claims, then perform parent-agent validation before writing.
+- Default autonomous grooming output is report-only. If a tool or dashboard action mutates unexpectedly, disclose it and verify state before continuing.
+- Hygiene candidates (`secret_like`, `transient`, `supersession`) are review evidence, not deterministic apply operations.
+- External LLM plans must use strict JSON `{"ops": [...]}` and pass through the TraceDecay evidence guard; rejected low-confidence or out-of-scope ops must stay skipped.
+
+## Dry-run report
+
+Before any mutation, produce a compact report with these sections:
+
+- `scope`: project root/store, tool/API used, dry-run timestamp, and whether memory health repair or dashboard start/stop was invoked.
+- `native_plan`: `mode`, `provider`, `coverage`, `counts`, action count, and hygiene-candidate counts from `tracedecay memory curate` or `/curate`.
+- `adds`: candidate durable facts with source spans, category, entities, trust, and duplicate-search result.
+- `updates`: fact ids, old/new summary, evidence, confidence, and why update beats add.
+- `merges`: winner/loser ids, similarity evidence, retained provenance, optional `merged_content`, and why separate facts are redundant.
+- `deletes`: fact ids, content/source summary, permanent-delete reason, risk, surviving fact if any, and explicit approval status.
+- `skipped`: rejected transient, secret-like, unsupported, stale-but-uncertain, or duplicate candidates.
+- `verification_plan`: exact read-only checks to run after apply.
+
+Map native curation fields into those sections as follows:
+
+- `actions`: deterministic similarity-dedup delete proposals; list them under `deletes` unless operator review converts them into a safer `merge`.
+- `hygiene_candidates`: review-only evidence; list confirmed candidates under `deletes`, `updates`, or `merges`, and unconfirmed candidates under `skipped`.
+- `llm_review`: bounded external-review request; use `clusters`, `hygiene_candidates`, `allowed_fact_ids`, and `min_confidence` as evidence constraints.
+- `llm_apply`: validated external ops and rejected ops; list valid dry-run ops under `merges`/`deletes`, and rejected ops under `skipped`.
+
+## Memorize a subject
+
+Use only when the user explicitly asks to memorize or remember a subject, code area, branch, PR, or decision set.
+
+1. **Research read-only:** use TraceDecay graph/search, LCM/session/message tools, docs, existing fact searches, and relevant branch/PR context. Scoped research agents may gather evidence but the parent agent is the only memory writer.
+2. **Filter:** keep durable, scoped facts with citations. Reject secrets, credentials, PII, large code blobs, transient branch state, unsupported claims, and uncited speculation.
+3. **Calibrate trust:** use `0.85+` for independently verified decisions/observations, about `0.7` for ordinary well-sourced facts, and about `0.5` for plausible but uncertain facts. Do not ask for approval solely because trust is low.
+4. **Dedupe before writing:** search `tracedecay_fact_store` with the subject plus candidate, matching category, `limit: 10`, and `min_trust: 0.5`; skip near-duplicates and ask before replacing contradictory facts.
+5. **Store accepted facts:** propose the candidate set, then call `tracedecay_fact_store` `action: "add"` with content, category, source, tags, entities, trust, and metadata containing subject/confidence/citations.
+6. **Read add diffs:** act on `near_duplicate`, `possible_conflict`, and `rejected_secret_like`; never rephrase a rejected secret to bypass filtering.
 
 ## Handoff
 
-- Need to remember a new subject with research fan-out → research read-only first, dedupe via `tracedecay_fact_store` `action: "search"`, then store durable, cited facts with `action: "add"`; reject secrets, credentials, and PII.
-- Need raw session messages or summary-DAG replay → `tracedecay:recalling-session-context`.
-- Need only index/server status, not memory mutation → `tracedecay:project-status`.
+- Need raw session messages or summary-DAG replay -> `tracedecay:recalling-session-context`.
+- Need only index/server status, not memory mutation -> `tracedecay:project-status`.
 
 ## Output
 

codex-plugin/skills/exploring-types-and-traits/SKILL.md

@@ -20,6 +20,7 @@ Call-graph questions ("who calls X") belong in `tracedecay:tracing-functions`; t
 ## Guardrails
 
 - All read-only and parallel-safe. `tracedecay_constructors` is best-effort for Rust (ignores `match` arms and `if let` patterns); `tracedecay_field_sites` pattern-matches `.<field>` references, so same-named fields on other types can appear — prefer the `Struct::field` form to narrow. Unknown proc-macro derives surface with `well_known: false` (name only, no synthesized-method info).
+- For several independent type/trait questions, use scoped read-only subagents per type, trait, field, or implementor cluster. Require exact symbol ids/qualified names and tool evidence; the parent agent synthesizes the type-level answer.
 - This skill maps types; it does not edit. Hand renames/edits to `tracedecay:refactoring-safely` / `tracedecay:atomic-code-edits`.
 
 ## Output

codex-plugin/skills/finding-impacted-areas/SKILL.md

@@ -21,6 +21,7 @@ description: 'Use when estimating blast radius: what depends on a symbol or file
 
 - Read-only analysis. This skill identifies impact and the test set; it does **not** run tests.
 - Start with a shallow `max_depth` and widen only when the picture is incomplete.
+- For broad changes, use scoped read-only subagents per changed file group, target symbol, or subsystem. Subagents should return cited dependents, affected tests, and depth/tool parameters; the parent agent owns the final blast-radius and test-set synthesis.
 
 ## Handoff
 

codex-plugin/skills/recalling-project-memory/SKILL.md

@@ -5,6 +5,9 @@ description: 'Use when recalling prior decisions, durable facts, user/project pr
 
 # Recalling project memory
 
+Prefer TraceDecay-native registered-project selectors whenever a recall spans or targets a project other than the active checkout. Codex skill guidance may describe how to choose selectors, but selector support should live progressively in TraceDecay MCP and CLI tools themselves.
+
+
 Recall memory **before** reaching for external or web search — prior sessions often already answered the question, and a memory hit is cheaper and project-specific.
 
 ## Workflow

codex-plugin/skills/recalling-session-context/SKILL.md

@@ -18,6 +18,7 @@ Climb this ladder cheapest-first; stop as soon as the question is answered. For
 ## Guardrails
 
 - Steps 1–5 are read-only. `tracedecay_lcm_compress`, `tracedecay_lcm_preflight`, and `tracedecay_lcm_session_boundary` are **lifecycle-integration tools for host agents** — never invoke them casually during recall.
+- For multi-step recall, dispatch scoped read-only subagents by session id, time window, provider, role, or query variant. Subagents must not call lifecycle or repair tools; the parent agent validates cited messages/summaries and produces the final timeline.
 - If the LCM store itself looks wrong (missing sessions, broken FTS, stale counts) → `tracedecay_lcm_doctor` (`mode: "diagnose"` first; `repair`/`clean` mutate and need explicit user intent).
 - All LCM tools default to `storage_scope: "project_local"`; only pass `hermes_profile` (with an absolute `hermes_home`) when the user asks about a Hermes profile store.
 

codex-plugin/skills/reviewing-a-diff/SKILL.md

@@ -18,6 +18,7 @@ description: 'Use when reviewing a PR, branch diff, or working-tree diff for imp
 ## Guardrails
 
 - Read-only review. Do not edit or run tests from this skill; to verify behavior, hand off to the `tracedecay:running-impacted-tests` skill.
+- For large diffs, use scoped read-only subagents by file group, subsystem, or risk category. Require cited TraceDecay findings and changed paths; the parent agent owns severity, deduplication, and the final review call.
 - If diff context is truncated and includes a `handle`, narrow by file/symbol first when possible; call `tracedecay_retrieve` with that `handle` only when the omitted risk detail is needed.
 
 ## Output

codex-plugin/skills/searching-for-code/SKILL.md

@@ -7,6 +7,8 @@ description: 'Find code by concept, symbol, signature, or qualified name in this
 
 Use the TraceDecay code graph before Grep/Glob/file reads. Pick the cheapest tool that answers the question.
 
+For multi-step context gathering, use scoped read-only subagents when separate questions can run independently. Give each subagent one bounded target (symbol, path, feature, session, or branch), the TraceDecay tools it may use, and a strict "no writes / no edits / no memory mutations" instruction; the parent agent synthesizes findings and performs any follow-up actions.
+
 ## Workflow
 
 1. **Conceptual / "how does X work" / names unknown → `tracedecay_context`.**
@@ -26,6 +28,7 @@ Use the TraceDecay code graph before Grep/Glob/file reads. Pick the cheapest too
 - All tools above are read-only and parallel-safe. Do not call mutating/editing tools from this skill.
 - Only fall back to Grep/Glob/Read for non-indexed content (string literals, comments, config the graph does not cover) or after TraceDecay pinpoints exact files.
 - Prefer one well-formed `tracedecay_context` call over many narrow searches.
+- When using subagents, ask for cited file/symbol/session ids, tool names used, gaps/uncertainties, and any `tracedecay_metrics:` lines; do not accept uncited conclusions as evidence.
 - If a response is truncated and includes a `handle`, narrow the query/result set first when possible; call `tracedecay_retrieve` with that `handle` only when the omitted details are needed.
 - About to write a new helper because the search came up empty? Run the `tracedecay:finding-duplicate-logic` pre-write probe first.
 

codex-plugin/skills/tracing-functions/SKILL.md

@@ -18,6 +18,7 @@ description: 'Use when tracing call relationships: who calls a function, what it
 ## Guardrails
 
 - Read-only and parallel-safe. Keep `max_depth` small (1–2) first; widen only when the chain is not yet clear. `tracedecay_rename_preview` only previews references — it does not rename.
+- For several independent symbols or call paths, use scoped read-only subagents per symbol, direction, or path hypothesis. Require node ids, depth/tool parameters, and dispatch notes; the parent agent owns the final trace.
 - If a trace response is truncated and includes a `handle`, narrow depth or target set first when possible; call `tracedecay_retrieve` with that `handle` when the omitted chain details are needed.
 
 ## Output

cursor-plugin/skills/architecture-overview/SKILL.md

@@ -17,6 +17,7 @@ This skill **maps structure**. Its companion `tracedecay:code-health-report` **s
 ## Guardrails
 
 - All tools here are read-only and parallel-safe. This skill maps and explains; it does not edit and it does not rank tech debt.
+- For broad repo maps, dispatch scoped read-only subagents by top-level directory, layer, or dependency question. Each subagent reports only cited TraceDecay findings; the parent agent owns the final architecture synthesis.
 
 ## Output
 

cursor-plugin/skills/assessing-test-coverage/SKILL.md

@@ -17,6 +17,7 @@ Read-only coverage intelligence from the graph (structural test↔source edges,
 ## Guardrails
 
 - All read-only and parallel-safe; nothing here executes tests. Coverage is structural (call/use edges), so integration tests that reach code indirectly (through a binary, fixture, or IO boundary) can be missed — an empty `test_map` is strong but not absolute evidence of "untested".
+- For many targets or changed paths, use scoped read-only subagents per file group, package, or risk bucket. Require each subagent to return the exact target, TraceDecay coverage tools used, affected tests, and uncertainty; the parent agent chooses the final recommendation.
 
 ## Output