fix(markers): bound declarations per scan

[mbeacom]

Summary

• retain at most the first 64 parsed marker declarations per file in physical/source order
• retain at most 10,000 declarations per batch in code-unit path then source order, independent of concurrent read completion
• keep exact per-file and batch overflow counts while bounding live marker objects to the output plus one 16-file concurrency window
• collapse overflow into one advisory marker-declarations-capped finding with no exit-code authority
• surface exact counts through explain, check --json, CLI human output, and the Action log/comment without displacing changed-record errors
• document the output contract and reconcile the missing v0 recovery and marker scan-health entries in Unreleased

Output contract

• MARKER_DECLARATION_FILE_CAP = 64
• MARKER_DECLARATION_BATCH_CAP = 10_000
• single-file scans report omittedMarkers; explain --json reports declarationLimit, totalDeclarations, and omittedDeclarations
• batch/check reports expose markerScan.declarations with total, retained, omitted, per-file omitted, batch omitted, and both limits

Evidence

• observed the new adversarial tests fail against the uncapped implementation before adding the caps
• reproduces the 1,618-declaration / 8,098-byte amplification case and retains exactly 64
• covers exact 64/65 and 10,000/10,001 boundaries, reverse input order, reverse concurrent completion, and bounded retained object counts
• full suite: 2,790 passed, 1 platform skip
• typecheck, workspace lint, actionlint, ADR lint, changelog/dependency/clean-clone gates, full build, release pack, schema no-diff, and manifest no-diff passed
• packages/ci/dist/index.js rebuilt twice byte-identically with Linux oven/bun:1.3.14; queue bundle unchanged

Closes #113

[github-actions]

Decisions governing this change

• 0001 — Record architecture decisions as versioned markdown in git
  • via path: docs/adr/**
• 0003 — Ship as a Spec Kit extension plus a standalone CLI, not a competing harness
  • via path: packages/cli/**
• 0011 — Host the canonical JSON Schema at its $id on adrkit.dev
  • via path: site/**
• 0016 — Require every check to be observed failing before it counts as coverage
  • via path: packages/*/test/**
• 0022 — Scan inbound markers in check and CI without giving them exit-code authority
  • via path: packages/ci/src/**
  • via path: packages/cli/src/index.ts
  • via path: packages/core/src/check/**
  • via path: packages/core/src/markers/**
  • declared by packages/core/src/check/index.ts:1 (@adr 0022)
• 0023 — Read a marker only where the format hides it: fences and markdown prose
  • via path: packages/core/src/markers/**
• 0024 — Report the measured scan extent, not the window constant
  • via path: packages/cli/src/index.ts
  • via path: packages/core/src/markers/**
• 0026 — Identify the CI comment by the strongest author evidence the token allows
  • via path: packages/ci/src/comment.ts
  • via path: site/src/content/docs/ci.mdx
• 0029 — Scope Backstage publication as a downstream consumer, tiered on the entity-ownership mapping
  • via path: packages/cli/src/index.ts
  • via path: packages/core/src/check/**
• 0030 — Keep extension surfaces that carry a dependency tree outside this repository
  • via path: packages/ci/**
• 0031 — Publish a narrow consumer SDK as the contract, and document the CLI JSON as its sibling
  • via path: packages/cli/src/index.ts
• 0032 — Publish one lockstep OCI image after the coordinated release succeeds
  • via path: README.md
• 0033 — Select interactive graph presentation at the CLI boundary while preserving piped DOT
  • via path: packages/cli/src/index.ts
  • via path: site/src/content/docs/**
• 0035 — Execute the gates that certify a pull request from the default branch
  • via path: packages/ci/**

Historical records that once covered this change

These no longer bind this change, and are listed for context only:

• 0021 — Resolve inbound source annotations without changing the schema (superseded) — superseded by 0022
  • via path: packages/cli/src/index.ts
  • via path: packages/core/src/markers/**

[Copilot]

🟢 Approval recommended

The implementation consistently enforces deterministic bounds, preserves exit-code semantics, and includes comprehensive cross-surface coverage.

Pull request overview

Bounds inbound @adr declaration amplification while preserving deterministic ordering, exact reporting, and advisory-only behavior.

Changes:

• Adds 64-per-file and 10,000-per-batch declaration limits.
• Reports overflow through core, CLI, Action, and JSON surfaces.
• Adds boundary, ordering, memory-bounding, and rendering coverage plus documentation.

File summaries

File	Description
site/src/content/docs/commands.mdx	Documents declaration limits and output fields.
site/src/content/docs/ci.mdx	Documents Action overflow reporting.
README.md	Summarizes marker safety limits.
packages/core/test/surface.test.ts	Verifies public constant exports.
packages/core/test/markers-scan.test.ts	Tests file and batch caps.
packages/core/test/markers-pool.test.ts	Tests concurrent result ordering.
packages/core/test/check.test.ts	Tests collapsed advisory findings.
packages/core/src/markers/scan.ts	Enforces the per-file cap.
packages/core/src/markers/read.ts	Enforces deterministic batch limits and accounting.
packages/core/src/markers/index.ts	Exports new marker APIs.
packages/core/src/check/index.ts	Adds declaration reports and warnings.
packages/core/README.md	Documents core contracts.
packages/cli/test/explain.test.ts	Updates explain JSON expectations.
packages/cli/test/explain-markers.test.ts	Tests explain overflow reporting.
packages/cli/test/check.test.ts	Tests check output and exit behavior.
packages/cli/src/index.ts	Renders declaration counts and notices.
packages/cli/README.md	Documents CLI limits and reporting.
packages/ci/test/comment-render.test.ts	Tests bounded Action comments.
packages/ci/test/bundle-scope.test.ts	Verifies bundle scope.
packages/ci/test/action.test.ts	Tests Action overflow behavior.
packages/ci/src/comment.ts	Adds overflow details to scan health.
packages/ci/src/action.ts	Logs declaration accounting.
packages/ci/dist/index.js	Rebuilds the distributed Action bundle.
docs/adr/0022-scan-inbound-markers-in-check-and-ci-without-giving-them-exit-code-authority.md	Records the cap policy.
CHANGELOG.md	Records marker and prior unreleased changes.
AGENTS.md	Captures the marker-cap invariant.

Review details

• Files reviewed: 25/26 changed files
• Comments generated: 0
• Review effort level: Balanced

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.