git:20260821.5573877 to git:20260915.3d7652b

27 added, 138 removed. Audit A to A.

---

name: repo-map

- description: "Use when a Git or non-Git workspace needs a machine-queryable repository asset scan, impact/relationship query, coverage or drift check, or an optional derived navigation view; not for task-local discovery, source changes, repository-guidance authoring, or change review."

+ description: "Use when a Git or non-Git workspace needs a machine-queryable repository asset scan, impact/relationship query, coverage or drift check, or optional derived navigation view; not for task-local discovery, source changes, guidance authoring, or review."

---

# Repository Map

- ## Overview

- Own two read-only capabilities, `repository.asset.query` and

- `repository.map.render`, plus the artifact-writing `repository.asset.scan` capability.

- The scan never changes repository source, documentation, or Git, but its host adapter

- must own an isolated run-local SQLite/cache path and declare that write explicitly.

- The authoritative result is a

- versioned Repository Asset Graph snapshot with stable asset and edge references,

- explicit basis, scope, exclusions, coverage, conflicts, and unresolved records. A

- Markdown or HTML map is an optional derived view over that snapshot; it is never the

- gate, completeness proof, or source of truth.

- Project source, contracts, configuration, Product Markdown, `DESIGN.md`, and local UI

- contracts retain their native authority. The graph indexes identity and relationships

- without copying their bodies. Runtime claims and delivery status belong to typed

- delivery observations, not the asset graph.

- Keep canonical/source owner, build/deploy owner, runtime service identity, and

- gateway/registration alias as separate fields when they differ.

- ## Workflow

+ ## Entry Gate

- 1. Resolve the requested capability, repository root, nested Git roots, symbolic scan

- scope, exclusions, and current basis. Reject absolute, parent-escaping, or symlink-

- escaping scope. Read effective repository guidance and inspect Worktree state before

- broad reads.

- 2. Preflight a compatible graph runtime for the selected capability and schema version.

- If none exists, return `CAPABILITY_MISSING` with the missing capability/version and

- recovery hint. Do not fall back to a hand-written Markdown map and imply equivalent

- coverage.

- 3. For `repository.asset.scan`, require a host-owned, repository-excluded run-local

- store and run bounded extractors against source, contracts,

- manifests, configuration, tests, and declared authorities. Record extractor identity

- and version, confidence, evidence status, content hash, and last-seen basis for every

- record. Keep runtime observations out of the graph.

- 4. Persist the local `urn:forgeway:repository-asset-snapshot:v1` snapshot and emit a

- portable `urn:skills:asset-map-result:v1` envelope containing its compatible

- snapshot/scan ID,

- basis, included scope, exclusions, coverage denominator and numerator, unresolved

- records, conflicts, stale/tombstoned records, and validation result. A partial scan

- remains partial even when all attempted extractors succeed.

- 5. For `repository.asset.query`, consume an exact compatible snapshot reference and a

- bounded query such as asset lookup, relationship traversal, consumer lookup, reverse

- impact, authority conflict, or drift. Preserve the snapshot basis in the result; a

- query against a stale basis is labeled stale rather than silently refreshed. If the

- caller already has a maintained record that matches the exact current file, owner,

- and function for the requested feature, return control without running a query; the

- implementation owner verifies that target directly in current source. For an

- unresolved cross-owner implementation edge, return only one compact slice: owner,

- entry, decisive registration/call path, affected consumers, focused check, basis,

- scope/exclusions, and unresolved conflicts. This is navigation, not a new sidecar or

- implementation authority.

- 6. Before any absence claim, report the searched scope, extractor coverage, unresolved

- records, and exclusions. A query miss means `Not found in this snapshot`, not proof

- that no implementation exists.

- 7. For `repository.map.render`, consume an exact snapshot/query result and render only

- the requested navigation projection. Include snapshot ID, basis, coverage, and a

- regeneration command or capability reference. Do not add facts that are absent from

- the machine result.

- 8. Validate schema, references, authority uniqueness, edge endpoints, path containment,

- and snapshot/basis consistency. Report drift and conflicts as typed failures; do not

- repair source, approve authorities, or mutate Git.

- 9. When the host provides Forgeway delivery integration, bind the invocation to an

- immutable Run input reference and PackageManifest/basis reference, then attach the

- typed result as an Observation. Provider, model, executable, and session attribution

- remain run-local facts. Absence of that integration does not weaken graph validation,

- but delivery state remains `Not verified`.

+ Own bounded repository asset scan, graph query, coverage/drift check, and derived

+ navigation rendering. Require a compatible graph runtime, repository root, safe scope,

+ and exact basis. Never substitute a hand-written map when the runtime is unavailable.

- ## Modes

+ ## Route Map

- - **Asset scan:** produce or incrementally refresh a validated graph snapshot.

- - **Asset query:** answer bounded identity, relation, authority, reuse, consumer, impact,

- coverage, unresolved, conflict, or drift questions against one snapshot.

- - **Implementation navigation query:** answer one unresolved owner, reuse, consumer,

- or impact edge from an existing compatible snapshot; never scan or implement.

- - **Derived render:** create a disposable Markdown/HTML navigation view from a typed

- result. Deleting the view must not lose graph facts.

+ | Request condition | Read | Result |

+ | --- | --- | --- |

+ | Build/refresh an unambiguous graph snapshot | [graph operation gates](references/graph-operation-gates.md) and [usage](references/usage.md) | Validated bounded snapshot |

+ | Query identity, relation, consumer, impact, authority, coverage, conflict, or drift | [graph operation gates](references/graph-operation-gates.md) and [usage](references/usage.md) | Basis-qualified compact result |

