vault-maintenance
暂无简介
- License 许可
- MIT
- 最近更新
- 2026-07-27
- Stars
- ★ 0
- Forks
- 0
02 资源文件 45
- 其他.gitignore123 B
- 参考文档package-lock.json37.4 KB
- 参考文档package.json333 B
- 脚本scripts/anki_similarity_query.js1.6 KB
- 脚本scripts/anki_similarity_sync.js2.0 KB
- 脚本scripts/flashcard_draft.js6.8 KB
- 脚本scripts/flashcard_push.js6.8 KB
- 脚本scripts/lib/anki_similarity.js6.1 KB
- 脚本scripts/lib/anki.js552 B
- 脚本scripts/lib/candidate_links.js2.4 KB
- 脚本scripts/lib/flashcards.js10.0 KB
- 脚本scripts/lib/frontmatter.js1.5 KB
- 脚本scripts/lib/queue.js3.7 KB
- 脚本scripts/lib/required_links.js2.4 KB
- 脚本scripts/lib/state.js3.4 KB
- 脚本scripts/lib/vault.js1.4 KB
- 脚本scripts/lib/wikilinks.js3.4 KB
- 脚本scripts/link_check.js2.8 KB
- 脚本scripts/longform_candidates.js5.4 KB
- 脚本scripts/tests/anki_similarity_query.test.js1.4 KB
- 脚本scripts/tests/anki_similarity_sync.test.js3.1 KB
- 脚本scripts/tests/anki_similarity.test.js7.2 KB
- 脚本scripts/tests/anki.test.js1.5 KB
- 脚本scripts/tests/candidate_links.test.js4.2 KB
- 脚本scripts/tests/fixtures/full_vault/000_inbox/note_with_links.md85 B
- 脚本scripts/tests/fixtures/full_vault/100_concepts/Partial Derivatives.md131 B
- 脚本scripts/tests/fixtures/full_vault/100_concepts/Separable Equations.md137 B
- 脚本scripts/tests/fixtures/full_vault/200_execution/orphan_case__weird.md94 B
- 脚本scripts/tests/fixtures/full_vault/200_execution/separable_equations__example_one.md93 B
- 脚本scripts/tests/fixtures/full_vault/900_system/templates/Capture - Reading.md140 B
- 脚本scripts/tests/fixtures/sample_vault/100_concepts/Separable Equations.md137 B
- 脚本scripts/tests/fixtures/sample_vault/200_execution/separable_equations__example_one.md93 B
- 脚本scripts/tests/fixtures/sample_vault/900_system/templates/Capture - Reading.md234 B
- 脚本scripts/tests/fixtures/smart_env/multi/sample.ajson315 B
- 脚本scripts/tests/flashcard_draft.test.js9.0 KB
- 脚本scripts/tests/flashcard_push.test.js10.9 KB
- 脚本scripts/tests/flashcards.test.js11.7 KB
- 脚本scripts/tests/frontmatter.test.js1.8 KB
- 脚本scripts/tests/link_check.test.js5.4 KB
- 脚本scripts/tests/longform_candidates.test.js7.2 KB
- 脚本scripts/tests/queue.test.js4.5 KB
- 脚本scripts/tests/required_links.test.js3.0 KB
- 脚本scripts/tests/state.test.js5.3 KB
- 脚本scripts/tests/vault.test.js2.1 KB
- 脚本scripts/tests/wikilinks.test.js4.4 KB
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
- Broken wikilinks —
[[links]]that don't resolve to an existing note. - Missing required links —
200_execution/notes missing atheory:link to a100_concepts/note (Rule 2), and100_concepts/notes oftype: conceptmissing aderived_fromfield. - 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)
-
Apply each
auto_fixesentry via the Edit tool:broken-link: infile, replace the literal textrawwithnew_raw.missing-theory-link: infile's frontmatter, settheory: ["<added>"](or append<added>iftheory:already has other entries — shouldn't happen for this fix type, since it only fires whentheory:is empty).
-
Resolve each
flaggedentry, per itstype:ambiguous-broken-link/ambiguous-link-collision: readfileand each note incandidates; if one is clearly the intended target, fix the link as inbroken-linkabove. If genuinely unclear, leave it and note it for the user in the summary.missing-theory-link: readfile; if a100_concepts/note is the obvious subject, addtheory: ["[[<Concept>]]"]. Otherwise leave it for the user.needs-derived-from-review: apply the02_Design_Specs.md §10objective/subjective test. If the note is interpretive/subjective and a source note can be identified, addderived_from: ["[[<Source>]]"]. If the note is objective/canonical, no action — absence is correct.candidate-link: read bothfile_aandfile_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.
-
Write the summary to
AgentOS/maintenance/link-verification_<YYYY-MM-DD>.md(sibling toObsVault/, per02_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. -
Update
state.json:- Set
last_runto the report'sgenerated_atvalue. - For each
candidate-linkresolved by dropping it (not adding a link), append[file_a, file_b](in the order given by the report) todismissed_pairs, unless an equivalent pair (in either order) is already present. - This step always runs, even if no
candidate-linkitems were dropped —last_runmust advance so the next incremental run doesn't re-scan unchanged files.
- Set
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 intostage_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 animage-occlusionflag (build manually in Anki).declared_sections/unrecognized_headings— the ideation note's headings, checked against the§23.2/§23.3vocabulary. 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)
- Context-Anchoring — every prompt names the parent framework/domain of
the tested element (use the directive's
context_anchor); never bare term→definition. - Minimum Information / Atomicity — one fact/relation/step per card; no compound questions; no lists unless ≤3 items and the count is the fact.
- 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. - Procedural-Step Fidelity — Case-Approach-modified cards reuse the
step names/ordering from the note (or linked
200_execution/notes) verbatim. - Supportive-Info Linking — Definition/Theorem/Principle cards reference at least one related concept by name in prompt or answer.
- No-Orphan-Recall — a card shown out of order must still be answerable from its own content.
- 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). - 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-noterather than drafted; a derivation-heavy concept note with some declared archetype still drafts those, per the user's own Stage A judgment call. - 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.
- 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 inworked_examples.mdfor the obviousness threshold in practice.
Stage C — AI Structuring / Stage D — Gap Flagging (review/draft pass)
- Read the ideation note named in each
drafted_notesdirective — 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. - Check the matching archetype/modifier's shape against
AgentOS/reference/flashcard_examples/worked_examples.md; write 1-3 finished card entries per declared heading intoAgentOS/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. SkipLongform Candidateheadings — a routing marker (§23), not an archetype/ modifier; never draft a card from one. It's Step 3's input instead (see below). - Anki semantic-duplicate check (
§23.7), per drafted card, before appending to the queue. Pipe this note's drafted card(s) as JSON tonode scripts/anki_similarity_query.jsvia 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. - Work through
stage_a_cross_checkfor 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. - For each
flaggedentry: append a## [<note>] — FLAGGEDblock recording the reason (unresolved-concept-link,empty-ideation-note,unrecognized-heading,duplicate-heading, orimage-occlusion). Never write a card for these.duplicate-headingis almost always leftoverCard Ideation.mdtemplate scaffolding pasted alongside real content (e.g. a second empty## Definitionafter 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. - Tag each card entry with
domain::sub_domain+ a concept-slug (kebab-case of the tested element) and anIdeation:field pointing back at the ideation note (§23— needed for the push-time status flip below). - Flip the ideation note's frontmatter
status: draft→status: reviewed(Edit tool) once its cards are written into the queue. - Advance state: set
state.json'sflashcards.last_runto the report'sgenerated_atvalue. Always runs, even if zero cards were drafted. - 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.jscopies 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 inObsVault/, per Hard Rule 2):{ schema_version, model, notes: { "<noteId>": { mod, deck, front, back, vec } } }. Built and incrementally refreshed byanki_similarity_sync.jsfrom AnkiConnect'snotesInfo(per-notemodtimestamp drives the reuse/re-embed decision) andcardsInfo(deck name —notesInfodoesn't return it). These two AnkiConnect actions are new alongside the already-documentedfindNotes/addNote.- Threshold (
ANKI_SIMILARITY_THRESHOLDinlib/anki_similarity.js, currently0.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/transformersis declared in this skill'spackage.json— runnpm installinAgentOS/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.
-
For each
flaggedentry, get the user's proposal — branch onsignals.ideation_declared:true: read the concept's sibling150_card_ideation/<slug>.mddirectly. Its## Longform Candidatebullets 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 for200_execution/candidates (no ideation-note sibling exists for them) and for100_concepts/candidates that haven't declared one yet.
-
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.
-
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_seenis the note'supdatedfrontmatter value at review time — this is what FR-05's cache check compares against on the next scan, not the review timestamp itself.declared_viais"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. -
Update
state.json: setlongform_candidates.last_runto the report'sgenerated_atvalue. Always runs, even if zero candidates were flagged this pass — advances the incremental scan the same way Steps 1–2 do. -
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
vocab-anki
暂无简介
transcript-distillation
暂无简介
daily-log
暂无简介
capture-promotion
暂无简介
review
Clear due memory reviews with free recall — the two-minute habit that makes learning permanent. Use when reviews are due, or the user wants to review, practice, or "do my engram reviews".
learn
Learn any topic properly — first-principles curriculum, generation-first tutoring, verified free recall, FSRS scheduling. Use when the user wants to learn, understand, study, or continue studying something.