iurykrieger/claude-bedrock/compress

/bedrock:compress — Vault Alignment Engine

Plugin Paths

Entity definitions and templates are in the plugin directory, not the vault root. Use the "Base directory for this skill" provided at invocation to resolve paths:

• Entity definitions: <base_dir>/../../entities/
• Templates: <base_dir>/../../templates/{type}/_template.md
• Plugin CLAUDE.md: <base_dir>/../../CLAUDE.md (already injected automatically into context)

Where <base_dir> is the path provided in "Base directory for this skill".

Vault Resolution

Resolve which vault to compress. This skill can be invoked from any directory.

Step 1 — Parse `--vault` flag: Check if the input arguments include --vault <name>. If found, extract the vault name and remove it from the arguments before parsing --mode.

Step 2 — Resolve vault path:

1. If `--vault <name>` was provided:

Read the vault registry at <base_dir>/../../vaults.json. Find the entry matching the name. If not found: error — "Vault <name> is not registered. Run /bedrock:vaults to see available vaults." If found: set VAULT_PATH to the entry's path value. Store the resolved vault name as VAULT_NAME.

1. If no `--vault` flag — CWD detection:

Read <base_dir>/../../vaults.json. Check if the current working directory is inside any registered vault path (CWD starts with a registered vault's absolute path). If multiple match, use the longest path (most specific). If found: set VAULT_PATH to the matching vault's path. Store its name as VAULT_NAME.

1. If CWD detection fails — default vault:

From the registry, find the vault with "default": true. If found: set VAULT_PATH to the default vault's path. Store its name as VAULT_NAME.

1. If no resolution:

Error — "No vault resolved. Available vaults:" followed by the registry listing. "Use --vault <name> to specify, or run /bedrock:setup to register a vault."

Step 3 — Validate vault path:

test -d "<VAULT_PATH>" && echo "exists" || echo "missing"

If missing: error — "Vault path <VAULT_PATH> does not exist on disk. Run /bedrock:setup to re-register."

Step 4 — Read vault config:

cat <VAULT_PATH>/.bedrock/config.json 2>/dev/null

Extract language, git.strategy, and other relevant fields for use in later phases.

From this point forward, ALL vault file operations use `<VAULT_PATH>` as the root.

• Entity directories: <VAULT_PATH>/actors/, <VAULT_PATH>/people/, etc.
• Git operations: git -C <VAULT_PATH> <command>
• When delegating to /bedrock:preserve, pass --vault <VAULT_NAME>

Overview

This skill scans all entities in the vault, detects 5 types of structural misalignments, proposes fixes to the user, and delegates all writes to /bedrock:preserve.

You are an execution agent. Follow the phases below in order, without skipping steps.

Execution modes

The skill accepts an optional --mode argument:

• `interactive` (default): all 5 capabilities prompt the user for confirmation before execution.
• `cron`: capabilities 1 and 4 (mechanical, deterministic) execute autonomously without confirmation.

Capabilities 2, 3, and 5 (semantic, judgment-dependent) are detected but written as a proposal to a fleeting note for human review — they are NOT executed.

Parse the mode from the invocation arguments. If no --mode is specified, default to interactive.

Five alignment capabilities

Critical rules:

• NEVER write entity files directly — all mutations go through /bedrock:preserve
• NEVER execute semantic capabilities (2, 3, 5) without confirmation in interactive mode
• NEVER execute semantic capabilities (2, 3, 5) autonomously in cron mode — always queue
• NEVER remove existing wikilinks
• NEVER delete entities (compress aligns, it does not delete)
• People/Teams/Concepts/Topics: append-only — never delete content
• Actors: free merge — may edit body freely

Phase 0 — Sync the Vault

Execute:

git -C <VAULT_PATH> pull --rebase origin main

If it fails:

• No remote: warn "No remote configured. Working locally." and proceed.
• Conflict: git -C <VAULT_PATH> rebase --abort and warn the user. Do NOT proceed without resolving.

Phase 1 — Scan and Detect

Scan the entire vault and run all 5 detection algorithms. Store results for Phase 2.

1.0 Load entity definitions and config

Read the entity definitions from the plugin directory to understand classification criteria:

• <base_dir>/../../entities/concept.md — needed for capability 2 (concept match)
• <base_dir>/../../entities/*.md — needed for capability 3 (entity misalignment)
• <base_dir>/../../entities/code.md — needed for capability 1 graph-side detection (§1.2.2)

Store the "When to create", "When NOT to create", and "How to distinguish" sections from each entity definition for use in detection.

Read vault config for graph-side detection:

cat <VAULT_PATH>/.bedrock/config.json 2>/dev/null

Extract code.cluster_threshold (default 0.85, used by §1.2.2 for Scenario A-extended similarity matching and Scenario B clustering) and code.max_per_actor (default 200, used in Phase 5 to surface cap overrun warnings — never enforced as a hard limit). If .bedrock/config.json is missing or has no code block, use the defaults silently.

1.1 Read all entities

For each entity directory (<VAULT_PATH>/actors/, <VAULT_PATH>/people/, <VAULT_PATH>/teams/, <VAULT_PATH>/concepts/, <VAULT_PATH>/topics/, <VAULT_PATH>/discussions/, <VAULT_PATH>/projects/, <VAULT_PATH>/fleeting/):

1. List all .md files, excluding `_template.md` and `_template_node.md`

• For actors: include both <VAULT_PATH>/actors/*.md (flat) and <VAULT_PATH>/actors/*/*.md (folder)

1. For each entity, read frontmatter + body
2. Extract:

• type from frontmatter
• name from frontmatter (or filename as fallback)
• aliases from frontmatter (array)
• All wikilinks [[target]] from body AND frontmatter arrays
• All proper nouns, service names, team names, person names mentioned in the body (for capabilities 4 and 5)

Optimization for large vaults: If the vault has more than 100 entities in a type, use subagents via Agent tool to parallelize reading by entity type.

Output: vault_data map: entity_name → {type, name, aliases[], wikilinks[], body_mentions[], frontmatter, body}

1.2 Capability 1 — Detect broken backlinks

Cap 1 detects backlinks that are broken on either of two layers: markdown wikilinks (§1.2.1, today's behavior) and graph-side back-pointers (§1.2.2, total-binding rule).

1.2.1 Markdown-side backlinks (existing behavior)

For each entity A in vault_data:

1. For each wikilink [[B]] found in A (body or frontmatter arrays):

• Skip if B does not exist as an entity file in the vault (wikilinks to non-existent entities are valid in Obsidian)
• If B exists: check if B contains a wikilink [[A]] (body or frontmatter arrays)
• If B does NOT link back to A: register as broken backlink with kind: "markdown_backlink"

Output: broken_backlinks[] — list of {kind: "markdown_backlink", source: A, target: B, direction: "A→B exists, B→A missing"}

1.2.2 Graph-side back-pointers (total-binding rule)

Rule: every node in <VAULT_PATH>/graphify-out/graph.json MUST end up with vault_entity_path set. There is NO relevance filter at /compress time — confidence level (EXTRACTED / INFERRED / AMBIGUOUS), trivial labels (Test / Mock / Builder / Stub / Fixture), degree, is_god_node, edge_count do NOT exclude any node from binding.

Best-effort load. If <VAULT_PATH>/graphify-out/graph.json is missing, empty, or invalid JSON, skip §1.2.2 silently and proceed with §1.2.1 results only. The /compress run continues normally.

GRAPH_PATH="<VAULT_PATH>/graphify-out/graph.json"
test -s "$GRAPH_PATH" && python3 -c "import json,sys; json.load(open('$GRAPH_PATH'))" 2>/dev/null && echo "OK" || echo "SKIP"

If OK, also load <VAULT_PATH>/graphify-out/.graphify_analysis.json (best-effort — when missing or stale, fall back to semantically_similar_to-only grouping; same fallback used by /preserve Phase 1.3 step 5).

Build the entity-id index. For each code entity in vault_data (i.e., entities under <VAULT_PATH>/actors/*/nodes/), normalize ids to a set:

ids = set()
fm = entity.frontmatter
if isinstance(fm.get("graphify_node_ids"), list):
    ids.update(fm["graphify_node_ids"])
if isinstance(fm.get("graphify_node_id"), str):  # legacy singular — backward compat
    ids.add(fm["graphify_node_id"])

Build a map entity_id_index: id → entity_path covering every code entity. Build bound_node_ids = set(entity_id_index.keys()).

Walk every node in graph.json. For each node N with id and OPTIONAL vault_entity_path:

• If vault_entity_path is already set on N → already bound, skip.
• Otherwise classify in priority order — stop at first matching shape:

1. Scenario A — `back_pointer_missing`. If N.id ∈ bound_node_ids: register {kind: "graph_back_pointer", shape: "back_pointer_missing", node_id: N.id, entity_path: entity_id_index[N.id]}.

1. Scenario A-extended — `extend_existing`. Find any node M such that:

• M.id ∈ bound_node_ids (M is bound to some entity E),
• There is an edge (N, M) or (M, N) of relation: "semantically_similar_to" with confidence_score ≥ code.cluster_threshold,
• OR (when .graphify_analysis.json is present) community_id(N) == community_id(M) AND (is_god_node(M) OR (edge_count(N) ≥ 2 AND edge_count(M) ≥ 2)).

If found, pick the M with the highest confidence_score (or highest degree if community-based) and register {kind: "graph_back_pointer", shape: "extend_existing", node_id: N.id, target_entity_path: entity_id_index[M.id], target_node_id: M.id, similarity: <score>}.

1. Scenario B — `orphan_graph_node`. Otherwise, mark N as a Scenario B candidate. Do NOT register yet — Scenario B candidates are clustered together first (next step).

Cluster Scenario B candidates using the Part 2 grouping algorithm (mirrors /preserve Phase 1.3 step 5):

• Two Scenario B nodes are in the same cluster if there is a semantically_similar_to edge between them with confidence_score ≥ code.cluster_threshold, OR they share community_id AND (at least one is is_god_node OR both have edge_count ≥ 2).
• If .graphify_analysis.json is absent or stale, only the semantically_similar_to rule applies.
• Singletons form their own cluster of size 1.
• Each cluster carries: cluster_id (synthetic), member_node_ids[] (the union of node ids — this becomes the graphify_node_ids array of the resulting code entity), representative (highest-degree node in the cluster — used for label, source_file, node_type).

Resolve `actor_context` for each Scenario B cluster via (b) + (c) from the spec: