Skip to content

Make SDK context evidence truthful, semantic, and reversible - #983

Merged
unbraind merged 4 commits into
mainfrom
feat/truthful-context-evidence-contracts
Aug 12, 2026
Merged

unbraind merged 4 commits into
mainfrom
feat/truthful-context-evidence-contracts

Conversation

@unbraind

@unbraind unbraind commented Aug 11, 2026 •

Copy link
Copy Markdown
Owner

Summary

This broad SDK and CLI tranche makes project-management context evidence authoritative, semantic, reversible, and stable under real agent workloads.

  • evaluate assurance against full authoritative metadata, add explicit present/missing predicates, canonicalize dependency kinds, fingerprint definitions, and preserve detected author provenance
  • make graph governance measure semantic context density, decode durable cache snapshots defensively, and reject incoherent cached evidence
  • expose truthful health ok values while treating immutable legacy provenance violations as visible advisory findings instead of permanently blocking otherwise healthy workspaces
  • make history-drift repair bypass stale metadata/body/collection caches and prove authoritative rereads after cached projections are poisoned
  • return role-labelled, shell-safe annotation recovery; partition generated error contracts; and keep contract snapshots/public SDK surfaces synchronized
  • make linked-test removal delimiter-safe, index-addressable, observable, and fail-closed across CLI, SDK, MCP, contracts, and completion
  • stabilize SDK entrypoint import-cost admission on the median of five fresh-process measurements while retaining p95 diagnostics and strict maximum-RSS budgets
  • upgrade and verify pm-changelog 2026.8.12 through companion PR #138 and its published npm/GitHub release

PM items

  • pm-py7qv2 — truthful assurance metadata and definition fingerprints
  • pm-33mjrw — detected assurance author provenance
  • pm-q6n8sj — canonical graph composition and semantic share
  • pm-h97qxd — health row ok parity
  • pm-rncuf7 — typed annotation transposition recovery
  • pm-m0b7h8 — lossless linked-test removal
  • pm-wqhzhg — exact-head review hardening and executable contract regressions
  • pm-eax4y8 — authoritative history-drift source scanning
  • pm-5q8wa0 — safe legacy provenance health disposition
  • pm-cg1sjb — deterministic SDK entrypoint import-cost admission
  • pm-c6urop — discovered compound linked-resource mutation UX follow-up; intentionally open and unclaimed

Verification

  • 486 test files and 7,242 tests passed with exact 100% statements, branches, functions, and lines
  • pnpm lint, typecheck, contracts, changelog check, secret scan, production audit, graph assurance, record integrity, and SDK entrypoint cost gates passed
  • 100% static docstring coverage and zero duplicated blocks
  • package artifact validation, 88-command package-first dogfood, packed npx smoke, and independent npm/Bun consumer acceptance passed
  • fresh temporary npm and Bun consumers exercised init, create, hierarchy, semantic dependency, claim, update, comment, evidence, get, close, and release through npx and bunx
  • pm validate --check-history-drift reports zero drift and pm health --check-only reports all ten checks healthy
  • semantic dogfood was explicitly skipped because PM_DOGFOOD_SEMANTIC was unset and is not counted as acceptance

Closes #979
Closes #980
Closes #982

Deliver a broad SDK and CLI context-integrity tranche across assurance, graph governance, health, annotation recovery, and linked-test evidence mutation.\n\n- evaluate assurance against authoritative metadata with missing/present predicates and definition fingerprints\n- attribute assurance writes through detected authors and enforce semantic graph composition\n- expose row-level health truth across SDK and CLI projections\n- provide role-labelled annotation recovery and partition the generated error catalog\n- make linked-test removal delimiter-safe, indexed, observable, and fail-closed\n- align contracts, docs, changelog, coverage, package smoke, and PM evidence\n\nTracks pm-py7qv2, pm-33mjrw, pm-q6n8sj, pm-h97qxd, pm-rncuf7, and pm-m0b7h8.
@coderabbitai

coderabbitai Bot commented Aug 11, 2026 •

Copy link
Copy Markdown

Review Change Stack

Warning

Review limit reached

@unbraind, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 30 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details
⚙️ Run configuration

Configuration used: Repository UI (base), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 9a3f3838-3bfb-4226-9a44-520fe164f629

📥 Commits

Reviewing files that changed from the base of the PR and between 6537649 and 658f9d8.

