@event4u/agent-config 9.6.0 → 9.8.0

package/dist/agent-src/rules/onboarding-gate.md

@@ -8,6 +8,8 @@ triggers:
   - path_prefix: ".agent-settings.yml"
 workspaces: [agent-config-maintainer, construction, engineering, finance, founder, gtm, legal-review-prep, ops, product, small-business]
 packs: [meta]
+enforced_by:
+  - "hook:onboarding-gate"
 ---
 
 # Onboarding Gate

package/dist/agent-src/rules/output-discipline.md

@@ -10,6 +10,8 @@ triggers:
   - phrase: "similar pattern"
 workspaces: [engineering]
 packs: [engineering-base]
+enforced_by:
+  - "validator:src/scripts/lint_output_slop.ts"
 ---
 
 # Output Discipline

package/dist/agent-src/rules/persona-governance.md

@@ -25,6 +25,8 @@ validator_ignore:
     reason: "Rule documents the persona authoring tree (.agent-src.uncondensed/personas/) as the deprecation-path operand."
 workspaces: [agent-config-maintainer]
 packs: [meta]
+enforced_by:
+  - "validator:src/scripts/lint_persona_governance.ts"
 ---
 
 # Persona Governance

package/dist/agent-src/rules/preservation-guard.md

@@ -14,6 +14,9 @@ validator_ignore:
     reason: "Rule references the authoring tree as the operand of condensation/preservation."
 workspaces: [agent-config-maintainer]
 packs: [meta]
+enforced_by:
+  - "validator:src/scripts/check_condensation.ts"
+  - "validator:src/scripts/skill_linter.ts"
 ---
 
 # Preservation Guard

package/dist/agent-src/rules/roadmap-progress-sync.md

@@ -11,6 +11,8 @@ routes_to:
   - "guideline:agent-infra/roadmap-progress-mechanics"
 workspaces: [agent-config-maintainer, engineering]
 packs: [meta]
+enforced_by:
+  - "hook:roadmap-progress"
 ---
 
 # Roadmap Progress Sync

package/dist/agent-src/rules/secret-vcs-guard.md

@@ -0,0 +1,106 @@
+---
+type: "auto"
+tier: "2a"
+alwaysApply: false
+description: "About to write a credential into a tracked file or stage/commit one in any VCS (git/svn/hg) — STOP, show the match, ask, offer alternatives; never silently commit, never silently strip"
+triggers:
+  - intent: "writing a credential or API key into a file"
+  - intent: "committing or staging changes that may contain a secret"
+  - keyword: "secret"
+  - keyword: "password"
+  - keyword: "credential"
+  - keyword: "api key"
+  - keyword: "token"
+  - keyword: ".env"
+  - keyword: "commit"
+  - keyword: "git add"
+  - keyword: "svn commit"
+  - keyword: "hg commit"
+  - keyword: "push"
+routes_to:
+  - "skill:secrets-management"
+validator_ignore:
+  - type: "substring"
+    pattern: "../../docs/"
+    reason: "See-also routes to docs/threat-model.md — the canonical attack-surface doc lives there by design."
+workspaces: [engineering]
+packs: [engineering-base]
+enforced_by:
+  - "validator:src/scripts/check_secret_leak.ts"
+---
+
+# Secret-in-VCS Guard
+
+A committed secret is a leaked secret. Once it reaches version control it is in
+the history, in every clone and fork, and — on a public remote — scraped by bots
+within minutes. `git rm` does not un-leak it; only rotation does. The cheapest
+moment to stop it is **before** the write. The agent is upstream of the commit,
+so the agent is the earliest gate.
+
+## The Iron Law
+
+```
+NEVER WRITE A CREDENTIAL INTO A TRACKED (OR TO-BE-TRACKED) FILE, AND NEVER
+STAGE / COMMIT CONTENT CONTAINING ONE — IN ANY VCS (git · svn · hg) —
+WITHOUT STOPPING FIRST.
+DETECT → SHOW THE MATCH (file:line · kind · why risky) → ASK → OFFER ALTERNATIVES.
+NEVER SILENTLY COMMIT A SECRET. NEVER SILENTLY STRIP ONE.
+ALREADY IN HISTORY → ROTATE FIRST. git rm DOES NOT UN-LEAK.
+```
+
+## When it fires
+
+The agent is about to (a) write/edit a value that looks like a live credential
+into a tracked or soon-to-be-tracked file, or (b) `git add` / `git commit` /
+`svn commit` / `hg commit` / push content containing one. Detection uses the
+`secret_detector` library (regex rule pack + Shannon entropy + keyword context):
+AWS/GitHub/Stripe/Google/Slack keys, PEM private keys, JWTs, DB connection URLs
+with embedded credentials, and `password=` / `api_key=` style assignments.
+
+## What to do on a `high`-confidence hit
+
+1. **STOP** — do not write, stage, or commit.
+2. **Show** the match: `file:line`, the kind, a masked preview, and why it is
+   risky. Never echo the full secret back.
+3. **Ask** via numbered options (per [`non-destructive-by-default`](non-destructive-by-default.md) +
+   [`user-interaction`](user-interaction.md)) — e.g. *move it to a secret store
+   (recommended)* / *this is a false positive, add a narrow allow-marker* /
+   *commit anyway (I understand the risk)*. Never decide for the user; never
+   auto-strip.
+4. **Offer the alternative**, tiered to context (full table in
+   [`secrets-management`](../skills/secrets-management/SKILL.md)): solo/local →
+   gitignored `.env` + committed `.env.example`; team/prod → cloud secret manager
+   or Vault/Doppler; k8s/GitOps → SOPS / Sealed Secrets; CI → OIDC over stored
+   creds.
+
+## Already committed / pushed → rotate first
+
+If the secret is already in history, lead with **rotate/revoke the credential
+now** — that is the only action that actually stops the damage. State plainly
+that `git rm` and even a history rewrite do **not** un-leak an already-pushed
+secret; then, if the user wants, point to history purge (`git filter-repo` / BFG)
+plus force-push and collaborator re-clone. See
+[`secrets-management`](../skills/secrets-management/SKILL.md).
+
+## Honesty — one layer, not the whole defense
+
+The agent-side gate is one layer and only covers what the agent writes. Recommend
+the user also enable the non-bypassable nets: the repo's CI secret-scan
+(`check_secret_leak`) and, where available, the host's push-protection.
+
+## When NOT to fire
+
+- `.env.example` / `*.sample` / `*.example` files with placeholder values.
+- A line carrying an audited allow-marker (`# secret-allow` / `// secret-allow` /
+  `<!-- secret-allow -->`) or listed in the repo `.secret-allow` file.
+- Obvious placeholders (`xxxx`, `changeme`, `your-key-here`, `<...>`), test
+  fixtures explicitly marked as such, and non-credential high-entropy strings
+  (hashes, UUIDs, lockfile digests) with no credential keyword nearby.
+
+## See also
+
+- [`secrets-management`](../skills/secrets-management/SKILL.md) — store selection, tiered alternatives, rotation contract, remediation ordering.
+- [`security-sensitive-stop`](security-sensitive-stop.md) — threat-model before editing a secrets surface (fires first, broader).
+- [`tool-safety`](tool-safety.md) — "no hidden credentials" in shipped files.
+- [`non-destructive-by-default`](non-destructive-by-default.md) — the commit/push confirmation floor this builds on.
+- [`lethal-trifecta-guard`](lethal-trifecta-guard.md) — secrets are the private-data leg of the trifecta.

package/dist/agent-src/rules/security-sensitive-stop.md

@@ -100,4 +100,4 @@ Authorization and tenancy bugs are often invisible in logs and fire silently
 until an auditor or attacker finds them. The cheapest moment to catch them
 is before the first edit — this rule makes that the default path.
 
-See also: `threat-modeling` · `authz-review` · `data-flow-mapper` · `minimal-safe-diff` · `think-before-action` · [`untrusted-input-defense`](untrusted-input-defense.md) · [`lethal-trifecta-guard`](lethal-trifecta-guard.md) · [`docs/threat-model.md`](../../docs/threat-model.md).
+See also: `threat-modeling` · `authz-review` · `data-flow-mapper` · `minimal-safe-diff` · `think-before-action` · [`untrusted-input-defense`](untrusted-input-defense.md) · [`lethal-trifecta-guard`](lethal-trifecta-guard.md) · [`secret-vcs-guard`](secret-vcs-guard.md) · [`docs/threat-model.md`](../../docs/threat-model.md).

package/dist/agent-src/rules/skill-quality.md

@@ -8,6 +8,8 @@ routes_to:
   - "guideline:agent-infra/skill-quality-checklist"
 workspaces: [agent-config-maintainer]
 packs: [meta]
+enforced_by:
+  - "validator:src/scripts/skill_linter.ts"
 ---
 
 # Skill Quality

package/dist/agent-src/rules/source-confidentiality.md

@@ -19,6 +19,8 @@ validator_ignore:
     reason: "Rule names the linter/denylist asset that necessarily holds the tokens."
 workspaces: [agent-config-maintainer]
 packs: [meta]
+enforced_by:
+  - "validator:src/scripts/check_no_external_sources.ts"
 ---
 
 # Source Confidentiality

package/dist/agent-src/rules/source-of-truth.md

@@ -11,6 +11,8 @@ triggers:
   - path_prefix: ".cursor/"
 workspaces: [agent-config-maintainer]
 packs: [meta]
+enforced_by:
+  - "validator:src/scripts/check_condensation.ts"
 ---
 
 # Source of Truth

package/dist/agent-src/rules/telegraph-speak.md

@@ -6,6 +6,8 @@ triggers:
   - intent: "any reply"
 workspaces: [agent-config-maintainer]
 packs: [meta]
+enforced_by:
+  - "observer:maintainer-review"
 ---
 
 # Telegraph Speak

package/dist/agent-src/rules/token-optimizer-maintenance.md

@@ -17,6 +17,8 @@ validator_ignore:
     reason: "Rule lists the authoring-tree paths that must stay in sync with the catalog."
 workspaces: [agent-config-maintainer]
 packs: [meta]
+enforced_by:
+  - "validator:src/scripts/check_token_optimizer_freshness.ts"
 ---
 
 # Token Optimizer Maintenance

package/dist/agent-src/rules/tool-safety.md

@@ -65,3 +65,4 @@ If a skill needs a tool that is not in the registry:
 - [`lethal-trifecta-guard`](lethal-trifecta-guard.md) — an over-broad tool grant is the standing egress leg of the lethal trifecta (OWASP ASI). Least Agency here breaks that leg by construction.
 - [`supply-chain-intake`](../skills/supply-chain-intake/SKILL.md) — the MCP-server intake gate applies this rule's Least-Agency tool-grant review before a new server is connected.
 - [`untrusted-input-defense`](untrusted-input-defense.md) — the least-agency + human-approval controls (OWASP LLM06 / ASI excessive-agency) that bound an untrusted-content path.
+- [`secret-vcs-guard`](secret-vcs-guard.md) — a raw credential in a shipped file is the "no hidden credentials" violation this rule names; that rule blocks it at write/commit time.

package/dist/agent-src/rules/verify-before-complete.md

@@ -7,6 +7,8 @@ load_context:
   - ../contexts/execution/verification-mechanics.md
 workspaces: [engineering]
 packs: [engineering-base]
+enforced_by:
+  - "hook:verify-before-complete"
 ---
 
 # Verify Before Completion

package/dist/agent-src/skills/adr-create/SKILL.md

@@ -104,6 +104,21 @@ Use the surface-specific template. All sections are required; "—"
 is acceptable for genuinely empty Alternatives or References blocks
 but never for Status, Context, Decision, or Consequences.
 
+**`review_trigger` is required and it names a CONDITION, not a date.** A
+decision is a call made under conditions that held at the time; the trigger
+records which change would make it worth re-deciding. "Review annually" is
+ignored by everyone and rots into ceremony —
+`check_adr_frontmatter.ts` rejects bare cadences for exactly that reason. Write
+the event: *"when a second consumer reports the same preservation surprise"*,
+*"when a host ships a native primitive for this"*, *"if the measured lift drops
+below the pre-registered threshold"*. Enforced from 2026-07-25 forward; earlier
+ADRs are grandfathered by date.
+
+When you later reopen one, say which **premise moved** and what evidences the
+move — not "we were wrong". If the original was right under its own conditions,
+record that too. A premise that turns out false while the decision stays correct
+gets a logged correction block, never a silent edit.
+
 **Flat-surface template** (`docs/decisions/ADR-NNN-<slug>.md`):
 
 ```markdown
@@ -115,6 +130,7 @@ decision: <slug>
 supersedes: — | ADR-MMM
 superseded_by: — | ADR-MMM
 phase: <roadmap> · <phase-id>
+review_trigger: <the CONDITION that would reopen this decision>
 ---
 
 # ADR-NNN — <Decision Title>
@@ -158,7 +174,7 @@ the area's contract from the README in
 - Per-area: `./scripts-run src/scripts/audit_adr_coverage --check` exits 0.
 - The project's CI / quality pipeline passes — locally only when
   `quality.local_auto_run: true`; under the default (`false` / missing)
-  remote CI is the gate, no local pipeline run.
+  remote CI is the gate and no local pipeline run happens.
 
 ## Rubric pass (optional, surfacing-only)
 

package/dist/agent-src/skills/agent-docs-writing/SKILL.md

@@ -189,29 +189,47 @@ After making changes, check if docs need updating:
 - **Structural changes** → update affected docs in `./agents/`
 - **New patterns** → update or create guideline docs
 
-## Doc sync check (after code changes)
+## Doc-Impact — the mandatory check after every code change
 
-After completing a significant code change, run this mental checklist:
+This is the detection procedure the [`downstream-changes`](../../rules/downstream-changes.md)
+§ Doc-Impact obligation points at. **Run it after every code change** — the
+*detection* is non-optional; the human still confirms the actual edit.
 
-| What changed | Doc to check |
+**Step 1 — did a public surface change?** Framework-agnostic surface list:
+
+| Public surface changed | Doc that describes it — update in the same change |
 |---|---|
-| Database schema (migration) | `agents/reference/docs/database-setup.md` |
-| New API endpoint | OpenAPI annotations, `AGENTS.md` API section |
-| New module created | Create `{module_root}/{Module}/{agent_folder}/` (resolve via `modules.root_paths` + `modules.agent_folder`) |
-| Service/repository signature changed | Check if referenced in `agents/reference/docs/services-and-repos.md` |
-| New environment variable | `.env.example`, `AGENTS.md` environment section |
-| Docker/compose change | `agents/reference/docs/docker.md`, `Makefile` documentation |
-| New Artisan command | `AGENTS.md` commands section |
-| New pattern/convention introduced | Relevant guideline in `.augment/guidelines/` |
-
-**When unsure** — ask with numbered options:
+| HTTP route / endpoint (Laravel `routes/`, Next.js `app/api`, FastAPI/Express handlers, Go mux) | OpenAPI / API reference, `README` usage, `AGENTS.md` API section |
+| Exported function / class / method signature | The doc/example that calls it; `agents/reference/docs/services-and-repos.md` if referenced |
+| CLI command or flag | `README` usage, `AGENTS.md` commands section, `--help` text |
+| Config / settings key | Settings doc, `README` config section, schema/example file |
+| Environment variable | `.env.example`, `AGENTS.md` environment section |
+| DB schema / migration | `agents/reference/docs/database-setup.md` |
+| Event payload / job constructor | The listener/consumer doc that documents the contract |
+| New module | `{module_root}/{Module}/{agent_folder}/` (resolve via `modules.root_paths` + `modules.agent_folder`) |
+| New pattern / convention | Relevant guideline in `.augment/guidelines/` |
+| Architectural decision | [`adr-create`](../adr-create/SKILL.md) — numbered ADR + index regen |
+
+**Step 2 — apply the fire/no-fire test.** Drift is a **falsifiable-claim
+contradiction**, not incompleteness:
+
+- **FIRE** (doc is now wrong — a reader would be misled): endpoint no longer
+  exists, wrong return type, renamed key, removed flag, broken code example.
+- **DO NOT FIRE** (completeness / quality only): the doc is high-level and
+  omits a new internal detail it never claimed to list; "could be clearer".
+
+**Step 3 — escape hatch.** Refactor-only / no public-surface change → no doc
+obligation. Surface changed but genuinely needs no doc edit → state the
+one-line reason; never edit a doc just to satisfy the rule (false-positive
+fatigue is worse than a missed nit).
+
+**When a doc edit IS needed but you are unsure of the wording** — flag it with
+numbered options; do NOT auto-rewrite prose without the user's knowledge:
 ```
 > 1. Yes — update the docs
-> 2. No — leave as-is
+> 2. No — leave as-is (reason: …)
 ```
 
-Do NOT auto-update docs without the user's knowledge. Flag what needs updating and let the user decide.
-
 ## Rules
 
 - All `.md` files must be in **English**.

package/dist/agent-src/skills/agents-md-thin-root/SKILL.md

@@ -21,7 +21,7 @@ packs:
 
 Use when:
 - Editing `AGENTS.md` at the package root.
-- Editing `packages/core/.agent-src.uncondensed/templates/AGENTS.md` (consumer-shipped template).
+- Editing `src/agent-src/templates/AGENTS.md` (consumer-shipped template).
 - Reviewing a PR that changes either file.
 - Running `/optimize/agents`.
 - A budget meter (`scripts/measure_augment_budget.ts`) flags the package-root AGENTS.md as the dominant cost.
@@ -29,7 +29,7 @@ Use when:
 ## Do NOT
 
 - Edit `.github/copilot-instructions.md` with this skill (use `copilot-agents-optimization` instead).
-- Edit other `.md` files under `.augment/`, `packages/*/.agent-src.uncondensed/`, or `agents/` with this skill.
+- Edit other `.md` files under `.augment/`, `src/`, or `agents/` with this skill.
 - Add a section to AGENTS.md without first checking whether an outboard target already exists in `agents/settings/contexts/` or `docs/contracts/`.
 - Replace prose with a bare link `[label](path)` — every pointer needs a *why*-clause ≥ 60 chars or it does not count toward the 40 % ratio.
 - Reuse the package-root anatomy in the consumer template — caps and target paths differ.
@@ -47,7 +47,7 @@ Every entry describes **what** the project does or **where** to learn more — n
 | File | FAIL above | WARN above | Target |
 |---|---|---|---|
 | `AGENTS.md` (package root) | 3,000 chars | 2,800 chars | ≤ 2,800 |
-| `packages/core/.agent-src.uncondensed/templates/AGENTS.md` (consumer) | 2,500 chars | 2,300 chars | ≤ 2,300 |
+| `src/agent-src/templates/AGENTS.md` (consumer) | 2,500 chars | 2,300 chars | ≤ 2,300 |
 
 Char-count is raw file size (`wc -c`), frontmatter included. Enforcement: `scripts/lint_agents_md.ts` (Phase 7), wired into the package's CI pipeline via the `lint-agents-md` task. WARN is a soft signal in CI; FAIL blocks merge.
 
@@ -85,7 +85,7 @@ Every substantive pointer specifies, on the same line or the immediately followi
 
 ## The contract — emergency-triage block
 
-Every Thin-Root AGENTS.md MUST contain an **Emergency Triage** section verbatim from `packages/core/.agent-src.uncondensed/contexts/contracts/emergency-triage-block.md` (Phase 6.4 will create that file as the canonical source). The block lists the five questions a host agent answers from the root file alone when network / tool access is degraded:
+Every Thin-Root AGENTS.md MUST contain an **Emergency Triage** section verbatim from `src/agent-src/contexts/contracts/emergency-triage-block.md` (Phase 6.4 will create that file as the canonical source). The block lists the five questions a host agent answers from the root file alone when network / tool access is degraded:
 
 1. What is this repository?
 2. What language(s) does this repository accept?
@@ -99,22 +99,22 @@ Each answer must fit on one line. The block exists so the root never silently de
 
 1. **Measure baseline.** `wc -c AGENTS.md` and `./scripts-run src/scripts/measure_augment_budget`. Record current char-count and the gap to 2,200 / 2,500.
 2. **Inventory sections.** List every `## ` heading and its char-count. Mark each as `keep-inline` (Iron-Law-adjacent, ≤ 200 chars, no good outboard target) or `outboard-candidate` (longer-form prose, table-only sections, narrative).
-3. **Identify outboard targets.** For each `outboard-candidate`, name the destination — `packages/core/.agent-src.uncondensed/contexts/`, `docs/contracts/`, an existing rule body, an existing skill body. Never invent a new top-level directory.
+3. **Identify outboard targets.** For each `outboard-candidate`, name the destination — `src/agent-src/contexts/`, `docs/contracts/`, an existing rule body, an existing skill body. Never invent a new top-level directory.
 4. **Move content; insert pointer.** Cut the section into the target file. Replace it in AGENTS.md with a single substantive pointer per anatomy above. Verify the *why*-clause length.
 5. **Re-measure.** `wc -c AGENTS.md` again. If above 2,200, repeat steps 2–4 on the next-largest section. Above 2,500 = must outboard further before commit.
 6. **Validate pointer ratio.** Count non-blank lines and substantive-pointer lines. Ratio < 0.40 = collapse decorative or boilerplate lines into a single pointer or remove.
-7. **Verify emergency-triage block.** Diff the in-file block against `packages/core/.agent-src.uncondensed/contexts/contracts/emergency-triage-block.md`. Drift = revert to canonical.
+7. **Verify emergency-triage block.** Diff the in-file block against `src/agent-src/contexts/contracts/emergency-triage-block.md`. Drift = revert to canonical.
 8. **Run lints.** `task lint-agents-md && task check-refs && task lint-skills`. All green before commit.
 
 ## Procedure — apply Thin-Root to consumer template
 
-Same procedure, applied to `packages/core/.agent-src.uncondensed/templates/AGENTS.md`. Hard cap shifts to 2,000 / 1,700. The consumer template intentionally lacks the package-self-references — its pointers target files that exist in the **consumer's** repo (`.augment/skills/`, `agents/settings/contexts/`, ...), not this package's authoring tree.
+Same procedure, applied to `src/agent-src/templates/AGENTS.md`. Hard cap shifts to 2,000 / 1,700. The consumer template intentionally lacks the package-self-references — its pointers target files that exist in the **consumer's** repo (`.augment/skills/`, `agents/settings/contexts/`, ...), not this package's authoring tree.
 
 ## Gotchas
 
-- **Outboarding to a new top-level dir.** Inventing `agents/explainers/` or `docs/notes/` for the moved content silently widens the contract surface. Outboard only into `packages/core/.agent-src.uncondensed/contexts/`, `docs/contracts/`, an existing rule body, or an existing skill body.
+- **Outboarding to a new top-level dir.** Inventing `agents/explainers/` or `docs/notes/` for the moved content silently widens the contract surface. Outboard only into `src/agent-src/contexts/`, `docs/contracts/`, an existing rule body, or an existing skill body.
 - **Pointer-ratio inflation by decoration.** Adding boilerplate "Browse all skills" / "See also" links to lift the ratio above 40 % defeats the purpose. The lint counts only substantive pointers (with a *why*-clause ≥ 60 chars); decorative links get filtered out and the ratio drops back below threshold.
-- **Emergency-triage drift.** Editing the in-file emergency-triage block instead of the canonical `packages/core/.agent-src.uncondensed/contexts/contracts/emergency-triage-block.md` causes the package-root and consumer-template versions to diverge silently. Always edit the canonical file and let the lint diff pull both back in sync.
+- **Emergency-triage drift.** Editing the in-file emergency-triage block instead of the canonical `src/agent-src/contexts/contracts/emergency-triage-block.md` causes the package-root and consumer-template versions to diverge silently. Always edit the canonical file and let the lint diff pull both back in sync.
 - **Cap inversion under WARN.** A 2,250-char AGENTS.md (above 2,200 WARN, below 2,500 FAIL) is a yellow signal not a green one — every additional sentence raises the probability of the next FAIL. Treat WARN as the spend boundary, not a buffer.
 - **Char-count includes frontmatter.** `wc -c` counts every byte including the YAML preamble, blank lines, and the trailing newline. Stripping a section to "look smaller" without re-running `wc -c` understates the true budget impact.
 - **Path enumeration.** A run of three or more bare `` `path/to/dir/` `` bullets without *why*-clauses is the classic re-bloat pattern. The lint emits a WARN at ≥ 3 such lines. Collapse them into one capability-style pointer — see the recipe in [`agents-md-anatomy § Iron Law`](../../contexts/contracts/agents-md-anatomy.md#iron-law--capabilities-over-structure).

package/dist/agent-src/skills/code-intelligence/SKILL.md

@@ -0,0 +1,94 @@
+---
+model_tier: inherit
+name: code-intelligence
+description: "Route codebase-structure questions (who calls X, where used, what imports, change-impact) to a code-graph first, grep fallback. Triggers 'who calls', 'where is this used', 'call graph'."
+source: package
+domain: engineering
+workspaces:
+  - engineering
+packs:
+  - meta
+requires_skills:
+  - source-discovery
+---
+
+# code-intelligence
+
+> For a **structure** question — *who calls X*, *where is Y used*, *what
+> imports Z*, *what breaks if I change this symbol* — a code-graph answers far
+> more precisely than a blind `grep`, at a fraction of the tokens. This skill
+> routes such questions to the native code-graph engine (ADR-124, Class A) or a
+> consumer-shipped index first, and falls back to grep **with a stated reason**
+> when the graph cannot answer. It is the executable side of
+> [`external-code-graph-interop`](../../rules/external-code-graph-interop.md):
+> *orchestrator first, owner where it wins*.
+
+## When to use
+
+- The question is about **relationships between code symbols**, not content:
+  callers/callees, references, imports, inheritance, change-impact.
+- You are about to `grep`/`Read` across many files to reconstruct a call or
+  import graph by hand.
+
+**When NOT to use:** content/semantic questions ("what does this function
+*mean*", "find the string 'password'"), single-file edits, or a repo with no
+code-graph and no appetite to build one — plain `grep`/read is right there.
+
+## Procedure
+
+1. **Detect the source.** `code_graph detect` — is a fresh consumer `graph.json`
+   or native cache present? (A consumer-shipped fresh index wins; the native
+   engine covers stale-or-absent — ADR-124 § 2.)
+2. **Build if absent and worthwhile.** No graph + a repo in the launch set
+   (PHP / TS / JS)? `code_graph build` (deterministic, LLM-free, ~seconds).
+   Skip for a one-off question in an unsupported stack — grep instead.
+3. **Query.** Pick the verb:
+   - `code_graph query <symbol>` — direct relations of a symbol.
+   - `code_graph affected <symbol>` — reverse: who calls / references it (the
+     "impact of changing X" question). `--since <ref>` seeds from a git diff.
+   - `code_graph path <a> <b>` — how two symbols connect.
+   - `code_graph explain <symbol>` — 2-hop neighbourhood.
+   Pass `--budget <tokens>` to cap output.
+4. **Read the confidence.** `EXTRACTED` = syntactic fact; `INFERRED` =
+   hierarchy-resolved; `AMBIGUOUS` = dynamic dispatch / facade, carries
+   candidates — treat its target as *one of* the candidates, never as certain.
+5. **Fall back honestly.** If the graph has no entry for the symbol, grep — and
+   say so: *"the graph has no entry for X, so I grepped."*
+
+## Output
+
+Every answer built with this skill MUST:
+
+- **Name the source** that answered — `native`, `consumer`, or `grep-fallback`
+  — so the reader knows the provenance and freshness of the relationship claim.
+- **Preserve the confidence class** for each relationship surfaced — never
+  present an `AMBIGUOUS` edge as a definite call; list its candidates or say
+  "ambiguous (dynamic dispatch)".
+
+## Gotcha
+
+- **A stale graph lies confidently.** If `detect` reports the index is N commits
+  behind, rebuild (`code_graph build --update`) before trusting relationship
+  answers, or say the answer is from a stale index.
+- **Dynamic dispatch is honestly ambiguous.** On a Laravel/JS codebase most
+  method-call edges are `AMBIGUOUS` (facades, injected services, `$obj->m()`).
+  That is the engine being honest, not broken — do not "resolve" them yourself
+  by guessing.
+
+## Do NOT
+
+- Do NOT rebuild a **fresh** consumer-shipped index — query it (interop
+  courtesy).
+- Do NOT block or defer a read waiting on the graph — it is an accelerator, not
+  a gate.
+- Do NOT treat the cache as a source of truth for anything beyond the last
+  build; it is a rebuildable artifact.
+
+## See also
+
+- [`external-code-graph-interop`](../../rules/external-code-graph-interop.md) —
+  the rule that routes structure questions here.
+- [`source-discovery`](../source-discovery/SKILL.md) — evidence-before-structure
+  discipline; the graph is one evidence source, still confirmed against the real
+  code when load-bearing.
+- `src/scripts/code_graph/` — the engine (build / query / detect / affected).