[Bug]: Kiro IDE fs_read guard denies .kiro/ reads when global gitignore excludes it — repo !.kiro/ negation not honored, blocks all stages; --doctor misses it

[omaraws]

Description

On the Kiro IDE harness, the agent's fs_read permission guard denies reads of any path matching a pattern in the global git excludes file (~/.config/git/ignore). When that global file contains .kiro/ (a common personal-harness setup — mine is installed by a separate ~/.agents config), every read under .kiro/ is denied.

The framework already ships the intended mitigation in the project .gitignore (!.kiro/, inside the # AI-DLC:gitignore block's project-scoped override), but Kiro's guard does not honor that repo-level negation, nor does it consult git's actual ignore resolution. git check-ignore correctly reports the path as not ignored, yet the guard still denies it and cites the global file as the source.

Because every stage body, agent persona, protocol module, and knowledge file lives under .kiro/, this blocks the workflow completely — no stage can run.

Separately, /aidlc --doctor does not catch this: it reports all project checks green because it never verifies that the active harness can actually read a known .kiro/ file.

Steps to Reproduce

1. On macOS with Kiro IDE, have a global git excludes file that ignores .kiro/:

   # ~/.config/git/ignore
   .kiro/
   

   (Confirm it is the active excludesfile; here it is git's default ~/.config/git/ignore.)
2. Open an AI-DLC project whose committed .gitignore carries the shipped project-scoped override !.kiro/.
3. Start a workflow (/aidlc <scope>) so the orchestrator emits the first run-stage directive (e.g. Intent Capture).
4. Observe the agent attempt to read a stage file, e.g. .kiro/aidlc-common/stages/ideation/intent-capture.md.

Expected Behavior

The read succeeds. The project's !.kiro/ negation (and/or git's own ignore resolution, which reports the path as not-ignored) should un-block reads of tracked .kiro/ files, so stages can run. The guard should not deny a path that git check-ignore reports as not-ignored.

Additionally, /aidlc --doctor should detect and report the condition (a .kiro/ file is not readable by the active harness) with a concrete remedy, rather than passing all checks.

Actual Behavior

The read is denied:

Tool call denied by user's permissions.
Rule: deny fs_read matching ".kiro/"
Source: /Users/omaraws/.config/git/ignore.

Meanwhile git itself un-ignores the path (exit 1 = not ignored):

$ git check-ignore -v .kiro/aidlc-common/stages/ideation/intent-capture.md
$ echo $?
1

So the guard's gitignore evaluation diverges from git's: it matches the global .kiro/ pattern and ignores both the repo-level !.kiro/ negation and git's resolved state. Every subsequent stage read fails the same way, and the workflow cannot proceed past the first run-stage directive.

/aidlc --doctor reported 0 problems, 2 warnings (36 project checks passed) and did not surface the read block.

AI-DLC Version

v2 (current on main)

Release / Commit

Installed runtime aidlc 2.8.2; repo clone at v2.8.1-11-g0865300b (0865300b).

AI-DLC Phase

Not phase-specific (blocks all stages; first observed entering Ideation / Intent Capture).

Harness

Kiro IDE

AI Model

Claude Opus 4.8

Environment

• OS: macOS 26.6.2
• Harness: Kiro IDE
• Global excludesfile: ~/.config/git/ignore containing .kiro/
• Project .gitignore: ships the AI-DLC block plus the project-scoped !.kiro/ override
• git: repo initialized; git check-ignore confirms .kiro/ and nested files are not ignored

Additional Context

Root cause lives in Kiro IDE's fs_read guard (a naive gitignore matcher that reads the global excludes file, does not reconcile cross-file negations, and does not consult git's index/resolution) — which AI-DLC cannot patch directly. But the impact is AI-DLC-specific and total, so two framework-side improvements would prevent a silent, total block:

1. Doctor readability probe — add a check that attempts to read a known-tracked .kiro/ file under the active harness and fails loudly with a remedy when it is blocked. This is the fast, deterministic signal that was missing here.
2. Known-issue doc + remedy — document that a global .kiro/ ignore breaks Kiro IDE despite the shipped !.kiro/ negation, with the workaround: add an fs_read allow for the workspace .kiro/** in ~/.kiro/settings/permissions.yaml (an explicit allow overrides the gitignore-derived deny). Adjusting the global excludes file is broader and re-introduces the personal-config leak that file exists to prevent, so it is not the recommended fix.

Workaround confirmed to be needed: git init + !.kiro/ makes git un-ignore .kiro/, but the Kiro guard still denies, so the permissions.yaml allow (or removing .kiro/ from the global excludes) is required to proceed.

Adjacent but distinct existing issues (different guard — plan-approval mutation classification, not gitignore-based denial): #1039, #965.

[wowzoo]

#1146

Thank you for finding this, and for bringing the git check-ignore exit code — that is what makes the divergence provable rather than arguable.

One correction to a premise, because your second proposal rests on it: AI-DLC does not ship a !.kiro/ negation. The # AI-DLC:gitignore managed block you name is real — installation writes it and our install tests assert its markers — but its contents are only paths under aidlc/, with no .kiro rule, negating or ignoring. The generated .gitignore is byte-identical to the authored one, !.kiro appears nowhere in the repository, and all seven harnesses agree. So the !.kiro/ in your project comes from your own configuration.

The block itself is a Kiro-side defect. Two things settle it. AI-DLC measurements are at 77116239; the Kiro-side reading comes from the shipped agent bundle of Kiro IDE 1.0.437, so it is version-specific.

• Each ignore file is compiled into its own matcher, and a negation is evaluated only within the file that carries it. A project-level !.kiro/ therefore cannot undo a global .kiro/ — they are independent sources rather than one ordered list. That is also why git check-ignore disagrees: git evaluates them as a single ordered set, with repository rules taking precedence over global ones.
• The permissions.yaml fs_read allow will not help either. Kiro registers git's global excludes file as an ignore source scoped to the fs_read capability, and a match becomes a policy decision with effect: deny. Kiro documents deny-overrides across every scope, with no allow able to clear a deny.

Kiro's ignore documentation states that the syntax is standard gitignore syntax and lists ! negation as supported, so that divergence is worth raising on their tracker — it is the only route to a real fix rather than a workaround, and the two points above are the evidence, so it does not have to be re-derived.

On our side we are looking at detection only. --doctor already opens every installed stage body, and it still reported 0 problems in your environment, because those reads happen in a subprocess and are not agent fs_read calls — so anything useful here has to test the condition rather than attempt another read. Whether that lands as a doctor check, a troubleshooting entry, or both is what we are working out.

One thing still unmeasured: whether /.kiro/ and **/.kiro/ anchor differently from .kiro/. That needs the IDE agent rather than a code read.

[apackeer]

Fix is up in #1161, detection-side as discussed above; the guard itself stays a Kiro IDE issue.

What we confirmed before writing it

• Kiro's own docs settle both halves of the diagnosis. Kiroignore lists git's global excludes file (in git repositories) and ~/.kiro/settings/kiroignore as sources the IDE honours automatically, with workspace files governed by the kiroAgent.agentIgnoreFiles setting. Permissions states deny-overrides with "no precedence between scopes", which is why the permissions.yaml fs_read allow cannot clear the gitignore-derived deny — so we deliberately did not ship that as the remedy.
• We also reproduced the per-file evaluation mechanically: evaluating your global file alone with git's own matcher hides the stage path, while the project with !.kiro/ does not. That is the exact divergence your check-ignore exit 1 showed.

What --doctor now does on Kiro IDE (.kiro/agents/aidlc.md present)

It evaluates each ignore source Kiro IDE honours on its own — the global excludes file, ~/.kiro/settings/kiroignore, the project .gitignore, and .kiroignore — against a stage path under .kiro/, using git -c core.excludesFile=<file> check-ignore in a scratch repository so only that one file applies. On your setup it reports:

fail  Kiro IDE ignore sources: ~/.config/git/ignore:1 ".kiro/" hides .kiro/ - the IDE's fs_read guard denies every stage, agent, and protocol read
      fix: remove or narrow the ".kiro/" rule in ~/.config/git/ignore; Kiro IDE evaluates each ignore file on its own, so a "!.kiro/" in another file and a permissions.yaml fs_read allow do not override it ...

Global-source matches fail; project .gitignore/.kiroignore matches warn, since doctor cannot read the IDE setting that decides whether those apply. A Kiro IDE Read Denials troubleshooting entry carries the same explanation and the denial text verbatim.

Remedy for your case. Remove .kiro/ from ~/.config/git/ignore. To keep hiding personal .kiro/ directories from git in other repositories without a global rule, put the pattern in each repository's .git/info/exclude: git honours it, and it is not among the sources Kiro documents — though we have not measured that against the IDE, so if you try it, a report either way would be useful.

The cross-file negation divergence is still worth filing on Kiro's tracker with the evidence above; that remains the only route to the guard itself behaving like git check-ignore.