+ | Root ownership or bounded source resolution is ambiguous | [ambiguity checklist](references/checklist.md) | Resolved bounded roots/source or safe stop |

+ | Need language/profile extraction detail | [frontend inventory](references/frontend-inventory.md), [API contract map](references/api-contract-map.md), and/or [Java build map](references/java-build-and-dependency-map.md) | Profile-specific graph evidence |

+ | Cross-project/repository signal applies | [project grounding](references/project-grounding.md) | Qualified boundary result |

+ | Render requested navigation view | [prompt templates](references/prompt-templates.md) | Derived, disposable view |

- ## Hard Rules

+ ## Invariants

- - Keep this Skill read-only with respect to repository source, documentation, and Git;

- only the bounded scan store or requested derived view may be written.

- - Never make Markdown the authoritative scan result or a required delivery gate.

- - Never treat directory enumeration or a selective reading path as complete repository

- cognition.

- - Never scan, refresh, or render a map merely because a task-local implementation needs

- navigation. Use an existing compatible snapshot for one bounded unresolved edge; if

- none exists, let the implementation owner use targeted current source.

- - Never query merely to reconfirm an already matched same-file, same-owner, same-function

- record.

- - Never copy Product, design, UI, source-contract, schema, or runtime bodies into the

- graph; store stable identity, location, hash, authority role, and edges.

- - Never infer runtime success, review approval, delivery, deployment, or production

- verification from static graph records.

- - Never hand-author stable IDs or relationship edges to compensate for a missing or

- failed extractor. Emit unresolved/conflict records and the responsible extractor.

- - Never erase renamed or deleted assets needed by historical Runs; use tombstones or

- versioned snapshot history according to the graph retention policy.

- - Never accept a snapshot whose basis, schema version, producer, validator, drift

- policy, or retirement rule is absent.

- - If an already maintained non-LLM structured projection is encountered, treat it as

- navigation only and require its named owner, producer, non-LLM consumer, semantic

- version, executable validator, drift policy, and retirement rule. Otherwise ignore

- it and use the validated graph/native source chain.

- - Do not create map sidecars for machine convenience without a named owner, producer,

- non-LLM consumer, semantic version, executable validator, drift policy, and

- retirement rule.

- - Preserve unrelated local changes and secrets. Do not export source bodies, credentials,

- or sensitive configuration into graph snapshots or derived views.

- - Say `Not verified` for unchecked runtime or delivery claims and distinguish it from

- `false`, `conflict`, `stale`, and `Not found in this snapshot`.

+ - Reject scope escape; isolate and exclude run-local cache from scans.

+ - A graph/query miss is bounded `Not found`, never proof of absence; stale snapshots remain stale.

+ - Index native authorities without copying or authoring repository guidance, product/design contracts, source, runtime facts, or Git state.

- ## Output Contract

+ ## Output Map

- Return the selected capability ID/version, repository and Git roots, basis/PackageManifest

- reference when available, scan scope and exclusions, snapshot/scan ID, typed result

- schema, validation, coverage, unresolved/conflict/stale counts, query and bounded result,

- derived-view path when requested, and every `Not verified` boundary. If Forgeway

- integration is active, also return Run and Observation references; never claim a Receipt

- or delivery level that this read-only owner did not produce.

+ Return capability/version, basis, scope/exclusions, snapshot/query identity, coverage,

+ unresolved/conflict/stale state, and `Not verified` boundaries; renders name their input.

- ## References

+ ## Reference Map

- - See [references/checklist.md](references/checklist.md) only for ambiguous root and

- bounded source-resolution procedures.

- - See [references/project-grounding.md](references/project-grounding.md) when static

- repository relations cross packaging, integration, compatibility, or deployment-

- target boundaries; runtime results still belong to delivery observations.

- - See [references/frontend-inventory.md](references/frontend-inventory.md) only to

- select frontend extractor/query scope; do not emit its legacy Markdown inventory as

- authority.

- - See [references/api-contract-map.md](references/api-contract-map.md) only to locate

- native API authority and consumer edges without copying schemas.

- - See [references/java-build-and-dependency-map.md](references/java-build-and-dependency-map.md)

- only to select Java build/dependency extractor scope; any tabular examples are query

- projections, not an authoritative output contract.

- - See [references/reuse-index.md](references/reuse-index.md) only to translate legacy

- reuse questions into graph consumer/registration queries; do not author its old

- Markdown rows.

- - See [references/project-guidance.md](references/project-guidance.md) only to identify

- and reroute an explicit repository-guidance authoring request; this read-only Skill

- does not perform that write mode.

- - See [references/prompt-templates.md](references/prompt-templates.md) only when

- composing a bounded scan/query/render request.

- - See [references/usage.md](references/usage.md) and

- [references/eval-cases.md](references/eval-cases.md) for usage and routing checks.

+ - Read [graph operation gates](references/graph-operation-gates.md) for every scan/query. Read [ambiguity checklist](references/checklist.md) only when root ownership or bounded source resolution is ambiguous.

+ - Read [usage](references/usage.md) for route examples and owner boundaries.

+ - Read [frontend inventory](references/frontend-inventory.md), [API contract map](references/api-contract-map.md), [Java build map](references/java-build-and-dependency-map.md), [project grounding](references/project-grounding.md), [reuse index](references/reuse-index.md), and [prompt templates](references/prompt-templates.md) only when applicable.

+ - Read [Project guidance](references/project-guidance.md) only to recognize and reroute an explicit guidance create/bootstrap/update request; never use it as authoring instructions in `repo-map`.

+ - Maintainers only: read [eval cases](references/eval-cases.md); do not load it during ordinary runtime.