gtapps/cortex-sync

Cortex Sync

Brings existing hermit content up to date with the frontmatter contract. Safe to run multiple times — only touches files that are missing required fields.

Step 1 — Scan (no writes)

Scan for missing fields:

• sessions/S-NNN-REPORT.md — missing tags
• proposals/PROP-NNN.md — missing tags
• Artifact paths declared in cortex-manifest.json — missing frontmatter (title, created) or tags

If cortex-manifest.json does not exist or artifact_paths is empty: skip artifact scanning entirely and include in the summary: "No artifact paths configured — skipping artifact enrichment. Run /claude-code-hermit:obsidian-setup to configure."

Report a full summary before doing anything. No writes in this step.

Cortex sync — gaps found:

  Sessions without tags:              18
  Proposals without tags:              4
  Artifact files without frontmatter:  6
  Artifact files without tags:         3

Proceed? (y/n)

"Proceed?" is abort-or-continue only — not blanket approval. Each cluster in the following steps still requires its own confirmation. Within each cluster, "skip" skips that cluster only — the skill continues with remaining clusters. If nothing is missing: "All content is up to date. Nothing to do." Stop.

Step 2 — Enrich artifacts

Handle all artifact files with gaps — both missing frontmatter and missing tags:

Missing frontmatter (title or created absent):

• Read the file content
• Apply the frontmatter contract (Section E of docs/frontmatter-contract.md): infer title from H1 heading or filename, created from git log or file mtime, source as interactive, propose tags from content
• Group files with similar inferred values into clusters and present as a batch:

  "6 artifact files in relatorios/ look like weekly reports. Apply this frontmatter to all? (confirm/edit/skip)"

• Fall back to per-file confirmation only when confidence is low or files differ significantly

Has frontmatter but missing tags:

• Read the file content and existing frontmatter
• Propose tags using the current vocabulary (see Step 3 for vocabulary rules)
• Confirm per cluster before writing

Step 3 — Tag sessions and proposals

Before proposing any tags: scan the last 5 session reports and proposals for the existing vocabulary. Follow the tag discipline rule from CLAUDE-APPEND: reuse existing tags, introduce new ones only when nothing fits, bias toward 1–2 tags per document.

After confirming each cluster, fold the accepted tags into the live vocabulary before proposing the next cluster — tags coined early in the run should be reusable for later clusters.

Cluster by inferred topic rather than confirming one by one:

• Group sessions/proposals by inferred topic (e.g., all "content" work, all "automation" work)
• Present each cluster with its own confirmation:

  "12 sessions appear to be content-related. Tag all with [content]? (y/edit/skip)"

• Fall back to per-file only for sessions that don't fit a clear cluster

Step 4 — Rebuild (conditional)

Check whether the Cortex is set up by using Glob("obsidian/*.md") — if it returns results, the Cortex is set up.

If yes: Run:

node ${CLAUDE_PLUGIN_ROOT}/scripts/build-cortex.js .claude-code-hermit obsidian .

This regenerates Connections.md with the enriched content. Cortex Portal.md is a live Dataview template and does not need to be rebuilt.

If no: Skip the rebuild and report:

"Content enriched. Run /claude-code-hermit:obsidian-setup to generate Cortex pages."

Step 5 — Report

Cortex sync complete
  Frontmatter added:    6 files
  Artifact files tagged: 3
  Sessions tagged:      18
  Proposals tagged:      4