[Marukome0743]

Summary

Fixes #2474. An ignored exact-file source claim now explains why it was refused and how to register intended source, so index-only additions or jj tracking are not mistaken for HEAD membership.

Changes

• Extend only the ignored exact-file refusal with HEAD membership, explicit registration, and index-only/jj tracking guidance.
• Include the offending path in a concrete {"version":1,"paths":[...]} example for the source repository's root registry, with instructions to preserve existing entries.
• Explain that output which is not source should be omitted from exact claims and excluded rather than registered.
• For gitignored exact paths under dependency folders or sensor caches that cannot be registered, keep the short refusal and say to omit the exact claim, without a paths registration example. Reuse the existing physical source-exclusion predicate.\n- Preserve admission rules and directory diagnostics; add regression tests and troubleshooting guidance.\n- Rebase after fix(review): honor registry exclusions in directory source claims #2475 and retain both the directory-exclusion and exact-file guidance in troubleshooting.

User experience

Before: an exact path already listed in the manifest received the unconditional-sounding is ignored by Git and cannot be source-review evidence, without explaining the supported remedy.
After: the refusal says the file is neither tracked at HEAD nor explicitly registered, explains that index-only additions or jj tracking alone do not establish HEAD membership, and gives a path-specific registration example. It distinguishes reviewed source from output to exclude. Directory claims keep their separate ignored-descendant check.

Checklist

• I have reviewed the contributing guidelines
• I have performed a self-review of this change
• Changes have been tested
• Changes are documented
• If this change adds an input to any fingerprint, epoch, or receipt identity, the description names the human-visible change it detects

No fingerprint, epoch, receipt identity, or admission rule changes.

Test plan

• Current revision: all 69 tests in tests/unit/t305-per-unit-attribution-receipts.test.ts passed, including the gitignored node_modules/pkg/index.js regression. Typecheck, lint and deterministic packaging passed.

• Reproduced the existing behavior before changing the diagnostic: identical ignored bytes are refused before/after index force-add, admitted through registration (which overrides exclude), and admitted when HEAD tracks the file.

• mise exec bun@1.4.2 -- bun scripts/package.ts

• mise exec bun@1.4.2 -- bun scripts/package.ts --check — deterministic across all seven harnesses.

• mise exec bun@1.4.2 node@24.21.0 -- bun run typecheck

• mise exec bun@1.4.2 node@24.21.0 -- bun run lint — passes with existing informational diagnostics only.

• mise exec bun@1.4.2 -- bun test tests/unit/t305-per-unit-attribution-receipts.test.ts --test-name-pattern 'strict source-manifest validation|review request refuses an explicitly claimed ignored path' — 11 passed.

• mise exec bun@1.4.2 -- bun test tests/unit/t314-source-freshness-receipts.test.ts --test-name-pattern 'ignored output rewritten during the stage|review request fails closed when source is ignored inside an initialized submodule' — 2 passed.

Acknowledgment

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the project license.

[apackeer]

Thanks, the new refusal text is the right steer: it names the exact paths line for .aidlc-source-paths.json, says force-add does not count, and never sends the agent to the person's .gitignore (the test pinning .gitignore unchanged is a nice touch).

Two things for one push:

1. Rebase after #2475 lands. Both PRs edit the same section of docs/guide/15-troubleshooting.md; keep both parts.
2. One case where the line is wrong. A gitignored file under a folder AI-DLC never treats as source (SOURCE_FINGERPRINT_HARD_EXCLUDED_DIRS, such as node_modules/pkg/index.js, or an isAidlcSensorCachePath path) still reaches the new text, and following its paths line makes the registry invalid, so the agent gets the same refusal again. In the exact-file branch, when the path lies under one of those folders, return the short refusal plus "it lies under a folder AI-DLC never treats as source; omit this exact claim", with no registration line. Add one t305 case: a gitignored node_modules/pkg/index.js claim whose reason contains "omit this exact claim" and not "paths":[.

Optional, your call: "or jj tracking" can go; it is true but adds nothing for the agent.

Once that push is in and CI is green, we'll approve and queue it.

[Marukome0743]

Thank you. Addressed in 6af9765, rebased onto main after #2475 merged. Both troubleshooting sections are preserved.

The ignored exact-file refusal now reuses the existing physical source-exclusion predicate for dependency folders and sensor caches. Those paths say to omit the exact claim and receive no paths registration example. Added the requested gitignored node_modules/pkg/index.js regression.

All 69 t305 tests, typecheck, lint and deterministic packaging passed. The pushed commit is Verified, and the PR description was updated.

[leandrodamascena]

Thanks for the follow-up. I reviewed the current head 3ed52857e against b72b91d16. This follows the direction Arden reviewed: explain how to recover while keeping the source admission rules unchanged.

Both requested changes are addressed. The directory guidance from #2475 is preserved, and node_modules claims now correctly say to omit the claim. I also pushed a one-line Biome limit adjustment in 3ed52857e, since the rebased file had exceeded the old limit and was failing lint.

All 77 selected tests, typechecks, lint, and packaging determinism checks passed locally. I found no further issues. CI has now passed on this head.

Approved