Agent Instruction Stack Resolver

See which repository AI instructions statically apply to a path—and which paths gain or lose guidance after a change.

Static model, not runtime prompt simulation.

中文 · English · API · Rules · Design

See which files gain or lose guidance before an instruction change merges. Think Terraform plan for repository AI instructions.

Why

Repository guidance is increasingly split across root and nested AGENTS.md, Copilot repository instructions, scoped .instructions.md files, prompt assets, custom-agent assets, and VS Code settings references. A small scope edit can change the guidance seen by many paths, but a normal code diff does not show that blast radius.

This CLI turns those files into deterministic, reviewable evidence:

• resolve explains the statically applicable instruction set for one path.
• reach shows the current static reach of one instruction source.
• snapshot, diff, and impact show which path stacks changed against a compatible baseline.
• coverage and conflicts surface conservative, CI-friendly findings.
• Markdown, JSON, JUnit, and SARIF outputs keep raw instruction bodies out of public reports.

Quick start from source

Requirements: Node.js 20 or newer.

The package is not published to the npm registry yet. All commands below run from a source checkout.

npm ci
npm run build
node dist/bin.js resolve examples/risky-repo src/api/user.ts --fail-on none

The package binary name is agent-instruction-stack-resolver; source-checkout examples use node dist/bin.js so they never depend on npm's executable resolution.

5-minute Aha: plan an instruction scope change

The fixture changes .github/instructions/review-contract.instructions.md from applyTo: src/api/** to applyTo: tests/**.

npm ci
npm run build
node dist/bin.js snapshot examples/impact-before --output before.json --fail-on none
node dist/bin.js diff examples/impact-after --baseline before.json --fail-on none
node dist/bin.js impact examples/impact-after .github/instructions/review-contract.instructions.md --baseline before.json --fail-on none

Derived summary of the two reports:

1 instruction source changed
2 existing path stacks changed

+ tests/user.test.ts   gained the instruction
- src/api/user.ts      lost the instruction

The generated machine-readable examples are committed as the diff report and the source impact report.

Commands

Command	Question answered
scan <repo>	What supported instruction assets, settings references, content paths, findings, and scan diagnostics exist?
resolve <repo> <path>	Which sources statically apply to this contained path under the selected profile?
reach <repo> <instruction-file>	Which currently scanned content paths does this source statically reach?
snapshot <repo> [--output <new-file>]	What complete, deterministic baseline represents the current source and path-stack state?
diff <repo> --baseline <file>	Which sources and content-path stack signatures changed since the baseline?
impact <repo> <instruction-file> --baseline <file>	Which paths gained, lost, or retained a changed revision of this source?
coverage <repo>	Which important content paths lack path-scoped coverage?
conflicts <repo>	Which conservative claim patterns conflict on at least one shared path?

Examples:

node dist/bin.js scan examples/risky-repo --fail-on none
node dist/bin.js resolve examples/risky-repo src/api/user.ts --json --fail-on none
node dist/bin.js reach examples/risky-repo .github/instructions/backend.instructions.md --fail-on none
node dist/bin.js snapshot examples/impact-before --output before.json --fail-on none
node dist/bin.js diff examples/impact-after --baseline before.json --json --fail-on none
node dist/bin.js impact examples/impact-after .github/instructions/review-contract.instructions.md --baseline before.json --json --fail-on none
node dist/bin.js coverage examples/risky-repo --junit --fail-on none
node dist/bin.js conflicts examples/risky-repo --sarif --fail-on none

Run node dist/bin.js --help for output, gate, profile, baseline, and scanner-limit options.

Static profile contracts

Profiles are versioned assumptions over repository evidence—not host emulators.

Profile	Automatically applicable kinds	Inventory-only behavior
vscode-copilot-static	root/nested AGENTS.md, .github/copilot-instructions.md, scoped .instructions.md with known path applicability	prompts, custom agents, settings references, and scoped instructions without applyTo do not enter a path set automatically
portable-agents-md	root and nested AGENTS.md	all other supported kinds remain inventory evidence
inventory	none	discovers every supported source kind without asserting path applicability

The reported order is a deterministic display order. Host runtime precedence and prompt assembly are explicitly unknown.

What the model does—and does not do

Modeled from repository evidence:

• root AGENTS.md and .github/copilot-instructions.md as repository-global evidence;
• nested AGENTS.md as directory-subtree evidence;
• scoped instructions with applyTo as bounded, case-sensitive minimatch evidence;
• supported VS Code instruction settings as references that are loaded safely and remain inventory-only;
• content-body, scope, status, and ordering revisions in path-stack signatures.

Not modeled:

• user, organization, extension, or dynamically injected instructions;
• runtime prompt assembly, host precedence, model behavior, or instruction compliance;
• semantic prompt quality or general natural-language contradiction detection;
• generated or ignored build trees such as .git, node_modules, dist, coverage, .next, and build.

The tool does not execute agent hosts, call an LLM, run repository code, or make network requests.

Parsing and matching contract

• Frontmatter is strict YAML: duplicate keys and aliases are rejected.
• applyTo accepts a comma-separated scalar or a string array, with at most 64 patterns and 512 characters per pattern.
• Matching uses the versioned minimatch-v10-bounded-static-v1 dialect: dotfiles included, case-sensitive, brace/extglob/negation disabled.
• Invalid instruction sources are quarantined, retained in snapshot source inventory, and excluded from resolution, coverage, conflicts, and path-stack/impact membership.
• Supported .vscode/settings.json / .jsonc keys are parsed with JSONC semantics and loaded through a second contained-file pass.

Bounded and fail-closed scanning

The scanner has explicit hard-bounded budgets for depth, directories, files, directory entries, per-file bytes, total source bytes, total accounted bytes, diagnostics, static analysis operations, canonical snapshot bytes, and total path-stack source IDs. Frontmatter and baseline inputs have separate size and structure limits. It rejects a symlink scan root, skips symlink/reparse paths, rechecks file identity around reads, resolves real paths, and checks physical containment. resolve reports a physically external symlink target as outside-root and returns no authoritative stack.

Any diagnostic makes scan completeness incomplete. Incomplete scans exit 3 and do not produce snapshots, because absence, coverage, and change conclusions would be unsafe.

Outputs, gates, and privacy

Formats: markdown, json, junit, and sarif.

• --fail-on evaluates the full finding set.
• --min-severity and --max-findings affect presentation only; hidden failures still fail the gate and remain represented in JUnit/SARIF.
• JSON reports conform to report schema 0.3.0 and carry schemaVersion: 0.3.0.
• Baselines conform to snapshot schema 0.3.0 and carry the same schemaVersion.
• Public reports omit raw instruction bodies and local absolute scan roots.
• Repository-relative paths, hashes, counts, reason codes, and bounded path samples are still metadata and may be sensitive in public artifacts.

Exit codes:

Code	Meaning
0	Complete scan; no finding met the configured failure threshold.
1	Complete scan; one or more findings met the failure threshold.
2	CLI usage/option error or any caught runtime, filesystem, output, baseline parse, or compatibility error.
3	Scan incomplete; conclusions are fail-closed.

Baseline compatibility

diff and impact require a complete snapshot with the same schema version, tool version, scanner revision, profile reference, and scan limits. Snapshot fingerprints and internal revision hashes detect malformed or accidentally modified baselines; they are integrity checks, not signatures and not proof that a baseline is trusted.

Findings

Current rules cover invalid frontmatter, inactive profile assets, dead applyTo scopes, orphaned prompt/agent assets, missing scoped coverage, bounded scanner failures, unsafe settings references, missing/out-of-root targets, and four conservative conflict topics: package manager, test execution, network use, and generated-file editing.

See Rules for exact semantics and limitations.

Library API

The package root intentionally exposes four runtime symbols: inspectRepository, renderReport, VERSION, and SCHEMA_VERSION. Internal scanners, parsers, matching helpers, and raw-body DTOs are not package-root APIs.

See API reference or 中文 API.

Validation evidence

The release gate runs typecheck, lint, 66 focused tests, build, CLI smoke, deterministic report/schema/privacy checks—including filesystem and analysis-budget incomplete reports for all eight modes—documentation guards, an exact package-file-set check, a packed-tarball install in a fresh project, workflow policy checks, and a source-plus-package secret scan. The CI matrix covers Windows and Linux on Node.js 20, 22, and 24.

Local commands:

npm run validate
npm audit --audit-level=high
npm pack --dry-run --json
npm publish --dry-run

Documentation

• English overview
• 中文概览
• API reference · 中文 API
• Rules · 规则
• Design · 设计
• Security policy
• Contributing

License

MIT