Repo Map

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

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.

Modes

• 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.

Hard Rules

• 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.

Output Contract

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.

References

• See references/checklist.md only for ambiguous root and bounded source-resolution procedures.
• See 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 only to select frontend extractor/query scope; do not emit its legacy Markdown inventory as authority.
• See 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 only to select Java build/dependency extractor scope; any tabular examples are query projections, not an authoritative output contract.
• See 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 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 only when composing a bounded scan/query/render request.
• See references/usage.md and references/eval-cases.md for usage and routing checks.