Mstar Compound Refresh

mstar-compound-refresh（知识维护）

Load order

Read mstar-harness-core first. Path symbols → mstar-conventions. On conflict, mstar-harness-core wins.

Purpose

Knowledge documents in {KNOWLEDGE_DIR} age. Code changes, conventions evolve, patterns become obsolete. mstar-compound-refresh audits the knowledge store against the current codebase and makes it trustworthy again.

产物与操作路径

SSOT: mstar-conventions/references/artifact-storage-paths.md。本 skill 仅操作 {HARNESS_DIR}/knowledge/**/*.md + {HARNESS_DIR}/knowledge/README.md（散文，见 Phase 4）+ <repo-root>/CONCEPTS.md + {HARNESS_DIR}/status.json（引用更新；v2 中知识引用挂在 workflow snapshot plan 行 metadata.knowledge_refs，见下）。禁止操作 docs/、{PLAN_DIR}/、{ITERATION_DIR}/、{SPECS_DIR}/。

Engine check (when available): run mstar compound validate <doc-path> --knowledge-dir <dir> (or import { scopeGuard, compoundRefreshScope } from "@mstar-harness/engine" in a host hook) to resolve the allowed scope above ({HARNESS_DIR}/knowledge/**, knowledge/README.md, <repo-root>/CONCEPTS.md, {HARNESS_DIR}/status.json) and guard every write against it. On fail -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.

When to use

Bootstrap vs refresh

Read the bootstrap reference on demand; do not paste its body into this SKILL.md.

Maintenance outcomes

For each candidate document, classify into one of five outcomes:

Guardrail — rejected approaches: a captured rejected approach stays only while the losing idea remains a tempting, meaningful mistake; delete it once obsolete or no longer plausible. Calibration: first real run of this axis — 9 size-divergent knowledge docs (36–78 lines) under {KNOWLEDGE_DIR}/architecture-patterns/ classified at fold time, all kept by future value (evidence: the knowledge-prose-folds plan ## Review Gate Summary → Task evidence); length proved not to be a criterion.

Core rules

1. Evidence over opinion. Signals are inputs, not a scorecard. Use engineering judgment.
2. Prefer no-write Keep. Do not update a doc just to leave a review breadcrumb.
3. Match docs to reality. When code differs from doc, update the doc — not ask whether the code change was "intentional."
4. Be decisive. When evidence is clear (file renamed, class moved), apply. Only ask PM when genuinely ambiguous.
5. Avoid low-value churn. Don't edit for typos, polish, or cosmetic changes that don't improve accuracy.
6. Delete, don't archive — except formal iteration-start §1.6 corpus hygiene (mstar-iteration/references/iteration-corpus-hygiene.md), which moves superseded/redundant knowledge/specs to {HARNESS_DIR}/archived/knowledge|specs/. Outside that gate, git history is the archive; git log --diff-filter=D -- <path> finds deleted docs.

   Not adopted: frozen-archive seal machinery, Archived: triplets, or a verifier — they contradict rule 6 (delete, don't archive; git history is the archive); do not reintroduce.

7. Evaluate document-set design. Check whether two+ docs overlap and should be consolidated. Redundant docs silently drift apart.

Scope selection

Default: user-guided

1. Ask PM for scope: "All knowledge docs, a specific category, or a keyword?"
2. If category: narrow to {KNOWLEDGE_DIR}/<category>/.
3. If keyword: search frontmatter (module:, tags:, problem_type:) and filenames.

PM-directed: specific scope

PM provides a scope hint (directory name, filename, module name, or keyword). Match in this order:

1. Directory match under {KNOWLEDGE_DIR}/
2. Frontmatter field match
3. Filename match
4. Content search

Process

Phase 1: Inventory

1. List all .md files under {KNOWLEDGE_DIR}/ (excluding README.md and index files).
2. Read frontmatter of each candidate.
3. Group by category / module for impact clustering.

Phase 2: Assess per doc

For each doc, check:

1. Referenced code still exists? — grep for file paths, class names, function names mentioned.
2. Referenced conventions still match? — check against current AGENTS.md, CONCEPTS.md, lint configs.
3. Solution still the recommended approach? — has a newer pattern superseded it?
4. Overlap with other docs? — search for same module/tags to find duplicates.
5. Future decision value? — rationale / alternatives considered / negative guarantees / reintroduction conditions that would still guide a future change → Keep, regardless of length. A completed decision whose body has no future leverage left (one-off fix detail, superseded mechanics) enters the Delete candidate pool. Word count and age remain discovery aids, never criteria.

Phase 3: Classify and act

Classify each doc → Keep / Update / Consolidate / Replace / Delete. Apply changes.

Phase 4: Reconcile the catalog

1. For every doc whose verdict changed its metadata or lifecycle (Update / Consolidate / Replace / Delete), update its catalog row: mstar catalog update for title/description/path/source hash and for the catalog lifecycle (active / archived / superseded), and mstar catalog link for provenance/supersession relations (identity is never patched; the revision guard is in --help). A doc deleted outside the iteration-start §1.6 archive gate leaves git history as its record — set/keep its catalog lifecycle so the row is not a silent dangling claim.
2. A knowledge body with no catalog row is a completeness gap, not a pass: register it (mstar catalog register, or reviewed mstar catalog discover + mstar catalog import) or report it. {KNOWLEDGE_DIR}/README.md index tables are not maintained as a register — README is prose.
3. If a doc was linked from knowledge refs (workflow snapshot plan row metadata.knowledge_refs / v1 root status.json metadata), update the references.

Phase 5: Report

Produce a maintenance report:

• Docs reviewed (count)
• Docs kept (count)
• Docs updated (list with what changed)
• Docs consolidated (list with which canonical doc merged into)
• Docs replaced (list with successor path)
• Docs deleted (list with reason)
• Docs flagged for PM review (ambiguous cases)

Phase 6: CONCEPTS.md reconciliation

If CONCEPTS.md exists, reconcile it with the refreshed knowledge:

• Terms mentioned in updated/replaced docs may need updating in CONCEPTS.md
• Terms no longer referenced may be candidates for removal

If CONCEPTS.md doesn't exist but knowledge docs contain qualifying domain terms, propose bootstrapping it (full repo-wide seed). Use references/concepts-vocabulary.md from mstar-compound for rules (read on demand — cross-skill path resolution via skill directory).

Cross-skill coordination

mstar-compound-refresh reads vocabulary rules from mstar-compound's references. At runtime, resolve the path from the loaded skill directory:

The CONCEPTS.md vocabulary rules are in the mstar-compound skill at:
references/concepts-vocabulary.md
Read that file from the mstar-compound skill directory before Phase 6.

NOT to do

• Do not delete docs without checking for inbound links
• Do not "archive" — delete instead
• Do not ask PM about mechanical updates (path fixes, renamed modules)
• Do not change code to match outdated docs — update docs to match code
• Do not run without PM approval for destructive actions (Delete, Replace)

Evidence

正确结果 = 每篇候选文档有明确 verdict（Keep / Update / Consolidate / Replace / Delete）并落到产物：文档改动 + catalog 行对账（Phase 4：mstar catalog update / register，生命周期 active / archived / superseded）+ 知识引用同步（workflow snapshot plan 行 knowledge_refs；v1 根 status.json legacy 引用） + 维护报告（Phase 5：reviewed / kept / updated / consolidated / replaced / deleted / flagged）+ CONCEPTS.md 对账（Phase 6）。

References

• 捕获侧规则与 CONCEPTS.md vocabulary 规则 → mstar-compound（Phase 6 前读 references/concepts-vocabulary.md）
• 路径符号与产物存储 SSOT → mstar-conventions（references/artifact-storage-paths.md）