⛔ Files ignored due to path filters (2)
  • src/sdk/generated/generated-error-code-catalog-part-1.ts is excluded by !**/generated/**
  • src/sdk/generated/generated-error-code-catalog-part-2.ts is excluded by !**/generated/**
📒 Files selected for processing (75)
  • .agents/pm/assurance.json
  • .agents/pm/extensions/.managed-extensions.json
  • .agents/pm/history/_workspace.jsonl
  • .agents/pm/history/pm-33mjrw.jsonl
  • .agents/pm/history/pm-5q8wa0.jsonl
  • .agents/pm/history/pm-c6urop.jsonl
  • .agents/pm/history/pm-cg1sjb.jsonl
  • .agents/pm/history/pm-eax4y8.jsonl
  • .agents/pm/history/pm-h97qxd.jsonl
  • .agents/pm/history/pm-m0b7h8.jsonl
  • .agents/pm/history/pm-py7qv2.jsonl
  • .agents/pm/history/pm-q6n8sj.jsonl
  • .agents/pm/history/pm-rncuf7.jsonl
  • .agents/pm/history/pm-wqhzhg.jsonl
  • .agents/pm/issues/pm-33mjrw.toon
  • .agents/pm/issues/pm-5q8wa0.toon
  • .agents/pm/issues/pm-c6urop.toon
  • .agents/pm/issues/pm-cg1sjb.toon
  • .agents/pm/issues/pm-eax4y8.toon
  • .agents/pm/issues/pm-h97qxd.toon
  • .agents/pm/issues/pm-m0b7h8.toon
  • .agents/pm/issues/pm-py7qv2.toon
  • .agents/pm/issues/pm-q6n8sj.toon
  • .agents/pm/issues/pm-rncuf7.toon
  • .agents/pm/issues/pm-wqhzhg.toon
  • CHANGELOG.md
  • docs/ASSURANCE.md
  • docs/DEPENDENCY_KIND_CONTRACT.md
  • docs/README.md
  • docs/SDK_AGENT_SESSION_CONTEXT.md
  • docs/SDK_CONTEXT_INTEGRITY.md
  • docs/TRUSTWORTHY_CONTEXT_EVIDENCE.md
  • docs/performance/sdk-entrypoint-import-costs.md
  • scripts/bench/sdk-entrypoint-costs.mjs
  • scripts/generate-error-code-catalog.mjs
  • scripts/release/surface-replication-sets.json
  • scripts/release/token-budgets.json
  • sdk/public-surface.json
  • src/cli/commander-usage.ts
  • src/cli/error-guidance.ts
  • src/cli/register-annotations.ts
  • src/cli/register-operations.ts
  • src/core/shared/errors.ts
  • src/core/store/item-metadata-cache.ts
  • src/sdk/cli-contracts/flag-contracts.ts
  • src/sdk/cli-contracts/registration-helpers.ts
  • src/sdk/cli-contracts/schemas/assurance-definition.ts
  • src/sdk/cli-contracts/tool-parameter-tables.ts
  • src/sdk/cli-contracts/tool-schema.ts
  • src/sdk/completion.ts
  • src/sdk/generated-error-code-catalog.ts
  • src/sdk/governance/assurance-runtime.ts
  • src/sdk/governance/assurance.ts
  • src/sdk/governance/health.ts
  • src/sdk/governance/validate-item-reader.ts
  • src/sdk/governance/validate.ts
  • src/sdk/graph/durable-cache.ts
  • src/sdk/graph/governance.ts
  • src/sdk/runtime-primitives.ts
  • src/sdk/test/execution.ts
  • tests/fixtures/contracts/full.json
  • tests/integration/provenance-value-health.integration.spec.ts
  • tests/unit/cli/cli-main-errors.spec.ts
  • tests/unit/cli/error-guidance.spec.ts
  • tests/unit/commands/health-command.spec.ts
  • tests/unit/commands/register-commands.spec.ts
  • tests/unit/commands/test-command.spec.ts
  • tests/unit/commands/validate-command.spec.ts
  • tests/unit/scripts/generate-error-code-catalog.spec.ts
  • tests/unit/scripts/sdk-entrypoint-costs.spec.ts
  • tests/unit/sdk/assurance-runtime.spec.ts
  • tests/unit/sdk/assurance.spec.ts
  • tests/unit/sdk/graph/assembly-governance.spec.ts
  • tests/unit/sdk/graph/durable-cache.spec.ts
  • tests/unit/sdk/health-vector-boundary.spec.ts
📝 Walkthrough

Summary by CodeRabbit

  • New Features
    • Added recovery guidance for transposed annotation and collection commands.
    • Added --note support and repeatable --remove-index for linked tests.
    • Health checks now consistently include an ok status.
    • Graph audits now show relationship composition and semantic-edge metrics.
  • Bug Fixes
    • Improved assurance author attribution, dependency handling, and measurement reliability.
    • Preserved linked-test commands containing commas or equals signs.
    • Improved validation accuracy and handling of legacy provenance warnings.
  • Documentation
    • Expanded assurance, graph, health, recovery, and context-integrity documentation.

Walkthrough

This PR updates assurance governance, graph composition metrics, health-row contracts, CLI recovery, linked-test removal, generated error catalogs, public schemas, documentation, tests, and project-management evidence.

Changes

Platform contract updates

Layer / File(s) Summary
Assurance evaluation and graph gates
src/sdk/governance/assurance.ts, .agents/pm/assurance.json, src/sdk/graph/*
Assurance adds presence predicates, canonical dependency handling, measurement fingerprints, author resolution, and semantic-edge floor enforcement. Graph audits expose edge shares and semantic-edge metrics.
Health and validation rows
src/sdk/governance/health.ts, src/sdk/governance/validate.ts, src/sdk/governance/assurance-runtime.ts
Health and validation checks expose boolean ok fields. Projections preserve the fields. Assurance runtime reads full metadata and uses each check’s ok value.
CLI recovery and linked-test mutations
src/cli/*, src/sdk/test/execution.ts, src/sdk/cli-contracts/*
Transposed commands produce role-labelled recovery data. Notes support --note. Linked-test removal supports typed selectors and repeatable 1-based indexes, reports removal counts, and rejects zero-match removals.
Contracts, generated artifacts, and verification
sdk/public-surface.json, tests/fixtures/contracts/full.json, scripts/generate-error-code-catalog.mjs, tests/*
Public schemas advance to version 4.7.0. New error contracts and generated catalog partitions are validated. Tests cover assurance, graph, health, recovery, and linked-test behavior.
Documentation and project records
docs/*, CHANGELOG.md, .agents/pm/*, scripts/release/*
Documentation, changelog entries, release fixtures, and project records describe the updated contracts and verification evidence.

Estimated code review effort: 5 (Critical) | ~120 minutes

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name Status Explanation Resolution
Out of Scope Changes check ⚠️ Warning The PR also includes assurance, graph, provenance, history-drift, import-cost, changelog, and other changes beyond the three linked issues. Move unrelated assurance, graph, provenance, history-drift, and import-cost changes into separate PRs, or link issues that explicitly authorize this broader scope.
Docstring Coverage ⚠️ Warning Docstring coverage is 46.72% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (3 passed)
Check name Status Explanation
Linked Issues check ✅ Passed The changes implement all three linked objectives: transposed-command recovery (#979), row-level ok parity (#980), and safe indexed test removal (#982).
Title check ✅ Passed The title clearly summarizes the PR’s main focus on making SDK context evidence truthful, semantic, and reversible.
Description check ✅ Passed The description directly explains the assurance, graph, health, CLI, linked-test, documentation, and verification changes.
✨ Finishing Touches 💡 1
📝 Generate docstrings 💡
  • Create stacked PR
  • Commit on current branch

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@unbraind
unbraind marked this pull request as ready for review August 11, 2026 22:29
@unbraind

Copy link
Copy Markdown
Owner Author

@greptileai please review this exact head. @coderabbitai full review

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry @unbraind, your pull request is larger than the review limit of 150000 diff characters

@coderabbitai

coderabbitai Bot commented Aug 11, 2026 •

Copy link
Copy Markdown

@unbraind: I will perform a full review of the current head for #983.

⚠️ Action not completed

Review rate limited.


Your included review limit is currently reached under our Fair Usage Limits Policy. This review may still proceed through usage-based billing if eligible. Your next included review will be available in 59 minutes.

@sourcery-ai

sourcery-ai Bot commented Aug 11, 2026

Copy link
Copy Markdown

Reviewer's Guide

Refactors error-code catalog generation into partitioned modules, strengthens SDK assurance semantics and provenance (including full-metadata item sources, field presence predicates, dependency-kind canonicalization, measurement definition fingerprints, and author resolution), enriches relationship graph and health contracts, and makes linked-test and annotation mutations delimiter-safe, index-addressable, and semantically recoverable across CLI, SDK, MCP, and docs.

Sequence diagram for assurance gate evaluation and verdict recording

sequenceDiagram
  participant Caller
  participant evaluateAssuranceGate
  participant evaluateMeasurement
  participant evaluateMeasurementInternal
  participant createHash
  participant evaluateAssuranceAssertion
  participant recordAssuranceVerdict
  participant readSettings
  participant appendWorkspaceAuditEvent

  Caller->>evaluateAssuranceGate: evaluateAssuranceGate(gateId, document, context, options)
  loop assertion_ids
    evaluateAssuranceGate->>evaluateMeasurement: evaluateMeasurement(measurementDefinition, scopedContext, document.measurements)
    evaluateMeasurement->>evaluateMeasurementInternal: evaluateMeasurementInternal(definition, context, stack, state)
    activate evaluateMeasurementInternal
    evaluateMeasurementInternal->>createHash: createHash("sha256")
    createHash-->>evaluateMeasurementInternal: digest(definition_fingerprint)
    deactivate evaluateMeasurementInternal
    evaluateAssuranceGate->>evaluateAssuranceAssertion: evaluateAssuranceAssertion(assertionDefinition, measurementResult, { owner_terminal })
    evaluateAssuranceAssertion-->>evaluateAssuranceGate: AssuranceAssertionVerdict
  end
  evaluateAssuranceGate-->>Caller: AssuranceGateVerdict

  Caller->>recordAssuranceVerdict: recordAssuranceVerdict(pmRoot, verdict, options)
  activate recordAssuranceVerdict
  recordAssuranceVerdict->>readSettings: readSettings(pmRoot)
  readSettings-->>recordAssuranceVerdict: settings (author_default)
  recordAssuranceVerdict->>appendWorkspaceAuditEvent: appendWorkspaceAuditEvent({ op:"assurance:gate:verdict", author: resolveAuthor(options.author, settings.author_default), context:{ assurance_verdict: verdict } })
  appendWorkspaceAuditEvent-->>recordAssuranceVerdict: void
  deactivate recordAssuranceVerdict
  recordAssuranceVerdict-->>Caller: void
Loading

Sequence diagram for linked-test removal with index-based selection

sequenceDiagram
  actor User
  participant pm_test_command
  participant collectTestMutationValues
  participant validateBackgroundTestOptions
  participant runForegroundLinkedTests
  participant runBackgroundLinkedTests
  participant runTest
  participant runStartBackgroundRun

  User->>pm_test_command: pm test <id> --remove-index 2 --run
  pm_test_command->>collectTestMutationValues: collectTestMutationValues(options)
  collectTestMutationValues-->>pm_test_command: { addValues, addJsonValues, removeValues, removeIndexValues }

  pm_test_command->>validateBackgroundTestOptions: validateBackgroundTestOptions(options, values)
  validateBackgroundTestOptions-->>pm_test_command: void

  alt options.background === true
    pm_test_command->>runBackgroundLinkedTests: runBackgroundLinkedTests(id, options, values)
    runBackgroundLinkedTests->>runStartBackgroundRun: runStartBackgroundRun(pmRoot, { testOptions: { removeIndex: values.removeIndexValues, ... } })
    runStartBackgroundRun-->>runBackgroundLinkedTests: result
    runBackgroundLinkedTests-->>pm_test_command: void
  else foreground
    pm_test_command->>runForegroundLinkedTests: runForegroundLinkedTests(id, options, values)
    runForegroundLinkedTests->>runTest: runTest(pmRoot, id, buildRunTestOptions(options, values))
    runTest-->>runForegroundLinkedTests: result
    alt values.addValues.length>0 || values.addJsonValues.length>0 || values.removeValues.length>0 || values.removeIndexValues.length>0 || options.run === true
      runForegroundLinkedTests->>runTest: invalidateSearchCachesForMutation(...)
    end
    runForegroundLinkedTests-->>pm_test_command: void
  end

  pm_test_command-->>User: JSON result with removed linked tests
Loading

File-Level Changes

Change Details Files
Split the generated error-code catalog into reusable partitions and update the generator and tests to manage them
  • Replace the inlined exhaustive error-code array with imports from two generated catalog-part modules and spread them into definePmErrorCodeCatalog
  • Extend the catalog-generation script to emit multiple partition files, skip them during discovery, and validate or regenerate all parts in both normal and --check modes
  • Update catalog-generation tests to read and assert over the combined root file and partition files instead of a single monolith
src/sdk/generated-error-code-catalog.ts
scripts/generate-error-code-catalog.mjs
tests/unit/scripts/generate-error-code-catalog.spec.ts
src/sdk/generated/generated-error-code-catalog-part-1.ts
src/sdk/generated/generated-error-code-catalog-part-2.ts
Tighten assurance semantics, predicates, and provenance while making verdicts definition-fingerprintable
  • Extend AssuranceItemRecord to treat files/tests/docs as opaque objects, and load assurance evaluation context from full item metadata instead of a light projection
  • Add a state="present"
"missing" predicate for items sources with validation that exactly one of equals or state is used when field is set, and implement presence semantics for null/empty values
  • Canonicalize dependency_kind measurements using resolveCanonicalRelationshipKind so aliases and canonical spellings share populations
  • Compute a stable SHA-256 definition_fingerprint for each measurement and attach it to AssuranceMeasurementResult and to each assertion verdict as measurement_definition_fingerprint
  • Refine assertion loosening detection, arithmetic evaluation, cost aggregation, and measurement caching for clearer error paths and numeric safety
  • Require assertion negative controls to include both pass and fail cases and strengthen document validation for cross-references and gate wiring
  • Resolve authors for assurance registry mutations and gate verdicts via readSettings default instead of hard-coded "unknown", and propagate registry-invalid errors as typed AssuranceMutationRefusalError
  • Adjust list/get/put/remove assurance APIs and verdict listing to the new shapes and add coverage in assurance tests for state predicates, dependency aliases, fingerprints, loosening rules, and registry failure behavior
  • Enrich relationship graph governance with semantic edge composition and harden durable cache decoding
    • Extend RelationshipCoverageProfile and audit snapshots to include edge_share_by_kind, semantic_edges, and semantic_edge_share, counting specific semantic kinds (discovered_from, incident_from, supersedes, verifies) and computing per-kind shares
    • Update diffRelationshipAuditSnapshots to diff new share and semantic fields while defaulting missing baseline fields to zero
    • Harden durable graph cache snapshot decoding with helpers for record/number validation, unit-interval shares, and optional fields; backfill defaults for older baselines that lack new profile fields
    • Augment dependency-kind documentation with semantic census semantics and assurance interaction, and expand graph tests to cover composition ratios and semantic-edge counts
    src/sdk/graph/governance.ts
    src/sdk/graph/durable-cache.ts
    docs/DEPENDENCY_KIND_CONTRACT.md
    tests/unit/sdk/graph/assembly-governance.spec.ts
    tests/unit/sdk/graph/durable-cache.spec.ts
    Make linked-test mutations delimiter-safe, index-addressable, and fail-closed, propagating new options through CLI, contracts, and completion
    • Introduce a structured LinkedTestRemovalSelector, parse --remove into command/path/either selectors with strict validation, and add parseRemoveIndexes for 1-based numeric remove-index semantics
    • Change linked-test mutation application to return {tests, removed} and track removed count on ResolvedTestItem/TestResult, emitting linked_test_remove_no_match errors instead of silent no-ops
    • Wire new removeIndex option through TestCommandOptions, runTest, runForegroundLinkedTests/runBackgroundLinkedTests, CLI flag contracts, MCP tool parameters/schema version bump, and completion scripts
    • Update tests to cover lossless removal of commands containing commas/equals, index-based removal, error cases for malformed selectors, and background-mode validation
    src/sdk/test/execution.ts
    src/cli/register-operations.ts
    src/sdk/cli-contracts/tool-parameter-tables.ts
    src/sdk/cli-contracts/tool-schema.ts
    src/sdk/cli-contracts/flag-contracts.ts
    src/sdk/cli-contracts/registration-helpers.ts
    src/sdk/completion.ts
    tests/unit/commands/test-command.spec.ts
    tests/unit/commands/register-commands.spec.ts
    tests/fixtures/contracts/full.json
    Improve CLI and SDK error guidance with typed positional recovery and new transposition classifications
    • Extend PmCliErrorRecoveryPayload and normalization to support parsed_positionals, and render those roles in text output for human debugging
    • Add collection_transposed_subcommand guidance that detects pm add forms for comments/notes/learnings/files/test and suggests object-first syntax, carrying labelled parsed_positionals
    • Add annotation_transposed_subcommand enforcement for comments/notes/learnings command handlers, including a --note alias for notes and explicit recovery payloads tying transposed_subcommand and item_id
    • Refactor commander error guidance helpers to use the new recovery field, maintain strict typing, and adjust tests accordingly for linked-test guidance, context item guidance, and generic fallbacks
    src/cli/error-guidance.ts
    src/cli/register-annotations.ts
    src/core/shared/errors.ts
    tests/unit/cli/error-guidance.spec.ts
    tests/unit/commands/register-commands.spec.ts
    Expose boolean health row truth alongside status and align assurance health measurements with it
    • Extend HealthCheck with an ok boolean, populate it consistently in all builders (settings, directories, integrity, storage, extensions, telemetry, locks, history_drift, vectorization), and ensure skipped checks still return ok: true
    • Preserve ok in brief and summary projections while stripping details, and keep status and ok aligned in tests
    • Adjust assurance-runtime checkValue so health measurements can select either status or ok while mapping ok to numeric values for bounds
    • Update context-integrity/health docs and tests to describe and assert the ok contract across projections and vector-boundary scenarios
    src/sdk/governance/health.ts
    src/sdk/governance/assurance-runtime.ts
    docs/SDK_CONTEXT_INTEGRITY.md
    docs/TRUSTWORTHY_CONTEXT_EVIDENCE.md
    tests/unit/commands/health-command.spec.ts
    tests/unit/sdk/health-vector-boundary.spec.ts
    Refresh documentation, contracts, and changelog around trustworthy context and evidence
    • Add TRUSTWORTHY_CONTEXT_EVIDENCE.md describing assurance full-record predicates, graph semantics, health ok, linked-test removal, and collection grammar recovery, and link it from the docs index
    • Update Assurance, Dependency-kind, and SDK context-integrity docs to reference new PM items, state predicates, semantic census, and ok semantics
    • Document new behavior in CHANGELOG under Unreleased Added/Fixed entries tied back to PM issues
    • Update release metadata and public-surface/contracts fixtures to match the new flags, schema version, and APIs
    docs/TRUSTWORTHY_CONTEXT_EVIDENCE.md
    docs/ASSURANCE.md
    docs/DEPENDENCY_KIND_CONTRACT.md
    docs/SDK_CONTEXT_INTEGRITY.md
    docs/README.md
    CHANGELOG.md
    scripts/release/surface-replication-sets.json
    scripts/release/token-budgets.json
    sdk/public-surface.json
    tests/fixtures/contracts/full.json

    Assessment against linked issues

    Issue Objective Addressed Explanation
    #979 Update CLI error handling for collection commands so that invocations like pm <collection> add <id> ... are detected as a transposed subcommand, report that add is not a valid subcommand, highlight the positional roles (including the item id), and provide a corrective example such as pm <collection> <id> --add <value> across all relevant collections. ✅
    #979 Handle the --note alias for notes consistently by either documenting it as a supported alias to --add or rejecting it, so that CLI help and behavior match. ✅
    #980 Expose a boolean ok field on every checks[] row in the health JSON output (while retaining status), and ensure all projections, contracts, tests, and documentation are updated to reflect row-level ok parity. ✅
    #982 Change pm test linked-test removal so a selector that matches no entries does not report a successful mutation (ok:true) and instead fails closed or clearly reports that zero entries were removed. ✅
    #982 Ensure pm test removal selectors can address any linked-test entry accepted by --add/--add-json, including commands containing commas or equals signs, for example by adding delimiter-safe parsing and a 1-based index selector. ✅
    #982 Expose and document the new linked-test removal behavior (delimiter-safe selectors, --remove-index, removed count) in CLI contracts, completion, tests, and narrative documentation so agents can rely on it. ✅

    Possibly linked issues


    Tips and commands

    Interacting with Sourcery

    • Trigger a new review: Comment @sourcery-ai review on the pull request.
    • Continue discussions: Reply directly to Sourcery's review comments.
    • Generate a GitHub issue from a review comment: Ask Sourcery to create an
      issue from a review comment by replying to it. You can also reply to a
      review comment with @sourcery-ai issue to create an issue from it.
    • Generate a pull request title: Write @sourcery-ai anywhere in the pull
      request title to generate a title at any time. You can also comment
      @sourcery-ai title on the pull request to (re-)generate the title at any time.
    • Generate a pull request summary: Write @sourcery-ai summary anywhere in
      the pull request body to generate a PR summary at any time exactly where you
      want it. You can also comment @sourcery-ai summary on the pull request to
      (re-)generate the summary at any time.
    • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
      request to (re-)generate the reviewer's guide at any time.
    • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
      pull request to resolve all Sourcery comments. Useful if you've already
      addressed all the comments and don't want to see them anymore.
    • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
      request to dismiss all existing Sourcery reviews. Especially useful if you
      want to start fresh with a new review - don't forget to comment
      @sourcery-ai review to trigger a new review!

    Customizing Your Experience

    Access your dashboard to:

    • Enable or disable review features such as the Sourcery-generated pull request
      summary, the reviewer's guide, and others.
    • Change the review language.
    • Add, remove or edit custom review instructions.
    • Adjust other review settings.

    Getting Help

    @codspeed

    codspeed Bot commented Aug 11, 2026 •

    Copy link
    Copy Markdown

    Merging this PR will degrade performance by 0.75%

    ⚠️ Different runtime environments detected

    Some benchmarks with significant performance changes were compared across different runtime environments,
    which may affect the accuracy of the results.

    Open the report in CodSpeed to investigate

    ⚡ 1 improved benchmark
    ❌ 3 regressed benchmarks
    ✅ 7 untouched benchmarks

    Warning

    Please fix the performance issues or acknowledge them on CodSpeed.

    Performance Changes

    Benchmark BASE HEAD Efficiency
    ❌ build index (2000 docs x 80 words) 360.4 ms 370.2 ms -2.63%
    ❌ build index (200 docs x 40 words) 18.8 ms 19.1 ms -1.24%
    ❌ encodeQueryCursor 259.2 µs 262.3 µs -1.17%
    ⚡ createQueryFingerprint 1.5 ms 1.4 ms +2.09%

    Tip

    Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.


    Comparing feat/truthful-context-evidence-contracts (658f9d8) with main (6537649)

    Open in CodSpeed

    @codecov

    codecov Bot commented Aug 11, 2026 •

    Copy link
    Copy Markdown

    Codecov Report

    ✅ All modified and coverable lines are covered by tests.
    ✅ All tests successful. No failed tests found.

    📢 Thoughts on this report? Let us know!

    @coderabbitai coderabbitai Bot left a comment

    Copy link
    Copy Markdown

    Choose a reason for hiding this comment

    The reason will be displayed to describe this comment to others. Learn more.

    Actionable comments posted: 18

    🤖 Prompt for all review comments with AI agents
    Verify each finding against current code. Fix only still-valid issues, skip the
    rest with a brief reason, keep changes minimal, and validate.
    
    Inline comments:
    In @.agents/pm/history/pm-33mjrw.jsonl:
    - Around line 13-14: Keep both PM items active until PR `#983` is merged: in
    .agents/pm/history/pm-33mjrw.jsonl lines 13-14, reopen and claim pm-33mjrw and
    defer close/release; apply the same reopen-and-claim correction to pm-m0b7h8 in
    .agents/pm/history/pm-m0b7h8.jsonl lines 15-16. Only record pm close and pm
    release after exact merged-head evidence for PR `#983` exists at both referenced
    history entries.
    
    In @.agents/pm/history/pm-h97qxd.jsonl:
    - Around line 15-18: Keep pm-h97qxd claimed and in_progress until
    registry-backed package-default bunx acceptance succeeds: update
    .agents/pm/history/pm-h97qxd.jsonl at lines 15-18 so the premature close/release
    state is corrected or superseded, and regenerate
    .agents/pm/issues/pm-h97qxd.toon at lines 5-11 and 39-58 with the item remaining
    open and its pending verification note replaced only after successful verifier
    evidence.
    
    In @.agents/pm/history/pm-q6n8sj.jsonl:
    - Line 9: Append a new PM comment to the history using the existing
    comment-append mechanism, stating that the evidence execution date uses
    Europe/Vienna while event timestamp fields remain UTC. Do not modify the
    existing hash-chained entry or its embedded comment, and preserve the history
    chain integrity.
    
    In @.agents/pm/history/pm-rncuf7.jsonl:
    - Around line 20-21: Restore PM items pm-rncuf7 and pm-m0b7h8 through the
    supported PM CLI lifecycle, reclaim ownership, and regenerate projections; apply
    this to .agents/pm/history/pm-rncuf7.jsonl lines 20-21,
    .agents/pm/issues/pm-rncuf7.toon lines 5-11, and
    .agents/pm/issues/pm-m0b7h8.toon lines 5-11. Keep both active while HEAD is
    detached or not an ancestor of origin/main, and close/release them only after
    recording the exact merged commit and verifying merged-head evidence.
    
    In `@CHANGELOG.md`:
    - Around line 5-8: Update the changelog classifier so the Issue fallback runs
    before title-only “add” keyword detection, preventing pm-q6n8sj from being
    classified as Added. Then regenerate CHANGELOG.md through the normal generation
    workflow and preserve the generated output rather than moving the line manually.
    
    In `@docs/TRUSTWORTHY_CONTEXT_EVIDENCE.md`:
    - Line 88: Update the command= selector in the pm-example test invocation to use
    shell-safe quoting for the nested node command, preserving the comma and equals
    sign so the stored command remains valid when the linked test executes.
    
    In `@src/cli/error-guidance.ts`:
    - Around line 1492-1535: Update buildTransposedCollectionActionGuidance to
    resolve and validate itemId through CommanderGuidanceContext before constructing
    suggestedRetry or emitting guidance. Add the verified item lookup/result to the
    context, and return null when no existing item ID is found; only then generate
    collection_transposed_subcommand using the verified value.
    
    In `@src/cli/register-annotations.ts`:
    - Around line 133-135: Update the option parsing around addFromOption to detect
    when both --add and --note are provided with distinct values and reject the
    conflicting combination before choosing an alias. Preserve normal behavior when
    only one alias is supplied, and add a regression test covering distinct values
    for both options.
    - Around line 45-63: Update the retry construction near suggestedRetry so
    undefined suppliedText selects a valid source-specific command: use --add - or
    --stdin for stdin input, and preserve --file with its path for file input. Keep
    the existing JSON-quoted --add value for supplied text, and ensure
    recovery.suggested_retry never emits bare --add.
    - Around line 45-63: The suggestedRetry construction uses JSON.stringify, which
    is not safe shell quoting for user-derived annotation text. Update the error
    recovery data around suggestedRetry and the PmCliError payload to use the
    existing CLI shell-quoting helper for every user-derived argument, or provide
    structured argv data instead; preserve the recovery guidance and avoid emitting
    executable or expandable shell text.
    
    In `@src/sdk/governance/assurance-runtime.ts`:
    - Around line 77-99: Add the required boolean ok property to ValidateCheck and
    each of the eight runValidate check builders, setting it to status === "ok" for
    every row. Keep the existing runHealth behavior and checkValue handling
    unchanged.
    
    In `@src/sdk/governance/assurance.ts`:
    - Around line 659-675: Replace the predicateContractErrors string-keyed truth
    table in the source.kind === "items" validation with two explicit conditions:
    require exactly one of equals or state when source.field is defined, and require
    source.field when either predicate is supplied. Preserve Object.hasOwn(source,
    "equals") so explicit equals: null counts as supplied, and keep both existing
    error messages unchanged.
    
    In `@src/sdk/graph/durable-cache.ts`:
    - Around line 309-329: Extend the profile decoder validation after the existing
    optional-field checks to verify composition fields against the totals in
    edges_by_kind and the corresponding edge counts. Require edge_share_by_kind and
    semantic_edge_share to match their count-derived shares, and ensure
    semantic_edges is consistent with the relevant total; retain the existing
    zero/empty defaults when all composition fields are absent. Use the surrounding
    profile-decoding symbols rather than changing unrelated validation.
    
    In `@tests/fixtures/contracts/full.json`:
    - Around line 13925-13941: Update the catalog-generation metadata for
    collection_transposed_subcommand to use Commander’s usage-error classification
    and exit code 2 instead of generic_failure and exit code 1, then regenerate the
    affected catalog and fixture so the generated entries are consistent.
    
    In `@tests/unit/cli/error-guidance.spec.ts`:
    - Around line 702-721: Strengthen the malformed-entry check in the test “renders
    typed positional roles and defensively normalizes malformed roles” by asserting
    the rendered parsed_positionals block contains only the valid
    transposed_subcommand entry. Ensure the assertion rejects any output containing
    the malformed role or value, including numeric or null renderings, rather than
    checking only the literal "- : " form.
    
    In `@tests/unit/commands/health-command.spec.ts`:
    - Around line 3048-3050: Strengthen the brief-result assertion near the health
    checks by adding a fixture whose status is not "ok", then verify each check
    derives ok exactly as (check.status === "ok"). Replace the type-only boolean
    assertion while preserving coverage of the brief projection result.
    
    In `@tests/unit/scripts/generate-error-code-catalog.spec.ts`:
    - Around line 9-20: Update readGeneratedCatalog to avoid hardcoding
    generated-error-code-catalog part filenames; enumerate the generated directory
    with readdir or reuse GENERATED_CATALOG_PART_COUNT from the generator, then read
    every discovered/expected part alongside the main catalog so assertions always
    cover all generated output.
    
    In `@tests/unit/sdk/assurance.spec.ts`:
    - Around line 668-676: Add a neighboring evaluation test for the absent
    `priority` field that uses an `equals: null` predicate and asserts the result
    has value 2 and population_size 2, matching the existing `missing-priority`
    fixture and expected count. Keep the assertion focused on evaluation behavior so
    it protects null equality handling in `valuesEqual`.
    
    🪄 Autofix

    Fix all unresolved CodeRabbit comments on this PR:

    • Push a commit to this branch (recommended)
    • Create a new PR with the fixes

    ℹ️ Review info
    ⚙️ Run configuration

    Configuration used: Repository UI (base), Organization UI (inherited)

    Review profile: ASSERTIVE

    Plan: Pro Plus

    Run ID: b2886d34-b284-4c43-92b8-5c3bfd38ed54

    📥 Commits

    Reviewing files that changed from the base of the PR and between 6537649 and 820b33e.

    ⛔ Files ignored due to path filters (2)
    • src/sdk/generated/generated-error-code-catalog-part-1.ts is excluded by !**/generated/**
    • src/sdk/generated/generated-error-code-catalog-part-2.ts is excluded by !**/generated/**
    📒 Files selected for processing (52)
    • .agents/pm/assurance.json
    • .agents/pm/history/_workspace.jsonl
    • .agents/pm/history/pm-33mjrw.jsonl
    • .agents/pm/history/pm-h97qxd.jsonl
    • .agents/pm/history/pm-m0b7h8.jsonl
    • .agents/pm/history/pm-py7qv2.jsonl
    • .agents/pm/history/pm-q6n8sj.jsonl
    • .agents/pm/history/pm-rncuf7.jsonl
    • .agents/pm/issues/pm-33mjrw.toon
    • .agents/pm/issues/pm-h97qxd.toon
    • .agents/pm/issues/pm-m0b7h8.toon
    • .agents/pm/issues/pm-py7qv2.toon
    • .agents/pm/issues/pm-q6n8sj.toon
    • .agents/pm/issues/pm-rncuf7.toon
    • CHANGELOG.md
    • docs/ASSURANCE.md
    • docs/DEPENDENCY_KIND_CONTRACT.md
    • docs/README.md
    • docs/SDK_CONTEXT_INTEGRITY.md
    • docs/TRUSTWORTHY_CONTEXT_EVIDENCE.md
    • scripts/generate-error-code-catalog.mjs
    • scripts/release/surface-replication-sets.json
    • scripts/release/token-budgets.json
    • sdk/public-surface.json
    • src/cli/error-guidance.ts
    • src/cli/register-annotations.ts
    • src/cli/register-operations.ts
    • src/core/shared/errors.ts
    • src/sdk/cli-contracts/flag-contracts.ts
    • src/sdk/cli-contracts/registration-helpers.ts
    • src/sdk/cli-contracts/schemas/assurance-definition.ts
    • src/sdk/cli-contracts/tool-parameter-tables.ts
    • src/sdk/cli-contracts/tool-schema.ts
    • src/sdk/completion.ts
    • src/sdk/generated-error-code-catalog.ts
    • src/sdk/governance/assurance-runtime.ts
    • src/sdk/governance/assurance.ts
    • src/sdk/governance/health.ts
    • src/sdk/graph/durable-cache.ts
    • src/sdk/graph/governance.ts
    • src/sdk/runtime-primitives.ts
    • src/sdk/test/execution.ts
    • tests/fixtures/contracts/full.json
    • tests/unit/cli/error-guidance.spec.ts
    • tests/unit/commands/health-command.spec.ts
    • tests/unit/commands/register-commands.spec.ts
    • tests/unit/commands/test-command.spec.ts
    • tests/unit/scripts/generate-error-code-catalog.spec.ts
    • tests/unit/sdk/assurance.spec.ts
    • tests/unit/sdk/graph/assembly-governance.spec.ts
    • tests/unit/sdk/graph/durable-cache.spec.ts
    • tests/unit/sdk/health-vector-boundary.spec.ts

    Comment thread .agents/pm/history/pm-33mjrw.jsonl Resolved
    Comment thread .agents/pm/history/pm-h97qxd.jsonl Resolved
    Comment thread .agents/pm/history/pm-q6n8sj.jsonl Resolved
    Comment thread .agents/pm/history/pm-rncuf7.jsonl Resolved
    Comment thread CHANGELOG.md Resolved
    Comment thread tests/fixtures/contracts/full.json Resolved
    Comment thread tests/unit/cli/error-guidance.spec.ts Resolved
    Comment thread tests/unit/sdk/assurance.spec.ts Resolved
    Address exact-head review findings across assurance metadata, graph cache coherence, drift validation, provenance health, CLI guidance, annotation retries, and generated error contracts.
    
    Stabilize SDK cold-import admission on five-sample medians while retaining p95 diagnostics and strict RSS budgets. Add focused regressions, exact coverage evidence, updated agent documentation, pm-changelog 2026.8.12 output, and rich PM lineage for the active tranche.
    @unbraind

    Copy link
    Copy Markdown
    Owner Author

    @coderabbitai full review
    @greptileai review
    @sourcery-ai review

    Please review exact head 36708c0. This update addresses the first review inventory and adds authoritative drift scanning, legacy provenance health disposition, deterministic SDK import-cost admission, and complete executable regressions.

    @coderabbitai

    coderabbitai Bot commented Aug 12, 2026 •

    Copy link
    Copy Markdown

    @unbraind I will perform a full review of PR #983 at exact head 36708c02d7a1377feaebd4bc197d263736506b20.


    🧠 Learnings used
    Learnt from: unbraind
    Repo: unbraind/pm-cli PR: 0
    File: :0-0
    Timestamp: 2026-07-25T23:43:31.481Z
    Learning: For GitHub pull request `#718` in unbraind/pm-cli, CodeRabbit quota/availability messages are operational notifications only and must not be interpreted as a substantive code-review finding or approval. Exact-head CI and independent validation artifacts are the relevant evidence.
    

    Learnt from: unbraind
    Repo: unbraind/pm-cli PR: 0
    File: :0-0
    Timestamp: 2026-07-26T09:16:12.987Z
    Learning: For pull request `#735` in unbraind/pm-cli, a CodeRabbit full-review command that returns a fair-usage-limit notice is provider unavailability only. It must not be represented as substantive review evidence, a findings-free result, or human approval.
    
    ⚠️ Action not completed

    Review rate limited.


    Your included review limit is currently reached under our Fair Usage Limits Policy. This review may still proceed through usage-based billing if eligible. Your next included review will be available in 59 minutes.

    @coderabbitai coderabbitai Bot left a comment

    Copy link
    Copy Markdown

    Choose a reason for hiding this comment

    The reason will be displayed to describe this comment to others. Learn more.

    Actionable comments posted: 1

    Caution

    Some comments are outside the diff and can’t be posted inline due to platform limitations.

    ⚠️ Outside diff range comments (2)
    scripts/generate-error-code-catalog.mjs (1)

    46-47: 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

    Reject stale generated partition files in check mode.

    --check validates only the two partitions created from GENERATED_CATALOG_PART_COUNT. It does not detect an extra generated-error-code-catalog-part-N.ts file, and tests cover only missing or modified expected files. Compare src/sdk/generated with the expected partition set and add an extra-partition regression test.

    🤖 Prompt for AI Agents
    Verify each finding against current code. Fix only still-valid issues, skip the
    rest with a brief reason, keep changes minimal, and validate.
    
    In `@scripts/generate-error-code-catalog.mjs` around lines 46 - 47, Update the
    --check validation around GENERATED_CATALOG_PART_COUNT to compare
    src/sdk/generated against the complete expected partition set, rejecting any
    extra generated-error-code-catalog-part-N.ts files as stale. Add a regression
    test covering an unexpected extra partition while preserving existing missing
    and modified partition checks.
    
    src/cli/register-annotations.ts (1)

    38-74: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

    Verify the item before emitting recovery.

    This path treats text.trim() as an item ID without checking the selected tracker. For example, pm notes add draft emits pm notes draft --add - even when draft does not exist.

    Resolve the candidate item before setting recovery.suggested_retry. If lookup fails, keep the usage error but omit transposition recovery. Add a regression for a missing candidate ID.

    The earlier tracker-validation concern remains reachable through this direct PmCliError path.

    🤖 Prompt for AI Agents
    Verify each finding against current code. Fix only still-valid issues, skip the
    rest with a brief reason, keep changes minimal, and validate.
    
    In `@src/cli/register-annotations.ts` around lines 38 - 74, Update the
    transposed-subcommand handling in the annotation registration flow to resolve
    and validate text.trim() as an item ID against the selected tracker before
    constructing recovery metadata or suggested retry commands. If lookup fails,
    still throw the existing usage PmCliError but omit transposition recovery;
    preserve recovery for valid candidates and add a regression covering a missing
    candidate ID.
    
    ♻️ Duplicate comments (1)
    tests/unit/commands/health-command.spec.ts (1)

    3048-3050: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

    Assert the brief projection's ok value.

    The assertion at Lines 3048-3050 checks only that ok is boolean. It passes when a warning row exposes the wrong value. Add a non-"ok" fixture and assert check.ok === (check.status === "ok"). The equality assertion at Lines 3327-3331 already covers this relation in another projection.

    🤖 Prompt for AI Agents
    Verify each finding against current code. Fix only still-valid issues, skip the
    rest with a brief reason, keep changes minimal, and validate.
    
    In `@tests/unit/commands/health-command.spec.ts` around lines 3048 - 3050, Update
    the health check projection test around the existing health.checks assertion to
    include a non-"ok" status fixture, then assert each check’s ok value equals
    whether check.status is "ok". Replace the boolean-type-only expectation while
    preserving the existing projection coverage.
    
    🤖 Prompt for all review comments with AI agents
    Verify each finding against current code. Fix only still-valid issues, skip the
    rest with a brief reason, keep changes minimal, and validate.
    
    Inline comments:
    In `@src/sdk/governance/assurance.ts`:
    - Around line 661-672: Update validateMeasurementDefinition to reject any
    defined source.state value other than "present" or "missing" before computing
    predicateCount, while preserving the existing field/predicate validation. Add a
    runtime regression test using an invalid cast or parsed declaration to verify
    unsupported items.state values are refused.
    
    ---
    
    Outside diff comments:
    In `@scripts/generate-error-code-catalog.mjs`:
    - Around line 46-47: Update the --check validation around
    GENERATED_CATALOG_PART_COUNT to compare src/sdk/generated against the complete
    expected partition set, rejecting any extra
    generated-error-code-catalog-part-N.ts files as stale. Add a regression test
    covering an unexpected extra partition while preserving existing missing and
    modified partition checks.
    
    In `@src/cli/register-annotations.ts`:
    - Around line 38-74: Update the transposed-subcommand handling in the annotation
    registration flow to resolve and validate text.trim() as an item ID against the
    selected tracker before constructing recovery metadata or suggested retry
    commands. If lookup fails, still throw the existing usage PmCliError but omit
    transposition recovery; preserve recovery for valid candidates and add a
    regression covering a missing candidate ID.
    
    ---
    
    Duplicate comments:
    In `@tests/unit/commands/health-command.spec.ts`:
    - Around line 3048-3050: Update the health check projection test around the
    existing health.checks assertion to include a non-"ok" status fixture, then
    assert each check’s ok value equals whether check.status is "ok". Replace the
    boolean-type-only expectation while preserving the existing projection coverage.
    
    🪄 Autofix

    Fix all unresolved CodeRabbit comments on this PR:

    • Push a commit to this branch (recommended)
    • Create a new PR with the fixes

    ℹ️ Review info
    ⚙️ Run configuration

    Configuration used: Repository UI (base), Organization UI (inherited)

    Review profile: ASSERTIVE

    Plan: Pro Plus

    Run ID: 2f639500-4109-4717-8903-c69c43151436

    📥 Commits

    Reviewing files that changed from the base of the PR and between 820b33e and 36708c0.

    ⛔ Files ignored due to path filters (2)
    • src/sdk/generated/generated-error-code-catalog-part-1.ts is excluded by !**/generated/**
    • src/sdk/generated/generated-error-code-catalog-part-2.ts is excluded by !**/generated/**
    📒 Files selected for processing (44)
    • .agents/pm/extensions/.managed-extensions.json
    • .agents/pm/history/pm-5q8wa0.jsonl
    • .agents/pm/history/pm-c6urop.jsonl
    • .agents/pm/history/pm-cg1sjb.jsonl
    • .agents/pm/history/pm-eax4y8.jsonl
    • .agents/pm/history/pm-q6n8sj.jsonl
    • .agents/pm/history/pm-wqhzhg.jsonl
    • .agents/pm/issues/pm-5q8wa0.toon
    • .agents/pm/issues/pm-c6urop.toon
    • .agents/pm/issues/pm-cg1sjb.toon
    • .agents/pm/issues/pm-eax4y8.toon
    • .agents/pm/issues/pm-q6n8sj.toon
    • .agents/pm/issues/pm-wqhzhg.toon
    • CHANGELOG.md
    • docs/SDK_AGENT_SESSION_CONTEXT.md
    • docs/TRUSTWORTHY_CONTEXT_EVIDENCE.md
    • docs/performance/sdk-entrypoint-import-costs.md
    • scripts/bench/sdk-entrypoint-costs.mjs
    • scripts/generate-error-code-catalog.mjs
    • scripts/release/surface-replication-sets.json
    • sdk/public-surface.json
    • src/cli/commander-usage.ts
    • src/cli/error-guidance.ts
    • src/cli/register-annotations.ts
    • src/core/store/item-metadata-cache.ts
    • src/sdk/governance/assurance-runtime.ts
    • src/sdk/governance/assurance.ts
    • src/sdk/governance/health.ts
    • src/sdk/governance/validate-item-reader.ts
    • src/sdk/governance/validate.ts
    • src/sdk/graph/durable-cache.ts
    • src/sdk/graph/governance.ts
    • tests/fixtures/contracts/full.json
    • tests/integration/provenance-value-health.integration.spec.ts
    • tests/unit/cli/cli-main-errors.spec.ts
    • tests/unit/cli/error-guidance.spec.ts
    • tests/unit/commands/health-command.spec.ts
    • tests/unit/commands/register-commands.spec.ts
    • tests/unit/commands/validate-command.spec.ts
    • tests/unit/scripts/generate-error-code-catalog.spec.ts
    • tests/unit/scripts/sdk-entrypoint-costs.spec.ts
    • tests/unit/sdk/assurance-runtime.spec.ts
    • tests/unit/sdk/assurance.spec.ts
    • tests/unit/sdk/graph/durable-cache.spec.ts

    Comment thread src/sdk/governance/assurance.ts Resolved
    Keep pm-c6urop open and unclaimed while moving it under the active roadmap and declaring its planning estimate. Record the hosted exact-head gate evidence on the review-hardening item.
    @unbraind

    Copy link
    Copy Markdown
    Owner Author

    @coderabbitai full review
    @greptileai review
    @sourcery-ai review

    Please re-review exact head bc3205c. The only delta after the previous review request is PM context: the discovered, intentionally unclaimed follow-up now has an active roadmap parent and explicit estimate so hosted tracker ratchets are truthful.

    @coderabbitai

    coderabbitai Bot commented Aug 12, 2026 •

    Copy link
    Copy Markdown

    @unbraind I will perform a full review of PR #983 at exact head bc3205cc8.

    I will assess the PM context delta for tracker consistency. I will not treat generated .agents/pm/ artifacts as evidence of direct raw-file edits.


    🧠 Learnings used
    Learnt from: unbraind
    Repo: unbraind/pm-cli PR: 735
    File: .agents/pm/history/pm-0yi7.jsonl:15-15
    Timestamp: 2026-07-26T09:24:02.363Z
    Learning: In `unbraind/pm-cli`, exact-head review evidence must not be required inside a PM history entry or derived task projection that is part of that same Git commit: appending via the PM CLI changes the append-only hash-chained history, synchronized projection, and commit head. Use the pull request’s exact-head hosted-check inventory as stable review evidence, and treat implementation commit references in PM records as traceability rather than self-attestation.
    

    Learnt from: unbraind
    Repo: unbraind/pm-cli PR: 0
    File: :0-0
    Timestamp: 2026-07-25T23:43:31.481Z
    Learning: For GitHub pull request `#718` in unbraind/pm-cli, CodeRabbit quota/availability messages are operational notifications only and must not be interpreted as a substantive code-review finding or approval. Exact-head CI and independent validation artifacts are the relevant evidence.
    

    Learnt from: unbraind
    Repo: unbraind/pm-cli PR: 0
    File: :0-0
    Timestamp: 2026-07-26T09:16:12.987Z
    Learning: For pull request `#735` in unbraind/pm-cli, a CodeRabbit full-review command that returns a fair-usage-limit notice is provider unavailability only. It must not be represented as substantive review evidence, a findings-free result, or human approval.
    

    Learnt from: unbraind
    Repo: unbraind/pm-cli PR: 0
    File: :0-0
    Timestamp: 2026-07-28T17:25:45.283Z
    Learning: For pm-cli PR `#798`, the `.agents/pm` GH-797 artifacts are intentional intake traceability for a discovered GitHub report. They remain open and unclaimed and do not represent unrelated implementation scope.
    

    Learnt from: unbraind
    Repo: unbraind/pm-cli PR: 777
    File: .agents/pm/chores/pm-xwah.toon:5-36
    Timestamp: 2026-07-27T19:50:20.307Z
    Learning: In unbraind/pm-cli, tracker updates under `.agents/pm/` may be generated by PM CLI commands and committed as resulting artifacts; do not infer direct raw file editing merely from `.toon` or history-file diffs. Review the PM command/history evidence and derived-record consistency instead.
    
    ⚠️ Action not completed

    Review rate limited.


    Your included review limit is currently reached under our Fair Usage Limits Policy. This review may still proceed through usage-based billing if eligible. Your next included review will be available in 49 minutes.

    Validate persisted item measurement state values before predicate evaluation and add a runtime regression for parsed declarations. Preserve complexity, docstring, exact coverage, contract, and full static gates.
    @unbraind

    Copy link
    Copy Markdown
    Owner Author

    @coderabbitai full review
    @greptileai review
    @sourcery-ai review

    Please review exact head 658f9d8. This commit implements the valid major runtime-contract finding: parsed assurance item sources now reject unsupported state values, with an executable regression and exact 100/100/100/100 coverage.

    @coderabbitai

    coderabbitai Bot commented Aug 12, 2026 •

    Copy link
    Copy Markdown

    @unbraind I will perform a full review of PR #983 at exact head 658f9d8fc.

    I will assess the assurance item-source state validation and its regression coverage. I will use the hosted exact-head check inventory as validation evidence.


    🧠 Learnings used
    Learnt from: unbraind
    Repo: unbraind/pm-cli PR: 0
    File: :0-0
    Timestamp: 2026-07-25T23:43:31.481Z
    Learning: For GitHub pull request `#718` in unbraind/pm-cli, CodeRabbit quota/availability messages are operational notifications only and must not be interpreted as a substantive code-review finding or approval. Exact-head CI and independent validation artifacts are the relevant evidence.
    

    Learnt from: unbraind
    Repo: unbraind/pm-cli PR: 0
    File: :0-0
    Timestamp: 2026-07-26T09:16:12.987Z
    Learning: For pull request `#735` in unbraind/pm-cli, a CodeRabbit full-review command that returns a fair-usage-limit notice is provider unavailability only. It must not be represented as substantive review evidence, a findings-free result, or human approval.
    

    Learnt from: unbraind
    Repo: unbraind/pm-cli PR: 957
    File: .agents/pm/history/pm-zzahs4.jsonl:6-14
    Timestamp: 2026-08-10T02:22:41.829Z
    Learning: In `unbraind/pm-cli`, the final merge decision uses the pull request hosted exact-head check inventory. PM history records retain implementation chronology and traceability only; they are not independent merge-validation evidence.
    
    ⚠️ Action not completed

    Review rate limited.


    Your included review limit is currently reached under our Fair Usage Limits Policy. This review may still proceed through usage-based billing if eligible. Your next included review will be available in 30 minutes.

    @unbraind

    Copy link
    Copy Markdown
    Owner Author

    Sourcery guidance and review-size limitation were reviewed. Provider inability to review the large tranche was not treated as approval.

    @unbraind

    Copy link
    Copy Markdown
    Owner Author

    The oversized-review limitation is acknowledged. It is not treated as approval; the tranche is covered by repository gates, manual acceptance, and other review findings.

    @unbraind

    Copy link
    Copy Markdown
    Owner Author

    Walkthrough and findings reviewed. Every actionable thread is fixed and resolved. The external docstring warning conflicts with the repository static docstring gate, which passed at 100 percent on the exact head.

    @unbraind

    Copy link
    Copy Markdown
    Owner Author

    Review acknowledgement read. No additional inline finding was attached; provider availability remains a documented limitation.

    @unbraind

    Copy link
    Copy Markdown
    Owner Author

    Codecov patch coverage was reviewed. Independent full repository coverage is exactly 100 percent for statements, branches, functions, and lines.

    @unbraind

    Copy link
    Copy Markdown
    Owner Author

    Exact-head review response reviewed. Provider unavailability is recorded separately from approval; hosted gates and resolved actionable threads provide the merge evidence.

    @unbraind

    Copy link
    Copy Markdown
    Owner Author

    Exact-head review response reviewed and recorded. All current hosted checks are terminal and all available actionable review threads are resolved.

    @unbraind

    Copy link
    Copy Markdown
    Owner Author

    Exact-head review response reviewed and recorded. The provider limit is not counted as approval; all available actionable findings were addressed.

    @unbraind

    Copy link
    Copy Markdown
    Owner Author

    Rate limiting is recorded as provider unavailability and was not treated as approval. Exact-head hosted gates and the actionable review inventory are complete.

    @unbraind

    Copy link
    Copy Markdown
    Owner Author

    Review fully read. The unsupported runtime state finding was valid, fixed, regression-tested, and resolved on exact head 658f9d8.

    @unbraind

    Copy link
    Copy Markdown
    Owner Author

    Reviewed the reported aggregate benchmark delta. Dedicated entrypoint and transport budget gates passed and the change remains below enforced regression thresholds.

    @unbraind

    Copy link
    Copy Markdown
    Owner Author

    Review fully read. All actionable findings were implemented with regressions and every thread is resolved on the exact head.

    @unbraind

    Copy link
    Copy Markdown
    Owner Author

    The associated inline acknowledgement review was read, reconciled with the exact head, and recorded; it introduces no unresolved finding.

    @unbraind

    Copy link
    Copy Markdown
    Owner Author

    The associated inline acknowledgement review was read, reconciled with the exact head, and recorded; it introduces no unresolved finding.

    @unbraind

    Copy link
    Copy Markdown
    Owner Author

    The associated inline acknowledgement review was read, reconciled with the exact head, and recorded; it introduces no unresolved finding.

    @unbraind

    Copy link
    Copy Markdown
    Owner Author

    The associated inline acknowledgement review was read, reconciled with the exact head, and recorded; it introduces no unresolved finding.

    @unbraind

    Copy link
    Copy Markdown
    Owner Author

    The associated inline acknowledgement review was read, reconciled with the exact head, and recorded; it introduces no unresolved finding.

    @unbraind

    Copy link
    Copy Markdown
    Owner Author

    The associated inline acknowledgement review was read, reconciled with the exact head, and recorded; it introduces no unresolved finding.

    @unbraind

    Copy link
    Copy Markdown
    Owner Author

    The associated inline acknowledgement review was read, reconciled with the exact head, and recorded; it introduces no unresolved finding.

    @unbraind

    Copy link
    Copy Markdown
    Owner Author

    The associated inline acknowledgement review was read, reconciled with the exact head, and recorded; it introduces no unresolved finding.

    @unbraind

    Copy link
    Copy Markdown
    Owner Author

    The associated inline acknowledgement review was read, reconciled with the exact head, and recorded; it introduces no unresolved finding.

    @unbraind

    Copy link
    Copy Markdown
    Owner Author

    The associated inline acknowledgement review was read, reconciled with the exact head, and recorded; it introduces no unresolved finding.

    @unbraind

    Copy link
    Copy Markdown
    Owner Author

    The associated inline acknowledgement review was read, reconciled with the exact head, and recorded; it introduces no unresolved finding.

    @unbraind

    Copy link
    Copy Markdown
    Owner Author

    The associated inline acknowledgement review was read, reconciled with the exact head, and recorded; it introduces no unresolved finding.

    @unbraind

    Copy link
    Copy Markdown
    Owner Author

    The associated inline acknowledgement review was read, reconciled with the exact head, and recorded; it introduces no unresolved finding.

    @unbraind

    Copy link
    Copy Markdown
    Owner Author

    The associated inline acknowledgement review was read, reconciled with the exact head, and recorded; it introduces no unresolved finding.

    @unbraind

    Copy link
    Copy Markdown
    Owner Author

    The associated inline acknowledgement review was read, reconciled with the exact head, and recorded; it introduces no unresolved finding.

    @unbraind

    Copy link
    Copy Markdown
    Owner Author

    The associated inline acknowledgement review was read, reconciled with the exact head, and recorded; it introduces no unresolved finding.

    @unbraind

    Copy link
    Copy Markdown
    Owner Author

    The associated inline acknowledgement review was read, reconciled with the exact head, and recorded; it introduces no unresolved finding.

    @unbraind

    Copy link
    Copy Markdown
    Owner Author

    The associated inline acknowledgement review was read, reconciled with the exact head, and recorded; it introduces no unresolved finding.

    @unbraind

    Copy link
    Copy Markdown
    Owner Author

    Second-order review acknowledgement inventory: all 18 CodeRabbit inline acknowledgement or rate-limit responses and their 18 empty review containers were read and reacted to. They are responses to already-addressed thread comments, contain no new unresolved finding, and are recorded here without further per-thread replies because another reply only creates a new automated acknowledgement container. The substantive correction in discussion_r3763147195 is accepted: equals null matches explicit null, while state missing matches absent fields.

    @unbraind
    unbraind merged commit 17b4076 into main Aug 12, 2026
    32 checks passed
    @unbraind
    unbraind deleted the feat/truthful-context-evidence-contracts branch August 12, 2026 02:26
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment