absorb_document
Convert a markdown agent-instruction file into typed vault nodes, classifying sections as policy, architecture suggestions, or injection risks. Dry-run returns a plan; confirm writes nodes.
Instructions
Slice 0 (PRODUCT-PLAN-2026-07.md §4/§9) — the "absorption tool". Converts a CLAUDE.md/AGENTS.md-style markdown file into typed vault nodes so a tech lead's existing agent-instruction file stops needing dual maintenance. Splits the file by ## sections and classifies each:
rule/policy/decision sections →
kind: documentnodes with arole: policyfrontmatter extra.architecture/component sections → element/capability SUGGESTIONS only — never auto-written; review and land with add_concept if useful.
sections matching an injection-suspect pattern (Tier 1 — imperative instruction-hijack phrasing, shell/SQL fragments) are excluded from absorption regardless of category and reported for human review. The file body is always treated as untrusted data; parsing never executes or evaluates its content. Two-stage safety, same shape as delete_concept:
Without confirm: true the call is a dry-run — returns the classification plan per section, no writes.
With confirm: true, absorbed sections are written as document nodes, the source file is backed up to
<file>.pre-absorb.bak, then rewritten into a "slim pointer" that reproduces every non-absorbed section (suggested, unclassified, or injection-suspect) verbatim — content is never destroyed. Throws instead of overwriting an existing backup file. The canonical source path must be inside repoRoot; outside paths (including symlink escapes) require an reviewed dry-run plus explicit allowOutsideRepo:true.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | No | Actually write when true. Omit or false for a dry-run (plan only, no writes). | |
| filePath | Yes | Path to the CLAUDE.md/AGENTS.md-style markdown file to absorb (absolute, or relative to the MCP server cwd). | |
| allowOutsideRepo | No | Explicit destructive opt-in required only when filePath resolves outside repoRoot. Dry-run reports outsideRepo and keeps canConfirm:false without it. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ok | Yes | ||
| title | No | ||
| dryRun | Yes | ||
| changed | No | ||
| message | Yes | ||
| summary | Yes | ||
| written | No | ||
| filePath | Yes | ||
| sections | Yes | ||
| backupPath | No | ||
| canConfirm | Yes | True only when repeating the call with confirm:true can perform the previewed change without another explicit safety opt-in. | |
| outsideRepo | Yes | ||
| sourceLabel | Yes | ||
| wouldChange | Yes | True only when the dry-run predicts a disk or Git change. | |
| previewReady | Yes | True only when this response is a complete dry-run preview that an agent can review. | |
| blockedReasons | Yes | Machine-readable human explanations for every condition currently blocking confirmation. | |
| postWriteMaintenance | No | Compact maintenance_plan summary for post-write follow-up. Bucket maps describe the remaining queue after the write. |