Skip to content

chore(repo): gitignore root .ai/ orchestrator-workflow run state#66

Merged
LanNguyenSi merged 1 commit into
masterfrom
chore/gitignore-ai-run-state
Jul 25, 2026
Merged

chore(repo): gitignore root .ai/ orchestrator-workflow run state#66
LanNguyenSi merged 1 commit into
masterfrom
chore/gitignore-ai-run-state

Conversation

@LanNguyenSi

Copy link
Copy Markdown
Owner

Closes the preflight deadlock caused by untracked orchestrator-workflow run state.

Problem

Untracked run directories under .ai/runs/ (00-goal.md through 06-handoff.md per run) make the worktree dirty. harness preflight then fails its clean-worktree check, leaves the preflight tag unwritten, and the investigation gate deadlocks. Observed on the MacBook during the toolchain-parity rollout on 2026-07-23; the run files had to be parked on a local-only branch just to get a clean tree.

Run state is orchestration bookkeeping and does not belong in commits or PRs (operator rule, 2026-06-19).

Why the pattern is root-anchored

The rule is /.ai/, not .ai/. An unanchored pattern matches at every directory level and would also swallow packages/agent-memory-sync/.ai/ and packages/memory-digest-cli/.ai/, which hold 8 tracked per-package agent docs (AGENTS.md, ARCHITECTURE.md, DECISIONS.md, TASKS.md). Those files stay tracked either way, but an unanchored rule hides them from every gitignore-aware search tool and makes git add -A silently skip new files there, while both packages' docs/ways-of-working.md tell agents to read .ai/AGENTS.md first.

This was caught in review; the first revision of this branch had the unanchored form.

Scope

Nothing under the repo-root .ai/ is tracked, so the ignore takes effect immediately. The harness split-ignore special case (tracking .ai/workflow/ and .ai/solution-acceptance.json while ignoring only .ai/runs/) does not apply here: this repo has neither, and no reference to solution-acceptance. If it ever enables solution-acceptance, adopt that split by narrowing the pattern to /.ai/runs/ rather than by appending ! negations, which git cannot honour under an excluded parent directory.

Verification

git check-ignore -v .ai/runs
  -> .gitignore:10:/.ai/  .ai/runs

git check-ignore --no-index -v packages/agent-memory-sync/.ai/AGENTS.md
  -> not ignored (exit 1)

rg --hidden --files -g '**/.ai/**'
  -> all 8 package docs still discoverable

Diff is one file, 7 insertions. Reviewed by a review subagent over two passes; the second pass ran 12 deterministic probes with controls and approved with no finding above low.

Refs: b2c6efec-629f-49b2-82b0-6685966bcece

Untracked run directories under .ai/runs/ (00-goal.md through 06-handoff.md
per run) made the worktree dirty, which failed `harness preflight`'s
clean-worktree check and deadlocked the investigation gate. Observed on the
MacBook during the toolchain-parity rollout on 2026-07-23; the run files had
to be parked on a local-only branch to get a clean tree.

Run state is orchestration bookkeeping and does not belong in commits or PRs
(operator rule, 2026-06-19).

The pattern is root-anchored (`/.ai/`, not `.ai/`) on purpose. An unanchored
pattern matches at every directory level and would also swallow
packages/agent-memory-sync/.ai/ and packages/memory-digest-cli/.ai/, which
hold 8 tracked per-package agent docs (AGENTS.md, ARCHITECTURE.md,
DECISIONS.md, TASKS.md). Those files stay tracked either way, but an
unanchored rule hides them from every gitignore-aware search tool and makes
`git add -A` silently skip new files there — while both packages'
docs/ways-of-working.md tell agents to read `.ai/AGENTS.md` first.

Nothing under the repo-root .ai/ is tracked, so the ignore takes effect
immediately. The harness split-ignore special case (tracking .ai/workflow/
and .ai/solution-acceptance.json while ignoring only .ai/runs/) does not
apply: this repo has neither, and no reference to solution-acceptance. If it
ever enables solution-acceptance, adopt that split instead.

Verified:
  git check-ignore -v .ai/runs
    -> .gitignore:10:/.ai/  .ai/runs
  git check-ignore --no-index -v packages/agent-memory-sync/.ai/AGENTS.md
    -> not ignored (exit 1)
  rg --hidden --files -g '**/.ai/**'
    -> all 8 package docs still discoverable

Refs: b2c6efec-629f-49b2-82b0-6685966bcece

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@LanNguyenSi LanNguyenSi added review:tests-pass merge-approval gate prerequisite review:checklist-complete merge-approval gate prerequisite review:comments-resolved merge-approval gate prerequisite review:scope-matches-task merge-approval gate prerequisite review:evidence-logged merge-approval gate prerequisite labels Jul 25, 2026
@LanNguyenSi
LanNguyenSi merged commit fdc2d8a into master Jul 25, 2026
5 of 7 checks passed
@LanNguyenSi
LanNguyenSi deleted the chore/gitignore-ai-run-state branch July 25, 2026 08:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

review:checklist-complete merge-approval gate prerequisite review:comments-resolved merge-approval gate prerequisite review:evidence-logged merge-approval gate prerequisite review:scope-matches-task merge-approval gate prerequisite review:tests-pass merge-approval gate prerequisite

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant