AGENT SKILL

vault-maintenance

暂无简介

License 许可
MIT
最近更新
2026-07-27
Stars
★ 0
Forks
0

02 资源文件 45

03 SKILL.md 正文

vault-maintenance

A periodic-sweep skill for ObsVault/. Each maintenance check runs as its own script + AI review pass, producing a human-readable summary in AgentOS/maintenance/. Invoked on demand — no fixed schedule (see 02_Design_Specs.md §21 and AgentOS/maintenance/future_steps.md's tiering and cadence notes).

This file is the entry point. Steps are documented as their own subsections below; new steps can be appended without restructuring existing ones.


Step 1: Link Verification

Script: scripts/link_check.js Spec: 02_Design_Specs.md §21

What it checks

  1. Broken wikilinks — [[links]] that don't resolve to an existing note.
  2. Missing required links — 200_execution/ notes missing a theory: link to a 100_concepts/ note (Rule 2), and 100_concepts/ notes of type: concept missing a derived_from field.
  3. Candidate links — pairs of notes with high embedding similarity (via Smart Connections' .smart-env/ data) that aren't yet linked.

Running the check

From AgentOS/skills/vault-maintenance/:

node scripts/link_check.js                  # incremental (default)
node scripts/link_check.js --mode=full      # full O(n²) sweep — "deep sweep"

Incremental (default): candidate-link discovery (check 3) only re-evaluates pairs where at least one note's mtime is newer than state.json's last_run. Checks 1–2 (broken links, missing required links) always run over the whole vault — they're linear scans, not affected by vault size the way pairwise similarity is.

Full (--mode=full): candidate-link discovery compares every pair of embedded notes, regardless of last_run — the "deep sweep" that catches old↔old pairs that have always existed but were never flagged. Run this periodically (cadence: manual, see AgentOS/maintenance/future_steps.md's tiering and cadence notes) — e.g. before a vault review session.

In both modes, pairs listed in state.json's dismissed_pairs are never re-flagged.

If state.json doesn't exist, every note is treated as "changed" — an incremental run is then equivalent to a full sweep.

This writes link_check_report.json (gitignored) to the vault-maintenance/ directory, with this shape:

{
  "mode": "incremental",
  "generated_at": "2026-06-11T18:30:00.000Z",
  "auto_fixes": [
    { "type": "broken-link", "file": "...", "old_target": "...", "new_target": "...", "raw": "...", "new_raw": "..." },
    { "type": "missing-theory-link", "file": "...", "added": "[[Concept]]" }
  ],
  "flagged": [
    { "type": "ambiguous-broken-link", "file": "...", "target": "...", "candidates": ["...", "..."] },
    { "type": "ambiguous-link-collision", "file": "...", "target": "...", "candidates": ["...", "..."] },
    { "type": "missing-theory-link", "file": "...", "reason": "..." },
    { "type": "needs-derived-from-review", "file": "..." },
    { "type": "candidate-link", "file_a": "...", "file_b": "...", "similarity": 0.81 }
  ],
  "skipped": [
    { "check": "candidate-link-discovery", "reason": ".smart-env/ not found" }
  ]
}

If skipped includes candidate-link-discovery, Smart Connections hasn't been enabled for ObsVault/ yet (a one-time manual setup step) — checks 1–2 still ran normally.

Review pass (AI)

  1. Apply each auto_fixes entry via the Edit tool:

    • broken-link: in file, replace the literal text raw with new_raw.
    • missing-theory-link: in file's frontmatter, set theory: ["<added>"] (or append <added> if theory: already has other entries — shouldn't happen for this fix type, since it only fires when theory: is empty).
  2. Resolve each flagged entry, per its type:

    • ambiguous-broken-link / ambiguous-link-collision: read file and each note in candidates; if one is clearly the intended target, fix the link as in broken-link above. If genuinely unclear, leave it and note it for the user in the summary.
    • missing-theory-link: read file; if a 100_concepts/ note is the obvious subject, add theory: ["[[<Concept>]]"]. Otherwise leave it for the user.
    • needs-derived-from-review: apply the 02_Design_Specs.md §10 objective/subjective test. If the note is interpretive/subjective and a source note can be identified, add derived_from: ["[[<Source>]]"]. If the note is objective/canonical, no action — absence is correct.
    • candidate-link: read both file_a and file_b. If the relationship is meaningful (not just topically adjacent), add a [[link]] between them in whichever note makes more sense contextually. Otherwise drop it.
  3. Write the summary to AgentOS/maintenance/link-verification_<YYYY-MM-DD>.md (sibling to ObsVault/, per 02_Design_Specs.md §3/§4 — agent output never lives inside the vault). Include: auto-fixes applied, flagged items resolved (and how), and any items left for the user's review.

  4. Update state.json:

    • Set last_run to the report's generated_at value.
    • For each candidate-link resolved by dropping it (not adding a link), append [file_a, file_b] (in the order given by the report) to dismissed_pairs, unless an equivalent pair (in either order) is already present.
    • This step always runs, even if no candidate-link items were dropped — last_run must advance so the next incremental run doesn't re-scan unchanged files.

Per 02_Design_Specs.md §8 (AI Authorship Boundary), all of the above is structural management — frontmatter, links, tags — which is in scope for AI to handle freely. Interpretive prose remains the user's.


Step 2: Card Ideation Pipeline

Scripts: scripts/flashcard_draft.js (sweep-side report), scripts/flashcard_push.js (manual push) Spec: 02_Design_Specs.md §23

Turns a concept note's identified cards (Stage A/B, the user's own work) into drafted Anki card prose (Stage C, AI). Consistent with the AI Authorship Boundary (02_Design_Specs.md §8): identifying what's worth testing and why is germane load (the user's); decomposing that into atomic, bidirectional card prose is extraneous load (AI's) — see §8 for the full germane/extraneous framing.

Stage A — Identification (the user, no artifact)

Self-interrogation checklist run against a written concept note — table in 02_Design_Specs.md §23.2. Surfaces which of the 7 archetypes (Definition, Notation, Theorem/Principle, Sequence, Hierarchy, Narrative Sequence, Cached Insight) and/or which modifier (Attribution, Distinction, Trigger→Concept, Case-Approach — §23.3) applies.

Stage B — Card Ideation (the user, permanent artifact)

Identification results get written into 150_card_ideation/<concept-slug>.md (template: 900_system/templates/Card Ideation.md) — one heading per archetype/modifier hit, terse, own words:

---
concept: "[[100_concepts/Dual Coding Theory|Dual Coding Theory]]"
status: draft        # draft -> reviewed -> pushed
---

## Definition
- verbal vs visual encoding channels — bidirectional

## Attribution
- Paivio, 1971 — foundational, worth citing (pairs with Definition)

## Cached Insight
- inferred: extraneous-load automation boundary generalizes to any
  admin-vs-interpretation split, not just note-taking

The concept: link must keep the 100_concepts/ folder prefix — an ideation note shares its concept note's basename by convention (this file above), so a bare [[Dual Coding Theory]] link is ambiguous in Obsidian (two notes, same basename, different folders) and may resolve to the ideation note itself rather than the concept note. The alias (|Dual Coding Theory) keeps the note's rendered/graph-view title clean despite the qualified target. flashcard_draft.js's resolver strips the prefix before matching against its 100_concepts/-only basename index, so don't "simplify" this to a bare basename — that's a regression, not a cleanup.

This note is permanent, not a buffer — it persists after its cards are pushed, as the standing record of why each card exists (unlike 000_inbox/ or review_queue.md, both cleared out once processed).

This note's existence is the trigger — there is no flashcard_ready checkbox. A concept is drafted once 150_card_ideation/<slug>.md exists and its mtime is newer than state.json's flashcards.last_run.

Running the draft (sweep-side)

From AgentOS/skills/vault-maintenance/, always run both commands together (never one without the other — the second depends on the first's freshly synced index when the semantic-duplicate check below runs):

node scripts/anki_similarity_sync.js   # refresh anki_embedding_index.json (§23.7)
node scripts/flashcard_draft.js

anki_similarity_sync.js keeps a local embedding index of the entire existing Anki collection fresh — incrementally: it re-embeds only notes whose AnkiConnect mod timestamp changed since the last sync, reusing cached vectors for everything else, and prunes notes no longer in the collection. Like the rest of this skill, it silently no-ops (leaves the index as-is) if AnkiConnect is unreachable — same "Prerequisite" pattern as "Pushing to Anki" below. First run downloads the embedding model's weights once (needs internet); every run after that is fully local/offline. Optional --dry-run prints stats without writing anything — useful as a first check against a real collection.

flashcard_draft.js itself scans 150_card_ideation/ for notes whose mtime is newer than state.json's flashcards.last_run, resolves each note's concept: frontmatter link back to its 100_concepts/ note, and writes flashcard_draft_report.json (gitignored):

{
  "generated_at": "2026-07-16T18:30:00.000Z",
  "drafted_notes": [
    {
      "note": "100_concepts/Dual Coding Theory.md",
      "ideation_note": "150_card_ideation/Dual Coding Theory.md",
      "domain_class": "other",
      "context_anchor": "Dual Coding Theory",
      "interactivity": "high",
      "derivation_heavy": false,
      "image_refs": [],
      "sequence": null,
      "declared_sections": ["Definition", "Attribution", "Cached Insight"],
      "unrecognized_headings": [],
      "stage_a_cross_check": [
        "high element-interactivity detected (dense links or comparison framing) but no Distinction/Trigger->Concept/Case-Approach modifier declared — confirm whether one applies (§23.3)."
      ]
    }
  ],
  "flagged": [
    { "type": "unresolved-concept-link", "note": "150_card_ideation/Typo.md", "reason": "..." },
    { "type": "empty-ideation-note", "note": "150_card_ideation/Blank.md", "reason": "..." },
    { "type": "unrecognized-heading", "note": "150_card_ideation/Loose.md", "headings": ["Random Thought"], "reason": "..." },
    { "type": "duplicate-heading", "note": "150_card_ideation/Messy.md", "headings": ["Definition"], "reason": "..." },
    { "type": "image-occlusion", "note": "100_concepts/Rankine.md", "image_refs": ["900_system/assets/diagram.png"], "reason": "..." }
  ],
  "skipped": []
}

This is drafted-state incremental: an ideation note is drafted once per edit; flashcards.last_run advances only after your review pass, so a note re-edited before review isn't re-drafted.

Card model

Two independent dimensions (§23.2/§23.4), plus modifiers layered on top (§23.3):

Archetype:  Definition | Notation | Theorem/Principle | Sequence
            | Hierarchy | Narrative Sequence | Cached Insight
Modifier:   Attribution | Distinction | Trigger->Concept | Case-Approach
Format:     Basic (Q&A) | Cloze

The user declares the archetype/modifier directly in the ideation note's section headings — this script no longer infers archetype from a cold concept note (retired: the old FAVORED_ARCHETYPES domain-routing table). What the script does still compute, per the user's decision to keep these as a secondary assist, not a gate:

  • domain_class / interactivity / derivation_heavy / sequence — the same mechanical detectors as before, now run against the concept note and folded into stage_a_cross_check: advisory notes flagging where the mechanical signal and the user's declared headings disagree (e.g. high interactivity with no Distinction/Trigger→Concept/Case-Approach declared, or a detected ordered list with no Sequence/Narrative Sequence declared). Never blocks drafting — read these, and either draft an additional card/modifier the cross-check surfaced, or note in the summary why it doesn't apply.
  • image_refs — unchanged, still routes to an image-occlusion flag (build manually in Anki).
  • declared_sections / unrecognized_headings — the ideation note's headings, checked against the §23.2/§23.3 vocabulary. An unrecognized heading isn't an error — it might be deliberate free-form scaffolding — but it's flagged so you can confirm it wasn't a typo (e.g. "Formula" no longer being separate from "Theorem/Principle").

Sequence/Narrative Sequence content-triggered guidance: length_mode (default "short") means one test-card (recite the whole sequence) + a small cloze set, one element at a time — not the full position/successor/predecessor matrix ("long" mode, still deferred; see AgentOS/reference/flashcard_examples/worked_examples.md's Sequence section or eudoxia0/spaced-repetition-tools if a note ever needs it).

Worked examples: before drafting any archetype/modifier for the first time in a session, check AgentOS/reference/flashcard_examples/worked_examples.md — anchoring examples for all 7 archetypes plus the 4 modifiers, showing the wrong (over-stuffed) version and the corrected breakdown where relevant. Match their shape, never their content (Law 7, Source Fidelity).

The ten Laws (binding when drafting any card)

  1. Context-Anchoring — every prompt names the parent framework/domain of the tested element (use the directive's context_anchor); never bare term→definition.
  2. Minimum Information / Atomicity — one fact/relation/step per card; no compound questions; no lists unless ≤3 items and the count is the fact.
  3. Element-Interactivity Routing — if interactivity: "high" (and the cross-check flags it), consider routing to the Distinction or Trigger→Concept modifier rather than a bare base archetype.
  4. Procedural-Step Fidelity — Case-Approach-modified cards reuse the step names/ordering from the note (or linked 200_execution/ notes) verbatim.
  5. Supportive-Info Linking — Definition/Theorem/Principle cards reference at least one related concept by name in prompt or answer.
  6. No-Orphan-Recall — a card shown out of order must still be answerable from its own content.
  7. Source Fidelity — paraphrase the ideation note + concept note's prose; introduce no new facts, examples, or framings. Cached Insight cards are the one exception that's still in-bounds: they restructure an inference the user already recorded in the ideation note, never one AI originates itself (§8).
  8. Whole-Task Exclusion — never draft a card whose answer is a multi-step derivation/proof/procedure. An ideation note with no declared archetype at all is flagged empty-ideation-note rather than drafted; a derivation-heavy concept note with some declared archetype still drafts those, per the user's own Stage A judgment call.
  9. Cueing Hygiene — no answer-leaking: avoid shared word-roots between prompt and answer, no true/false or "which of the following," no implicit-order enumerations.
  10. Bidirectionality — for Definition, Notation, and Distinction-modified cards, draft both directions (term→def, def→term) unless the reverse is trivially inferable from the term's surface form (e.g. "microglia are a kind of…?" when "micro-" already signals the answer). Default to drafting both; prune the obvious-reverse case with a one-line justification in the maintenance summary. See the Isomers example in worked_examples.md for the obviousness threshold in practice.

Stage C — AI Structuring / Stage D — Gap Flagging (review/draft pass)

  1. Read the ideation note named in each drafted_notes directive — not the concept note cold (§23.1). The concept note is still read for supporting prose/context, but the ideation note's headings are what determine which cards get drafted.
  2. Check the matching archetype/modifier's shape against AgentOS/reference/flashcard_examples/worked_examples.md; write 1-3 finished card entries per declared heading into AgentOS/skills/anki-flashcards/review_queue.md (append, format below), following the ten Laws. Before writing, re-check against Law 2 (Atomicity) and Law 9 (Cueing Hygiene) specifically. Skip Longform Candidate headings — a routing marker (§23), not an archetype/ modifier; never draft a card from one. It's Step 3's input instead (see below).
  3. Anki semantic-duplicate check (§23.7), per drafted card, before appending to the queue. Pipe this note's drafted card(s) as JSON to node scripts/anki_similarity_query.js via stdin ({"cards":[{"id":"...","front":"...","back":"..."}]}) and read the returned shortlist ({"results":[{"id":"...","shortlist":[...]}]}) from stdout. This is a cheap, recall-biased cosine-similarity pre-filter against the entire existing Anki collection (typically 0-5 candidates per card) — it is not the final verdict. For each shortlisted candidate, read both the drafted card and the candidate's Front/Back and judge whether they test the same underlying knowledge, even if worded differently, before flagging. Only write a > WARNING: line (format below) for candidates you confirm as true overlap. Drop cosine hits you judge to be false positives silently — don't record them anywhere; the point is reducing the user's review burden, not shifting noise from "under-checked" to "over-checked." This is additive to, not a replacement for, flashcard_push.js's existing exact-match/tag-match guards at push time.
  4. Work through stage_a_cross_check for the note (Stage D, gap flagging): for each advisory note, either draft the additional card/modifier it points at, or record in the maintenance summary why it doesn't apply. Never silently add a card the user didn't identify in Stage A/B, and never silently drop a cross-check note either — every one gets a visible resolution.
  5. For each flagged entry: append a ## [<note>] — FLAGGED block recording the reason (unresolved-concept-link, empty-ideation-note, unrecognized-heading, duplicate-heading, or image-occlusion). Never write a card for these. duplicate-heading is almost always leftover Card Ideation.md template scaffolding pasted alongside real content (e.g. a second empty ## Definition after the note already has real content under its first ## Definition) — merge the duplicate's content into the first occurrence (or delete it if empty) rather than just leaving it flagged. Leave the template's reference comment block alone — it's meant to persist as the user's own working reference, not get cleaned up.
  6. Tag each card entry with domain::sub_domain + a concept-slug (kebab-case of the tested element) and an Ideation: field pointing back at the ideation note (§23 — needed for the push-time status flip below).
  7. Flip the ideation note's frontmatter status: draft → status: reviewed (Edit tool) once its cards are written into the queue.
  8. Advance state: set state.json's flashcards.last_run to the report's generated_at value. Always runs, even if zero cards were drafted.
  9. Summary: note what was drafted/flagged/cross-checked in the maintenance summary (AgentOS/maintenance/), same as Step 1.

Queue entry format (one per ----delimited block):

## [100_concepts/Dual Coding Theory.md] — Definition (Basic)
**Front:** In Dual Coding Theory, what does the Redundancy Effect describe?
**Back:** ...
**Tags:** cognitive-science::dual-coding-theory, redundancy-effect
**Ideation:** 150_card_ideation/Dual Coding Theory.md
---

If step 3's semantic-duplicate check confirms overlap with an existing Anki note, append a > WARNING: line to the entry (same mechanism flashcard_push.js already uses for its own warnings — lib/queue.js serializes/strips it transparently):

## [100_concepts/Dual Coding Theory.md] — Definition (Basic)
**Front:** In Dual Coding Theory, what does the Redundancy Effect describe?
**Back:** ...
**Tags:** cognitive-science::dual-coding-theory, redundancy-effect
**Ideation:** 150_card_ideation/Dual Coding Theory.md
> WARNING: possible duplicate of existing Anki note 1690000000123 (deck: ObsVault) — Front: "..." — cosine similarity 0.81 — LLM-confirmed same underlying knowledge; review before pushing.
---

A Sequence note (length_mode: "short") yields a small block of its own — still one entry per ---, archetype labeled Sequence:

## [100_concepts/Taxonomic_Rank.md] — Sequence (Basic)
**Front:** In the taxonomic rank system, recite the four nested ranks from largest to smallest.
**Back:** Domain, kingdom, phylum, class.
**Tags:** biology::taxonomic-rank, taxonomic-rank-units
**Ideation:** 150_card_ideation/Taxonomic_Rank.md
---
## [100_concepts/Taxonomic_Rank.md] — Sequence (Cloze)
**Front:** In the taxonomic rank system, the largest rank is the {{c1::domain}}.
**Back:** ...
**Tags:** biology::taxonomic-rank, taxonomic-rank-units
**Ideation:** 150_card_ideation/Taxonomic_Rank.md
---

Math syntax — MathJax, not LaTeX dollar signs. Anki renders math via MathJax; it does not recognise bare $...$ / $$...$$ delimiters by default. Always use:

  • Inline math: \(...\) — e.g. \(A^k B\), \(\mathscr{C}\)
  • Block/display math: \[...\]

Pushing cards with $...$ produces raw-text fields that display as literal dollar-sign strings in Anki (confirmed 2026-06-26).

Code syntax — HTML tags, not markdown fences. flashcard_push.js copies Front/Back straight into Anki fields with no markdown-to-HTML conversion (buildNote(), scripts/flashcard_push.js), the same reason bare $...$ fails for math. Markdown code spans/fences render as literal backtick characters in Anki. Always use:

  • Inline code: <code>...</code> — e.g. <code>[x for x in range(10)]</code>
  • Multi-line snippets: <pre><code>...</code></pre>

Worked examples (this file, worked_examples.md) can keep ordinary markdown backticks for readability — only queue entries and pushed fields need the HTML form.

Anki semantic-duplicate index (§23.7)

anki_similarity_sync.js and anki_similarity_query.js (scripts/lib/anki_similarity.js) add a duplicate-knowledge check that's independent of and earlier than flashcard_push.js's existing exact-match/tag-match guards. It embeds Front/Back text with a local model (TaylorAI/bge-micro-v2, via @huggingface/transformers — no API key, no remote calls after the one-time model download) rather than doing exact-string or exact-tag matching, so it can catch a card that tests the same knowledge as an existing one but is worded differently.

  • anki_embedding_index.json (gitignored, lives in this skill's own directory — never in ObsVault/, per Hard Rule 2): { schema_version, model, notes: { "<noteId>": { mod, deck, front, back, vec } } }. Built and incrementally refreshed by anki_similarity_sync.js from AnkiConnect's notesInfo (per-note mod timestamp drives the reuse/re-embed decision) and cardsInfo (deck name — notesInfo doesn't return it). These two AnkiConnect actions are new alongside the already-documented findNotes/addNote.
  • Threshold (ANKI_SIMILARITY_THRESHOLD in lib/anki_similarity.js, currently 0.70): deliberately recall-biased — it's a pre-filter, not a verdict, since Stage C step 3 above absorbs the false-positive cost on a small shortlist. This is a reasoned starting guess, not an empirically measured number. After the first few real runs, spot-check shortlist sizes (target ballpark 0-5 per drafted card): lower the constant if a known-near-duplicate isn't surfacing, raise it if shortlists are frequently maxed out with obviously-irrelevant candidates.
  • Dependency: @huggingface/transformers is declared in this skill's package.json — run npm install in AgentOS/skills/vault-maintenance/ before first use.

Pushing to Anki (manual, on "push")

When the user says "push", run:

node scripts/flashcard_push.js

Prerequisite: Anki desktop + the AnkiConnect add-on must be running locally (like Step 1's Smart Connections dependency). If unreachable, the push reports skipped and changes nothing.

It parses remaining card entries (FLAGGED entries are skipped), and applies three duplicate guards: Layer 0 (generation-phase) — a card identical (same note + Front) to one already staged in this run is a drafting-overlap duplicate; it's warned and retained, never pushed twice. Layer 2 — findNotes tag:<concept-slug>; if matches exist in Anki, warns and leaves the entry in place with the warning appended (no add). Layer 1 — otherwise addNote to deck ObsVault with allowDuplicate: false, so Anki's own first-field guard rejects an exact existing duplicate. Pushed entries are removed from the queue; warned ones stay for the user to resolve.

Ideation status flip (§23, fully automated per the user's decision): the result object includes ideation_status: [{ ideation, status, remaining }] — one entry per ideation note referenced by any card processed this run. status: "pushed" means every one of its cards cleared the queue this run; status: "partial" means some remain (remaining count). For every "pushed" entry, flip that ideation note's frontmatter status: reviewed → status: pushed (Edit tool) — the script itself never writes into ObsVault/ (Hard Rule 2); it only computes which notes qualify.

Step 3: Long-Form Candidate Flagging

Script: scripts/longform_candidates.js Spec: AgentOS/reference/plans/spec_longform-practice_2026-07-17.md (FR-03–05), Phase 3 of the longform-practice roadmap.

What it checks

Scans 100_concepts/ and 200_execution/ for the composition discriminator — chains of procedures applied in an applied context (proof/ derivation/multi-step-problem signals), not difficulty or atomicity — that distinguish content unsuited to a flashcard from content that fits Anki fine. A note qualifies as a candidate if either:

  • detectDerivationHeavy (scripts/lib/flashcards.js, already used by Step 2 to keep derivations off cards) flags step/proof-chain signals in its body, or
  • it lives in 200_execution/ at all — that folder is worked derivations by definition (filename convention <theory>__<case>.md), so folder membership alone is a belt-and-suspenders candidate signal, independent of the mechanical heuristic.

Running the check

From AgentOS/skills/vault-maintenance/:

node scripts/longform_candidates.js

Incremental only (no full-sweep mode, unlike Step 1): only notes whose mtime is newer than state.json's longform_candidates.last_run are considered, same mechanism as Step 2's flashcards.last_run.

Each candidate is then checked against AgentOS/longform-practice/state/eligibility.json (FR-05's cache, keyed by note path): if a cached entry's note_updated_seen is >= the note's current updated frontmatter value, the note is not re-flagged (already reviewed, not stale) — it appears in skipped instead. Otherwise it's flagged.

Writes longform_candidates_report.json (gitignored) to the vault-maintenance/ directory:

{
  "generated_at": "2026-07-17T18:30:00.000Z",
  "flagged": [
    {
      "note": "100_concepts/Undetermined Coefficients.md",
      "reason": "derivation/proof step-chain signals detected in note body",
      "signals": { "derivation_heavy": true, "folder": "100_concepts", "ideation_declared": true }
    }
  ],
  "skipped": [
    {
      "type": "cached-eligibility",
      "note": "100_concepts/Some Other Concept.md",
      "reason": "reviewed_at 2026-07-11T12:00:00.000Z covers current updated: 2026-07-10"
    }
  ]
}

signals.ideation_declared (100_concepts/ candidates only — see below): whether the concept's sibling 150_card_ideation/<slug>.md already declares a ## Longform Candidate section. Computed by checking the ideation note for that heading (parseIdeationSections, scripts/lib/ flashcards.js — the same parser Step 2 uses), content untouched; the review pass reads the actual bullets itself. 200_execution/ notes have no 150_card_ideation/ sibling by convention (§23.1 — ideation notes scaffold concept notes only), so this signal is always false there and the review pass falls back to the live prompt below.

Review pass (AI) — the FR-04 propose/review exercise

This step is interactive, not a one-shot fix like Steps 1–2's auto-fixes. It's a declare-then-critique pass, same shape as Step 2's Stage A-D: The user proposes first (in writing, when they've already declared it, or live otherwise); the AI's job is to critique/refine that proposal against the note, never to originate it.

  1. For each flagged entry, get the user's proposal — branch on signals.ideation_declared:

    • true: read the concept's sibling 150_card_ideation/<slug>.md directly. Its ## Longform Candidate bullets are the proposal — top-level bullets are problem types, nested bullets are case-branches (template: 900_system/templates/Card Ideation.md). Skip the live prompt below.
    • false: prompt the user to propose the problem types that stem from this concept, including internal case-branches as explicit sub-items — e.g. undetermined-coefficients' root-overlap cases (no overlap / single-root overlap / double-root overlap) aren't a separate problem type, they're sub-items of one. This is the only path for 200_execution/ candidates (no ideation-note sibling exists for them) and for 100_concepts/ candidates that haven't declared one yet.
  2. Review the proposal against the note's own content for completeness and correctness before eligibility-tracking begins for that concept: does the note's worked example imply a case-branch the proposal omitted? Is every case-branch the note actually demonstrates accounted for? Flag gaps back to the user rather than silently accepting or silently filling them in yourself — FR-04 is a check, not an AI-authored proposal, whether the proposal came from the ideation note or a live answer.

  3. Once confirmed, write/update the note's entry in AgentOS/longform-practice/state/eligibility.json:

    {
      "100_concepts/Undetermined Coefficients.md": {
        "reviewed_at": "2026-07-17T18:30:00.000Z",
        "note_updated_seen": "2026-07-16",
        "status": "confirmed",
        "declared_via": "ideation-note",
        "problem_types": [
          {
            "type": "particular solution via undetermined coefficients",
            "cases": ["no overlap with homogeneous solution", "single root overlap", "double root overlap"]
          }
        ]
      }
    }
    

    note_updated_seen is the note's updated frontmatter value at review time — this is what FR-05's cache check compares against on the next scan, not the review timestamp itself. declared_via is "ideation-note" or "live-prompt", matching step 1's branch — kept for traceability, since provenance (who proposed what, and what the AI critique changed) is the point of a declare-then-critique flow.

  4. Update state.json: set longform_candidates.last_run to the report's generated_at value. Always runs, even if zero candidates were flagged this pass — advances the incremental scan the same way Steps 1–2 do.

  5. Write the summary to AgentOS/maintenance/longform-candidates_<YYYY-MM-DD>.md, same convention as Steps 1–2: which notes were flagged, whether each came from a written declaration or a live prompt, the confirmed problem types/case-branches for each, and anything left open for the user.

eligibility.json is longform-practice's own persisted cache (not a vault-maintenance report) — Phase 6 (session generation) reads it directly to know which problem types/cases a concept is confirmed eligible for, once its flashcards also clear Step 2's separate maturity gate (AgentOS/longform-practice/scripts/maturity_gate.js). The two gates are independent: candidate-flagging tracks what to practice, the maturity gate tracks whether it's unlocked yet — a concept can be a confirmed candidate long before its flashcards mature.

Future steps

Additional vault-maintenance checks (frontmatter compliance, domain-registry drift, orphan-note detection, etc.) and a fixed run schedule are deferred — see AgentOS/maintenance/future_steps.md's candidate-checks table. When added, give each its own ## Step N section above, following the same script + review-pass shape.

04 同仓库更多 Skills