From bedrock
Persists entities to vaults via single write point: detects, matches, creates/updates, and links bidirectionally. Handles structured lists, free-form text/notes, or graphify output; auto-resolves vault by flag, CWD, or default.
npx claudepluginhub iurykrieger/claude-bedrock --plugin bedrockThis skill is limited to using the following tools:
Entity definitions and templates are in the plugin directory, not in the vault root.
Detects and fixes vault structural misalignments: broken backlinks, concept fragmentation, entity miscategorization, duplicated entities, and misnamed entities. Supports interactive and cron modes.
Archives investigation findings into Obsidian vaults or directories as structured knowledge with entity notes, methodology notes, tool notes, registries, and wikilinks. Standalone or Spotlight pipeline.
Manages Obsidian vault structure by organizing documents into service and work-log layers, adding files with auto-categorization and metadata, processing meeting notes, running health checks, and committing via Git.
Share bugs, ideas, or general feedback.
Entity definitions and templates are in the plugin directory, not in the vault root. Use the "Base directory for this skill" provided at invocation to resolve paths:
<base_dir>/../../entities/<base_dir>/../../templates/{type}/_template.md<base_dir>/../../CLAUDE.md (already injected automatically into context)Where <base_dir> is the path provided in "Base directory for this skill".
Resolve which vault to operate on. 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 further parsing.
Step 2 — Resolve vault path:
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.
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.
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.
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.
<VAULT_PATH>/actors/, <VAULT_PATH>/people/, etc.<VAULT_PATH>/.bedrock/config.jsongit -C <VAULT_PATH> <command>This skill centralizes ALL write logic for the vault. It receives input (structured, free-form,
or graphify output), identifies entities, correlates with the existing vault, proposes changes
to the user, and executes after confirmation. It is the only path to create or update entities in the vault (except /sync-people
which handles people/teams via GitHub API).
You are an execution agent. Follow the phases below in order, without skipping steps.
Two pre-flight steps run before any input parsing: synchronize the vault with its remote, then (when applicable) merge an incoming graphify output directory into the vault's cumulative graphify-out/.
Execute:
git -C <VAULT_PATH> pull --rebase origin main
If the pull fails:
git -C <VAULT_PATH> rebase --abort and warn the user. DO NOT proceed without resolving.When this runs: Only when the skill was invoked with a graphify_output_path argument pointing at a graphify output directory (e.g., /bedrock:learn passes $TEACH_TMP/graphify-out-new/). Free-form text input and structured entity-list input skip this sub-phase entirely.
Skip condition (backward compat): If the input's graphify_output_path resolves to the same absolute path as <VAULT_PATH>/graphify-out/, skip this sub-phase. Legacy callers (and /bedrock:sync in its current form) point at the vault's own output directory — there is nothing to merge. Use realpath (or equivalent) to compare:
incoming_real=$(cd "<graphify_output_path>" 2>/dev/null && pwd -P)
vault_real=$(cd "<VAULT_PATH>/graphify-out" 2>/dev/null && pwd -P)
if [ "$incoming_real" = "$vault_real" ]; then
echo "Phase 0.2: graphify_output_path already points at the vault — skipping merge."
# proceed to Phase 1 with graphify_output_path unchanged
fi
Skip condition (no graphify input): If the input is free-form text, structured entity list, or otherwise does not include graphify_output_path, skip.
Step 1 — Validate incoming directory. Verify that <graphify_output_path>/graph.json exists, is non-empty, and parses as valid JSON. If invalid, abort with a clear error and do NOT mutate the vault:
if [ ! -s "<graphify_output_path>/graph.json" ]; then
echo "ERROR: graph.json missing or empty in <graphify_output_path>. Aborting before vault mutation."
exit 1
fi
python3 -c "import json,sys; json.load(open('<graphify_output_path>/graph.json'))" || { echo "ERROR: graph.json is not valid JSON."; exit 1; }
Step 2 — First-ingestion edge case. If <VAULT_PATH>/graphify-out/ does not exist, promote the incoming directory wholesale (no re-merge pass) and record stats, then skip to Step 7:
if [ ! -d "<VAULT_PATH>/graphify-out" ]; then
mkdir -p "<VAULT_PATH>"
cp -R "<graphify_output_path>" "<VAULT_PATH>/graphify-out"
echo "Phase 0.2: first ingestion — promoted incoming graphify output to <VAULT_PATH>/graphify-out/."
# record: nodes_added = <count of nodes in graph.json>, nodes_merged = 0, edges_added = <count of edges>, stale_flag_set = false
# skip to Step 7 (record stats) then exit sub-phase
fi
Step 3 — Merge graph.json (nodes + edges). Both files follow NetworkX node-link format ({"nodes": [...], "edges": [...]} or "links" — accept either key). Run the merge via an inline Python block to avoid hand-merging JSON in the prompt. Write the merged graph to a staging file, then atomically swap:
python3 - <<'PY'
import json, os, pathlib, shutil, sys
existing_path = pathlib.Path("<VAULT_PATH>/graphify-out/graph.json")
incoming_path = pathlib.Path("<graphify_output_path>/graph.json")
staging_path = existing_path.with_suffix(".json.staging")
with existing_path.open() as f:
existing = json.load(f)
with incoming_path.open() as f:
incoming = json.load(f)
# Accept both "edges" and "links" keys — normalize to "edges".
def _edges(g):
return g.get("edges", g.get("links", []))
# --- Node merge keyed by id ---
def _union(a, b):
# Preserve order; dedup by string representation.
seen, out = set(), []
for item in (a or []) + (b or []):
key = json.dumps(item, sort_keys=True) if not isinstance(item, str) else item
if key not in seen:
seen.add(key)
out.append(item)
return out
def _dedup_sources_by_url(a, b):
seen, out = set(), []
for item in (a or []) + (b or []):
if isinstance(item, dict) and "url" in item:
if item["url"] in seen:
continue
seen.add(item["url"])
out.append(item)
return out
existing_nodes = {n["id"]: n for n in existing.get("nodes", [])}
nodes_added = 0
nodes_merged = 0
for inc in incoming.get("nodes", []):
nid = inc["id"]
if nid not in existing_nodes:
existing_nodes[nid] = inc
nodes_added += 1
else:
cur = existing_nodes[nid]
# Union sources by URL
if "sources" in inc or "sources" in cur:
cur["sources"] = _dedup_sources_by_url(cur.get("sources"), inc.get("sources"))
# Most-recent updated_at (YYYY-MM-DD lexical compare works)
cur_ua, inc_ua = cur.get("updated_at"), inc.get("updated_at")
if inc_ua and (not cur_ua or inc_ua > cur_ua):
cur["updated_at"] = inc_ua
# Union labels and tags
for key in ("labels", "tags"):
if key in inc or key in cur:
cur[key] = _union(cur.get(key), inc.get(key))
nodes_merged += 1
# --- Edge dedup keyed by (source, target, type/relation) ---
def _edge_key(e):
return (e.get("source"), e.get("target"), e.get("type") or e.get("relation"))
existing_edges = _edges(existing)
seen_edges = {_edge_key(e) for e in existing_edges}
edges_added = 0
for inc_edge in _edges(incoming):
k = _edge_key(inc_edge)
if k in seen_edges:
continue
existing_edges.append(inc_edge)
seen_edges.add(k)
edges_added += 1
merged = dict(existing)
merged["nodes"] = list(existing_nodes.values())
# Preserve the key naming the existing file used.
merged_key = "edges" if "edges" in existing else ("links" if "links" in existing else "edges")
merged[merged_key] = existing_edges
with staging_path.open("w") as f:
json.dump(merged, f, indent=2, ensure_ascii=False)
# Emit stats to stdout for capture.
print(json.dumps({"nodes_added": nodes_added, "nodes_merged": nodes_merged, "edges_added": edges_added}))
PY
Atomic swap after the Python block succeeds:
mv "<VAULT_PATH>/graphify-out/graph.json.staging" "<VAULT_PATH>/graphify-out/graph.json"
If the Python block exits non-zero, abort without running the mv — the vault's graph.json stays untouched.
Step 4 — Append obsidian/*.md files. For each markdown file in <graphify_output_path>/obsidian/:
source_file frontmatter value starts with /tmp/ — these are ephemeral visualization files produced by /bedrock:teach and must not accumulate in the vault.<VAULT_PATH>/graphify-out/obsidian/: append the incoming content to the existing file, separated by \n\n---\n\n. Existing content is preserved verbatim.<VAULT_PATH>/graphify-out/obsidian/.mkdir -p "<VAULT_PATH>/graphify-out/obsidian"
for src in "<graphify_output_path>/obsidian/"*.md; do
[ -e "$src" ] || continue
SRC_FILE=$(awk -F'"' '/^source_file:/{print $2; exit}' "$src")
case "$SRC_FILE" in /tmp/*) continue ;; esac
dest="<VAULT_PATH>/graphify-out/obsidian/$(basename "$src")"
if [ -e "$dest" ]; then
printf '\n\n---\n\n' >> "$dest"
cat "$src" >> "$dest"
else
cp "$src" "$dest"
fi
done
Step 5 — Append GRAPH_REPORT.md. If <graphify_output_path>/GRAPH_REPORT.md exists:
<VAULT_PATH>/graphify-out/GRAPH_REPORT.md exists: append a new dated section.if [ -f "<graphify_output_path>/GRAPH_REPORT.md" ]; then
dest="<VAULT_PATH>/graphify-out/GRAPH_REPORT.md"
if [ -e "$dest" ]; then
{
printf '\n\n---\n\n# Merge on %s\n\n' "$(date +%Y-%m-%d)"
cat "<graphify_output_path>/GRAPH_REPORT.md"
} >> "$dest"
else
cp "<graphify_output_path>/GRAPH_REPORT.md" "$dest"
fi
fi
Step 6 — Mark .graphify_analysis.json stale. If <VAULT_PATH>/graphify-out/.graphify_analysis.json exists, set a top-level "stale": true field. Other content is untouched:
analysis="<VAULT_PATH>/graphify-out/.graphify_analysis.json"
stale_flag_set=false
if [ -f "$analysis" ]; then
python3 - <<PY
import json, pathlib
p = pathlib.Path("$analysis")
with p.open() as f:
data = json.load(f)
data["stale"] = True
with p.open("w") as f:
json.dump(data, f, indent=2, ensure_ascii=False)
PY
stale_flag_set=true
fi
If the file does not exist, skip (nothing to mark).
Step 7 — Record merge stats for the Phase 7 report. Capture nodes_added, nodes_merged, edges_added (from Step 3's Python stdout) and stale_flag_set (from Step 6). These values are threaded through to Phase 7's report block under a new "Graphify merge" section and returned in the skill's result payload to the caller (e.g., /bedrock:learn).
Step 8 — Point subsequent phases at the merged location. After the merge succeeds, set graphify_output_path := <VAULT_PATH>/graphify-out/ for all downstream phases. Phase 1.3 (graphify-output parsing), Phase 2 (matching), and the rest of the flow read from the merged vault location — not from the original temp input.
/bedrock:preserve accepts three input modes. Determine which to apply:
When called by another skill (e.g., /bedrock:learn) or when the user provides an explicit list.
The format is an optional top-level header followed by a list of entities:
# Optional top-level header — applies to all entities in the batch
actor_context: <actor-name> # optional, kebab-case slug of an actor in the vault.
# When present, /preserve treats the batch as scoped to that actor:
# graphify nodes of file_type=document/paper become `code` of this actor
# with node_type ∈ {concept, decision} (see Phase 1.3 step 4).
entities:
- type: actor | person | team | concept | topic | discussion | project | fleeting | code
name: "canonical entity name"
action: create | update
content: "content to include in the entity body"
relations:
actors: ["actor-slug-1", "actor-slug-2"]
people: ["person-slug-1"]
teams: ["team-slug-1"]
concepts: ["concept-slug-1"]
topics: ["topic-slug-1"]
discussions: ["discussion-slug-1"]
projects: ["project-slug-1"]
code: ["node-slug-1"]
source: "github | confluence | jira | session | manual | gdoc | csv | graphify"
metadata: {} # additional frontmatter fields specific to the type
If the input is a bare list (no entities: key, no actor_context), accept it as a list of entities with actor_context = null. This preserves backward compatibility with callers that pre-date the field.
If the input follows this format (or something close): parse directly and go to Phase 2.
When the user provides natural text, meeting notes, session context, or any unstructured content. Analyze the text and extract:
Mentioned entities — identify by name, alias, or reference:
Inferred action — for each entity:
updatecreateContent — what was said about each entity in the input
Relations — infer which entities relate to each other based on context
Source — infer: session (conversation), meeting-notes (minutes), manual (typed text)
To classify new content, consult the plugin's entity definitions (see "Plugin Paths" section) (loaded in Phase 2.0):
Convert the result to the structured format from section 1.1 and proceed.
When called by /bedrock:learn (or any skill) with a graphify output reference,
OR when the user invokes /bedrock:preserve directly pointing at a graphify-out/ directory:
Input format:
graphify_output_path: path to graphify-out/ directorysource_url: original external source URL/path (optional — may not be present for manual invocation)source_type: type of external source (optional)actor_context: kebab-case slug of an actor in the vault (optional). When present, the entire corpus is treated as belonging to that actor: file_type=document/paper nodes are classified as code of that actor with node_type ∈ {concept, decision} instead of as global concept/topic/fleeting. When absent, classification falls back to the corpus-agnostic logic (concept global / topic / fleeting).Detection: If the input contains a path ending in graphify-out/ or graphify-out,
or references graph.json, treat as graphify output input.
Processing:
Read graph.json from graphify_output_path/graph.json:
id, label, file_type, source_file, source_locationsource, target, relation, confidence, confidence_scoregraph.json is missing or empty: abort with error "No graph.json found in graphify output. Run /graphify first."Read obsidian files from graphify_output_path/obsidian/*.md:
id (kebab-cased)Read analysis from graphify_output_path/.graphify_analysis.json (if exists):
community_id per node), god nodes (is_god_node), community labelsdomain/* tags when creating entitiesstale: true, downstream steps fall back to graph-only signals (no community-aware grouping)Read configuration from <VAULT_PATH>/.bedrock/config.json (best-effort):
code.max_per_actor: integer, default 200. Per-actor cap on the number of code candidates produced from this corpus. No absolute global cap.code.cluster_threshold: float, default 0.85. Minimum semantically_similar_to.confidence_score for two nodes to be grouped into the same code candidate..bedrock/config.json is missing or has no code block, use the defaults silently.Group nodes by semantic similarity (BEFORE filtering and classification) — produces clusters that will each become at most one code candidate:
semantically_similar_to edge between them with confidence_score ≥ code.cluster_threshold.community_id (from .graphify_analysis.json) AND at least one of them is is_god_node OR both have edge_count ≥ 2. This guards against weakly-tied community co-membership..graphify_analysis.json is absent or stale, only the semantically_similar_to rule applies.cluster_id (synthetic), member_node_ids[] (the union of node ids — this becomes the graphify_node_ids array of the resulting code entity), representative (the node with highest degree in the cluster — used for label, source_file, etc.).Classify clusters into vault entity types — /preserve owns this classification. Read ALL entity definitions from the plugin (see "Plugin Paths") and apply:
When actor_context is present (single-actor corpus):
file_type: code clusters → code for the actor, node_type ∈ {function, class, module, interface, endpoint} inferred from the representative node's label/edges.file_type: document or file_type: paper clusters → code for the actor:
node_type: decision if the representative node has rationale_for edges OR the label/text contains decision markers (e.g., "ADR", "RFC", "decision", "chose", "decided").node_type: concept otherwise.actor field is set to [[<actor_context>]] for all entities.When actor_context is absent (corpus-agnostic):
file_type: code clusters → code (parent actor inferred from source_file path or repo name in the path; if no actor can be inferred, classify as fleeting).file_type: document or file_type: paper clusters → check for concept first: if the representative node describes a pattern, principle, technique, protocol, or abstraction AND is self-contained AND is not specific to a single actor → concept (global).
topic or fleeting depending on completeness criteria.is_god_node) → consider as actor, concept, or topic.fleeting.Filter relevant clusters (applied to code candidates only — non-code classifications keep their existing inclusion logic):
confidence ∈ {EXTRACTED, INFERRED} AND at least one of:
is_god_node (from .graphify_analysis.json),degree > community_average_degree (from .graphify_analysis.json; if analysis absent, use overall graph average),edge_count ≥ 2.Test, Tests, Mock, Fake, Builder, Stub, Fixture) or the cluster only contains nodes flagged trivial by graphify.code candidates by their resolved actor. Within each actor, rank by is_god_node (true first) > degree > edge_count. Keep the top code.max_per_actor (default 200); discard the rest with a warning in the report listing how many were dropped per actor.Service|Controller|...) is removed.code classifications (concept global, topic, fleeting): include all that pass classification.Match against existing vault — Use the textual matching logic from Phase 2 (filename, name, aliases, graphify ids). For code entities, the graphify-id match accepts both legacy singular graphify_node_id and the new graphify_node_ids array — match if the cluster's member_node_ids set intersects the entity's existing id set. Mark matched clusters as update, unmatched as create.
Build internal structured format for each classified + filtered cluster:
type: from classification (step 6).name: kebab-cased label of the cluster's representative node.action: create or update (from step 8 matching).content: body of the obsidian markdown file matching the representative's id (or generate from graph.json metadata if no obsidian file). When the cluster has multiple members, include a brief "Grouped from N graphify nodes" note in the body listing the member ids — this preserves traceability.relations: from graph.json edges of all member nodes (convert node ids to entity slugs via kebab-case; deduplicate).source: from input source_type (or "graphify" if not provided).source_url: from input source_url (if provided).source_type: from input source_type (if provided).metadata: for code entities, include:
graphify_node_ids: array — the cluster's member_node_ids (always written as array even when size is 1).actor: wikilink of the parent actor ([[<actor_context>]] when set; otherwise inferred).node_type: from step 6.source_file: relative path from the representative node.confidence: strongest edge confidence across all member nodes (EXTRACTED > INFERRED > AMBIGUOUS).metadata: for concept (global) entities from graphify, include:
graphify_node_ids: array.confidence: strongest edge confidence across all members.Proceed to Phase 3 (Change Proposal) — present the classified cluster list for user confirmation, then execute writes as normal (Phases 4-7).
Note: When invoked directly by the user (not via /learn), the user confirmation in Phase 3 is the only gate before writes. When invoked via /learn, /learn has already shown the user the graphify report (god nodes, communities) providing context for the confirmation.
Before converting to structured format, classify each entity by Zettelkasten role. Consult the plugin's entity definitions ("Completeness Criteria" section) to determine the correct type:
Classification rule:
graphify_node_ids array (or legacy singular graphify_node_id) and actor defined → classify as code (permanent extension, sub-entity of actor)concept (permanent)fleetingHeuristics for fleeting:
When in doubt, err on the side of fleeting — it is safer to capture as fleeting and promote later than to create an incomplete permanent entity.
If the input came from another skill (e.g., /bedrock:learn) and already includes a classification suggestion (type: fleeting), respect the suggestion but validate against the criteria above.
If no input was provided: ask the user "What would you like to preserve in the vault? Provide text, meeting notes, or a list of entities."
Objective: Correlate entities from the input with the existing vault.
Read ALL entity definition files from the plugin (see "Plugin Paths" section):
<base_dir>/../../entities/*.md
These files define what each entity type is, when to create, when NOT to create, and how
to distinguish between types. Internalize these definitions — you will use them to classify new
content (especially in free-form mode, Phase 1.2).
List all files in each entity directory (exclude _template.md and _template_node.md):
<VAULT_PATH>/actors/*.md and <VAULT_PATH>/actors/*/*.md (actors can be folders)
<VAULT_PATH>/actors/*/nodes/*.md (code entities within actors)
<VAULT_PATH>/people/*.md
<VAULT_PATH>/teams/*.md
<VAULT_PATH>/topics/*.md
<VAULT_PATH>/discussions/*.md (if exists)
<VAULT_PATH>/projects/*.md (if exists)
<VAULT_PATH>/fleeting/*.md (if exists)
For each file found, extract:
filename (without extension) — canonical identifiername (or title) from frontmatter — human-readable namealiases from frontmatter — alternative namesgraphify_node_ids from frontmatter — for code entities (if present, accept both the new array form and the legacy singular graphify_node_id string; normalize to a set of ids per entity)For each entity from the input, check if it already exists in the vault:
Match rules (in priority order):
billing-api == billing-api"Billing API" finds billing-api.md"BillingAPI" finds billing-api.md if alias contains "BillingAPI"billing-api → billingapi finds "BillingAPI"graphify_node_ids (array) and the vault entity's id set, where the vault entity's id set is normalized from EITHER graphify_node_ids (array, current schema) OR the legacy singular graphify_node_id (string treated as a 1-element set). Any non-empty intersection is a match. This is the most reliable match for code entities and takes priority over the others when present.Safety rules:
For each entity from the input:
update (update existing entity)create (new entity)For entities of type actor that have a repository field in frontmatter:
GitHub MCP (call directly, NOT via subagent):
mcp__plugin_github_github__list_pull_requests → recent PRs (5, state=all, sort=updated)mcp__plugin_github_github__list_commits → recent commits (5)Atlassian MCP:
IMPORTANT: Enrichment is best-effort. If MCP is not available or fails, continue without it. Record which sources failed in the final report.
IMPORTANT: DO NOT use subagents for MCP calls. Permissions are not inherited by subagents.
Objective: Present to the user EVERYTHING that will be done, BEFORE executing.
For each entity, present:
## Change Proposal — /bedrock:preserve
### Entities to create
| # | Type | Name | File | Relations |
|---|---|---|---|---|
| 1 | actor | billing-new-api | actors/billing-new-api.md | [[squad-payments]], [[alice-smith]] |
### Entities to update
| # | Type | Name | File | Changes |
|---|---|---|---|---|
| 1 | actor | billing-api | actors/billing-api.md | Add "Recent Activity" section |
### Bidirectional links
| Source entity | Target entity | Section added |
|---|---|---|
| [[billing-new-api]] | [[squad-payments]] | "Related Actors" in squad-payments |
| [[squad-payments]] | [[billing-new-api]] | "team" in billing-new-api |
### Sources consulted
- ✅ Local vault
- ✅ / ❌ GitHub MCP
- ✅ / ❌ Atlassian MCP
Total: N entities to create, M to update, P bidirectional links.
Ask: "Confirm execution? (yes/no/adjust)"
DO NOT proceed without explicit user confirmation.
Objective: Create and update entities as per the approved proposal.
For each entity marked as create:
<base_dir>/../../templates/<directory>/_template.mdtype: entity typename (or title for topics): extracted namealiases: generate at least 1 alias following the convention per type (see conventions.md)tags: use hierarchical tags: [type/<type>, status/<status>, domain/<domain>]updated_at: today's date (YYYY-MM-DD)updated_by: "preserve@agent"status: deprecated → > [!warning] Deprecatedpci: true → > [!danger] PCI Scope<directory>/<filename>.mdRules per entity type:
| Type | Directory | Filename pattern | Name frontmatter key |
|---|---|---|---|
| actor | actors/ or actors/<name>/ | repo-name.md | name |
| code | actors/<actor>/nodes/ | node-slug.md | name |
| person | people/ | first-last.md | name |
| team | teams/ | squad-name.md | name |
| concept | concepts/ | slug.md | name |
| topic | topics/ | YYYY-MM-category-slug.md | title |
| discussion | discussions/ | YYYY-MM-DD-slug.md | title |
| project | projects/ | project-slug.md | name |
| fleeting | fleeting/ | YYYY-MM-DD-slug.md | title |
When creating a code entity:
actor field in the input (wikilink or slug) indicates the actor. Verify that the actor exists in actors/.actors/<name>.md):
actors/<name>/actors/<name>.md → actors/<name>/<name>.md (use git mv)actors/<name>/nodes/actors/_template_node.md
actors/<actor>/nodes/<node-slug>.mdname (e.g., ProcessTransaction → process-transaction.md)graphify_node_ids (array — always written as a list, even of size 1), actor, node_type, source_file, confidence from the inputgraphify_node_id (string), normalize it to graphify_node_ids: [<id>] before writing. Never persist the singular form.domain/* tags from the parent actoractor: "[[actor-name]]" in frontmatter- [[node-slug]] — brief description in the "Knowledge Nodes" sectionWhen filling the entity body, apply semantic linking rules by role:
For each entity marked as update:
updated_at and updated_bysources field (when applicable)If the input contains source_url and source_type (provided by /bedrock:learn or another caller):
When creating an entity:
sources:
- url: "<source_url>"
type: "<source_type>"
synced_at: "<today's date>"
When updating an entity:
sources field from frontmattersynced_at with today's date{url, type, synced_at}synced_at descending (most recent first)If the input does NOT contain source_url: do not modify the sources field — keep the existing value (or [] if new entity).
Objective: Ensure that every relation is reciprocal.
When creating/updating entity X with a reference to entity Y:
Bidirectional linking graph:
Team ──members──→ Person ──team──→ Team
Team ──actors──→ Actor ──team──→ Team
Topic ──people──→ Person
Topic ──actors──→ Actor
Person ──focal_points──→ Actor
Project ──focal_points──→ Person ──projects──→ Project
Project ──related_actors──→ Actor
Project ──related_topics──→ Topic
Project ──related_teams──→ Team
Discussion ──related_actors──→ Actor
Discussion ──related_people──→ Person
Discussion ──related_projects──→ Project
Discussion ──related_topics──→ Topic
Code ──actor──→ Actor ──"Knowledge Nodes" section──→ Code
Code ──relations──→ Code (bidirectional via relations[])
For each pair (X → Y) in the approved proposal:
[[X]] if not already present## Discussions, ## Related Projects):
- [[X]] — brief context at the end of the list---)updated_at and updated_by of YIdempotency: if the wikilink [[X]] already exists in Y's field/section, DO NOT add it again.
| Target entity (Y) | Body section | Frontmatter field |
|---|---|---|
| Actor receiving link from Discussion | ## Discussions | — |
| Actor receiving link from Project | ## Related Projects | — |
| Person receiving link from Discussion | ## Discussions | — |
| Person receiving link from Project | ## Projects | projects (if exists) |
| Topic receiving link from Project | ## Related Projects | — |
For frontmatter-based links (team↔actor, team↔person, person↔team, etc.): use only the YAML field, do not create a body section.
Objective: Propagate vault_entity_path to the corresponding nodes in <VAULT_PATH>/graphify-out/graph.json, closing the bidirectional bridge between each code entity touched in this run and the graphify nodes it materializes.
This phase runs AFTER bidirectional linking (Phase 5) and BEFORE the git workflow (Phase 6), so the back-pointer change lands in the same commit as the entities.
Remove any orphaned staging file from a prior interrupted run before doing anything else:
rm -f "<VAULT_PATH>/graphify-out/graph.json.staging" 2>/dev/null || true
This is idempotent and never fails the phase.
Locate the vault's cumulative graph file:
GRAPH_PATH="<VAULT_PATH>/graphify-out/graph.json"
test -s "$GRAPH_PATH" && echo "EXISTS" || echo "MISSING"
If the path does NOT exist, OR the file is empty (-s returns false), OR JSON parsing fails:
phase_6_5_status = "skipped" and phase_6_5_reason ("missing", "empty", or "invalid_json")./preserve.If the file exists and parses, continue.
code entitiesIterate over every entity created or updated in Phase 4 with type: code. For each one, normalize the graphify 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 working map: id → vault_entity_path where vault_entity_path is the path of the entity file relative to <VAULT_PATH> (e.g. actors/billing-api/nodes/process-transaction.md).
If the touched-code-entities set is empty (run touched no code entities), skip directly to Phase 6 with phase_6_5_status = "skipped", phase_6_5_reason = "no_code_entities".
Read graph.json and write the updated graph to a staging file:
python3 - <<'PY'
import json, pathlib, sys
graph_path = pathlib.Path("<VAULT_PATH>/graphify-out/graph.json")
staging_path = graph_path.with_suffix(".json.staging")
with graph_path.open() as f:
graph = json.load(f)
# Map from id → vault_entity_path was prepared in §6.5.3 — passed in as JSON.
target_map = json.loads("""<TARGET_MAP_JSON>""")
nodes_updated = 0
nodes_unmatched_ids = []
for node in graph.get("nodes", []):
nid = node.get("id")
if nid in target_map:
# Idempotency by overwrite: always set, even if already present.
node["vault_entity_path"] = target_map[nid]
nodes_updated += 1
# Detect ids that did not match any node (graph diverged from vault — possible re-run of /graphify).
matched_ids = {n["id"] for n in graph.get("nodes", []) if "id" in n}
nodes_unmatched_ids = [tid for tid in target_map.keys() if tid not in matched_ids]
with staging_path.open("w") as f:
json.dump(graph, f, indent=2, ensure_ascii=False)
print(json.dumps({
"nodes_updated": nodes_updated,
"unmatched_ids": nodes_unmatched_ids,
}))
PY
If the Python block exits non-zero (parse error, write error, etc.), do NOT run the mv — the original graph.json stays intact. Capture the error message, set phase_6_5_status = "failed", phase_6_5_reason = "<error>", and skip to Phase 6 without aborting /preserve. The vault's git state remains valid because no rename occurred.
If the Python block succeeded:
mv "<VAULT_PATH>/graphify-out/graph.json.staging" "<VAULT_PATH>/graphify-out/graph.json"
mv on the same filesystem is atomic at the filesystem level — readers either see the old or the new file, never a half-written one. Set phase_6_5_status = "applied" and capture nodes_updated, unmatched_ids from the Python output.
Capture for the Phase 7 report and the skill's return payload:
graph_back_pointers:
status: "applied" | "skipped" | "failed"
reason: "<reason if skipped or failed, omit if applied>"
nodes_updated: N # 0 when skipped
unmatched_ids: ["..."] # ids in touched entities but not found in graph.json
These values are threaded through to Phase 7's report block under a new "Graph back-pointers" section and returned in the skill's result payload to callers (e.g. /bedrock:learn).
Determine the commit message following the convention:
Single entity:
vault(<type>): <verb> <name> [source: <source>]
Types: actor, person, team, concept, topic, discussion, project, source
Verbs: creates, updates, links
Sources: memory, github, jira, confluence, gdoc, csv, manual, session, preserve
Multiple entities:
vault: preserves N entities [source: <sources>]
Or, if called by /bedrock:learn:
vault: teaches <source-name>, creates N updates M entities [source: <type>]
# Stage touched entities (includes actor subfolders: actors/*/nodes/)
git -C <VAULT_PATH> add actors/ people/ teams/ topics/ discussions/ projects/ fleeting/
# Stage graphify back-pointer changes when Phase 6.5 ran successfully.
# Only run when graphify-out/graph.json exists — `git add` of a non-existent path errors out.
if [ -f "<VAULT_PATH>/graphify-out/graph.json" ]; then
git -C <VAULT_PATH> add graphify-out/graph.json
fi
# Check if there is anything to commit
git -C <VAULT_PATH> diff --cached --quiet && echo "Nothing to commit" && exit 0
Read the vault's git strategy from .bedrock/config.json:
cat <VAULT_PATH>/.bedrock/config.json 2>/dev/null
Extract the git.strategy field. If the file does not exist or has no git key, default to "commit-push".
Valid values: "commit-push", "commit-push-pr", "commit-only".
Strategy: commit-push (default)
git -C <VAULT_PATH> commit -m "<message per convention>"
git -C <VAULT_PATH> push origin main
If push fails (conflict):
git -C <VAULT_PATH> pull --rebase origin main
git -C <VAULT_PATH> push origin main
If it fails 2x: STOP and inform the user. If there is no remote: commit locally and warn.
Strategy: commit-push-pr
First, check that gh is available:
which gh 2>/dev/null
If gh is not found: warn the user and fall back to commit-push strategy (above).
If gh is available:
Create a branch. Derive the branch name from the commit message:
vault/<YYYY-MM-DD>-<entity-name> (e.g., vault/2026-04-15-billing-api)vault/<YYYY-MM-DD>-batch-<N>-entities (e.g., vault/2026-04-15-batch-7-entities)Check for collisions:
git -C <VAULT_PATH> branch --list "vault/<YYYY-MM-DD>-<slug>*"
If the branch already exists, append a counter: vault/2026-04-15-billing-api-2.
git -C <VAULT_PATH> checkout -b <branch-name>
Commit and push the branch:
git -C <VAULT_PATH> commit -m "<message per convention>"
git -C <VAULT_PATH> push origin <branch-name>
Open a pull request:
cd <VAULT_PATH> && gh pr create --title "<commit message>" --body "Automated by /bedrock:preserve" --base main
Return to main:
git -C <VAULT_PATH> checkout main
Strategy: commit-only
git -C <VAULT_PATH> commit -m "<message per convention>"
Do not push. Output:
Git strategy: commit-only — changes committed locally. Use `git push` manually when ready.
Present to the user:
## Preserve — Report
### Entities created
| Type | Name | File | Source |
|---|---|---|---|
| actor | payment-new-api | actors/payment-new-api.md | github |
### Entities updated
| Type | Name | File | Changes |
|---|---|---|---|
| actor | billing-api | actors/billing-api.md | Recent Activity, wikilinks |
### Bidirectional links applied
| Source | Target | Type |
|---|---|---|
| [[billing-new-api]] | [[squad-payments]] | frontmatter: actors[] |
| [[squad-payments]] | [[billing-new-api]] | frontmatter: team |
### Graphify merge (only when Phase 0.2 ran)
| Metric | Value |
|---|---|
| Nodes added | N |
| Nodes merged | M |
| Edges added | P |
| Analysis marked stale | true / false |
Omit this section entirely when Phase 0.2 was skipped (no `graphify_output_path`, or backward-compat path match).
The same four fields are included in the skill's return payload (e.g., consumed by `/bedrock:learn`):
```yaml
graphify_merge:
nodes_added: N
nodes_merged: M
edges_added: P
stale_flag_set: true | false
| Metric | Value |
|---|---|
| Status | applied / skipped / failed |
| Reason (skipped/failed) | missing / empty / invalid_json / no_code_entities / |
| Nodes updated | N (0 when skipped) |
| Unmatched ids | list (ids present in touched entities but absent from graph.json) |
When Status = applied, the back-pointer write is part of the same git commit as the entities (Phase 6 stages graphify-out/graph.json alongside the entity directories). When Status = skipped or failed, no graph mutation occurred and the vault's graph.json is untouched.
The same fields are included in the skill's return payload:
graph_back_pointers:
status: "applied" | "skipped" | "failed"
reason: "..." # omit when applied
nodes_updated: N
unmatched_ids: ["..."]
vault: preserves 2 entities [source: github]
---
## Critical Rules
| # | Rule |
|---|---|
| 1 | **NEVER delete content** written by another agent or human (except the "Recent Activity" section in actors, which is temporal) |
| 2 | **NEVER overwrite frontmatter** — only merge new fields. NEVER delete existing fields. |
| 3 | **NEVER commit sensitive data** (credentials, tokens, PANs, CVVs) |
| 4 | **ALWAYS update** `updated_at` and `updated_by` on every touched entity |
| 5 | **ALWAYS use kebab-case** without accents for filenames |
| 6 | **ALWAYS follow the templates** from `_template.md` when creating new pages |
| 7 | **ALWAYS confirm** proposal with user before executing writes |
| 8 | **Maximum 2 push attempts** — after that, abort and inform |
| 9 | **Best-effort for external sources** — never block due to unavailable MCP |
| 10 | **Idempotency in wikilinks** — do not add a link that already exists |
| 11 | **Frontmatter keys in English**, values in the vault's configured language |
| 12 | **Bare wikilinks** — `[[name]]`, never `[[dir/name]]` |
| 13 | **Hierarchical tags** — `[type/actor]`, never `[actor]` |
| 14 | **Mandatory aliases** — at least 1 alias per new entity |
| 15 | **Mandatory callouts** — `[!warning] Deprecated` for deprecated, `[!danger] PCI Scope` for PCI |
| 16 | **Vault resolution first** — resolve `VAULT_PATH` before any file operation or git command |
| 17 | **All git commands use `git -C <VAULT_PATH>`** — never assume CWD is the vault |
| 18 | **All entity paths use `<VAULT_PATH>/` prefix** — `<VAULT_PATH>/actors/`, not `actors/` |
| 19 | **Graphify merge is append-only** — Phase 0.2 never deletes nodes, edges, obsidian content, or GRAPH_REPORT sections. On node-id collision: union `sources` by URL, take most-recent `updated_at`, union labels/tags. On edge collision by `(source, target, type)`: drop the incoming duplicate. |
| 20 | **Graphify merge backward-compat** — if `graphify_output_path` resolves to the same absolute path as `<VAULT_PATH>/graphify-out/`, Phase 0.2 is a no-op. Legacy callers and `/bedrock:sync` continue to work unchanged. |
| 21 | **Graphify merge is atomic** — `graph.json` is merged into a `.staging` file and atomically renamed. If validation or merge fails, the vault's `graph.json` is untouched. |
| 22 | **`.graphify_analysis.json` is marked stale, never recomputed** — Phase 0.2 sets `stale: true` on merge. `/bedrock:compress` owns recomputation. |
| 23 | **`actor_context` scopes the corpus** — when present in Phase 1.1 / 1.3 input, `file_type=document/paper` graphify nodes become `code` of that actor with `node_type ∈ {concept, decision}`; when absent, classification falls back to corpus-agnostic logic (concept global / topic / fleeting). The caller (e.g. `/learn`) decides which mode to invoke. |
| 24 | **Semantic grouping precedes filtering** — Phase 1.3 step 5 clusters graphify nodes by `semantically_similar_to ≥ code.cluster_threshold` (default 0.85) or community co-membership BEFORE the relevance filter. Each cluster maps to at most one `code` candidate carrying every `graphify_node_ids`. |
| 25 | **Per-actor cap, no global cap** — `code.max_per_actor` (default 200, from `.bedrock/config.json`) caps `code` candidates per actor. Ranking inside the cap: `is_god_node` > `degree` > `edge_count`. There is NO absolute global cap on the number of `code` entities in the vault. |
| 26 | **`graphify_node_ids` is always written as an array** — even when the cluster has a single member. At read time, `/preserve` accepts both the array form and the legacy singular `graphify_node_id` (string); it always writes the array on output. There is no batch migration. |
| 27 | **No English keyword regex for relevance** — the previous label allowlist (`Service|Controller|Client|Factory|Handler|Mapper|Gateway|Provider`) is REMOVED. Relevance comes from confidence + community signals (`is_god_node`, `degree > community average`, `edge_count ≥ 2`). Trivial label exclusion (`Test`, `Mock`, `Builder`, etc.) is preserved. |
| 28 | **Phase 6.5 is atomic** — `graph.json` is written to a `.staging` file and atomically renamed via `mv`. If the Python block fails, `mv` does NOT run, the vault's `graph.json` stays intact. Same pattern as Phase 0.2 (Rule 21). No write to `graph.json` occurs outside Phase 0.2 and Phase 6.5. |
| 29 | **Phase 6.5 is best-effort** — when `<VAULT_PATH>/graphify-out/graph.json` is missing, empty, invalid JSON, or no `code` entities were touched, Phase 6.5 silently skips with an explicit `status` and `reason` in the Phase 7 report. `/preserve` does NOT fail. Vaults without `graphify-out/` continue to work without the bridge. |
| 30 | **Phase 6.5 is idempotent** — `vault_entity_path` is always overwritten with the current path, never appended. Running `/preserve` twice in a row over the same entities does not duplicate fields nor alter any other node attribute. Unmatched ids (graphify re-run, id changed) surface as a warning but never block. |