# Source-Tree Load Protocol

**Purpose:** Define how framework consumers read the decomposed `source-tree/`
context artifact efficiently — without ever loading the large `tree.json`
file wholesale.

**Trigger:** Any subagent, skill, or rule that needs source-tree information
(path validation, layer classification, directory purpose).

**Reference:** ADR-071 (source-tree as an AI-optimized decomposed folder
artifact), ADR-072 (tech-stack amendment permitting structured JSON context
artifacts).

---

## Why This Rule Exists

`source-tree.md` was replaced by `devforgeai/specs/context/source-tree/` — a
folder of generated, schema-validated JSON files. One of those files,
`tree.json`, is an **exhaustive every-file tree** (tens of thousands of
lines). Reading it wholesale blows the context window and is never
necessary: every measured consumer use case is served by a small slice.

The artifact self-describes its load protocol in `_manifest.json` under the
`load_protocol` key. This rule is the operational decision matrix.

---

## Decision Matrix

| Use case | Do this | Do NOT do this |
|----------|---------|----------------|
| **Path validation** — "is this file location legal?" | `devforgeai-validate query-source-tree --validate-path <path>` | `Read` `tree.json` and scan |
| **Placement / naming / forbidden-pattern rules** | `Read devforgeai/specs/context/source-tree/governance.json` (small) — or `query-source-tree --governance [--category <cat>]` | `Read` `tree.json` |
| **Component inventory** — "what is in agents / skills / hooks / …?" | `Read .../source-tree/components/<name>.json` — or `query-source-tree --component <name>` | `Read` `tree.json` |
| **Directory purpose** — "what does this one directory contain?" | `query-source-tree --subtree <path>` (extracts just that branch) | `Read` `tree.json` |
| **Big-picture counts / entry point** | `Read .../source-tree/_manifest.json` (~40 lines) | `Read` `tree.json` |

Component names: `skills`, `agents`, `commands`, `hooks`, `cli`, `specs`.

---

## `--validate-path` Semantics

`query-source-tree --validate-path` uses **default-deny**: a path that
matches no governance rule is reported NOT VALID (exit code 1), not
valid-by-omission. The matcher asserts the well-known framework directory
contracts (skills, agents, commands, hooks, rules, specs, the `src/claude/`
authoring tree) and the forbidden patterns (nested agents/commands, backup
files, executable code under `.claude/skills/`). It is a conservative
governance check, not a full filesystem policy engine.

Exit codes: `0` = valid, `1` = not valid / no matching rule, `2` = error.

---

## Token-Cost Note

`_manifest.json`, `governance.json`, and the `components/*.json` files are
small (tens to a few hundred lines) and safe to `Read` directly.
`tree.json` is multi-megabyte. The `query-source-tree` CLI parses the JSON
and returns only the requested slice, so a consumer's token cost is bounded
by its actual need — not by repository size.

---

## Reference

- **ADR-071:** `devforgeai/specs/adrs/ADR-071-*.md` — source-tree AI-optimized decomposed artifact
- **ADR-072:** `devforgeai/specs/adrs/ADR-072-*.md` — tech-stack amendment for structured JSON context artifacts
- **Artifact:** `devforgeai/specs/context/source-tree/` (manifest + tree + components + governance + class-registry)
- **CLI:** `devforgeai-validate query-source-tree` (read-only query layer)
- **Mutability:** `.claude/rules/workflow/configuration-layer-mutability.md` (source-tree/ folder row)
- **Enforcement:** `.claude/hooks/pre-tree-json-read-guard.sh` (PreToolUse[Read], `exit 2`) blocks wholesale `Read` of `devforgeai/specs/context/source-tree/tree.json`. No bypass — `query-source-tree` is the sanctioned mechanism. See ADR-092.

---

**Version:** 1.1 | **Created:** 2026-05-19 | **Updated:** 2026-05-23 (ADR-092) | **Source:** ADR-071 / ADR-072, Phase 7.1
