git:20260902.c090977 to git:20260903.ea4d121

# Guidelines for AI Agents

This repository distributes the IDD (Issue-Driven Development)

workflow — a portable set of `.github/instructions/` files that

wire up a multi-agent issue-driven pipeline for any GitHub

project.

**Canonical reference**: The full, authoritative project guidance

lives in

[`.github/copilot-instructions.md`](.github/copilot-instructions.md).

This file contains tool-specific guidance for Claude. When

Copilot-specific workflow names appear, apply the intent in Claude

using Claude's own interaction model rather than following product

terms literally.

## Minimum requirements

- Match the conversational language to the user's language.

- Write comments and documentation in English unless there is a

clear project-specific reason otherwise.

- When editing `README.md`, also apply the equivalent change to

`README.ja.md`, and vice versa. Keep both files in sync in the

same commit.

- Avoid hard-coded repository file counts in docs unless the

number is mechanically maintained. If count-based wording is

necessary, update every mirrored reference in the same commit.

- If uncertainty, hidden risk, or missing context blocks a safe

change, stop and ask a concise question before proceeding.

- Keep changes small and reviewable. Follow the project's

Conventional Commits rules and keep each commit atomic.

- Do not modify community documents (`CODE_OF_CONDUCT*`,

`CONTRIBUTING*`) without explicit approval.

## Project standards

- **Indentation**: 2 spaces

- **Line endings**: LF only

- **Trailing whitespace**: trimmed except in Markdown

- **Final newline**: always present

- **File naming**: lowercase with hyphens unless a platform

convention requires otherwise

- **Helper sources**: the helper migration to TypeScript is complete —

every `scripts/*.mjs` / `bin/*.mjs` is generated from a

`src/**/*.mts` source by `pnpm run build` and committed; no

hand-written helper `.mjs` path remains. `.mts` is the source of

truth — edit the `.mts`, never the generated `.mjs`.

See [docs/typescript-sources.md](docs/typescript-sources.md).

- **Inline code span wrapping**: a code span may wrap at a word

boundary but must never wrap mid-token (right after a hyphen,

underscore, slash, or dot the token continues through) — CommonMark

renders the break as a literal space and corrupts the token. Put a

command too long for one line in a fenced code block instead. If the

wrap-point character is a hand-added artifact rather than part of

the real value, delete it instead of just relocating the break.

Enforced by `node scripts/audit-code-span-wrap.mjs`

(repository-local; not distributed to `idd-template/`).

- **Bare issue/PR reference wrapping**: a bare `#NNN` reference must

never be the first token of a paragraph, list item, or wrapped

continuation line in prose Markdown — `dprint fmt`'s automatic

line-wrap can relocate it there, and markdownlint's MD018 rule

(`no-missing-space-atx`) then flags it as a malformed ATX heading.

MD018 only fires at zero leading indentation, so it misses the same

drift inside an indented list-item continuation line — do not rely

on the linter alone. Prefer "issue `#NNN`" (or another phrasing that

keeps a word before the `#`) whenever the reference could plausibly

open a sentence, bullet, or wrapped line.

## Key workflow rules

- **Commits**: Follow

[Conventional Commits](https://www.conventionalcommits.org/).

A `.gitmessage` template is available at the repository root.

Write user-facing, lowercase subjects under 72 characters, and

split unrelated changes into separate atomic commits.

- **Branch strategy**: All changes reach `main` through pull

requests (merge commits only). Feature branches may rebase onto

`main` before the first PR-branch push; after publication, sync

from `main` with a normal merge by default instead of rebasing.

See

[`.github/copilot-instructions.md`](.github/copilot-instructions.md#branch-strategy)

for full rules.

- **Merge policy**: This source repository records

`fully_autonomous_merge` as an explicit local IDD dogfooding opt-in

against the distributed `human_merge` default

(applies only to `kurone-kito/idd-skill`). An IDD session may

continue through F3 merge execution only after normal claim,

freshness, CI, advisory, review, and unresolved-thread gates

pass.

- **Discover concurrency**: This source repository also records

`discover.selectionDesync: session-offset` as a local IDD

dogfooding policy (applies only to `kurone-kito/idd-skill`),

spreading concurrent-session A4 Step 2 candidate selection across

a same-score tie band instead of every session converging on the

same lowest-numbered issue, to cut claim races under this

repository's heavy concurrent-session load.

- **Advisory-convergence waiver backstop**: This source repository

also records `ciGate.externalCheckWaivers.mode:

"maintainer-authorized"` with `idd-advisory-convergence` registered

under `ciGate.externalChecks.waivable` as a local IDD dogfooding

policy (applies only to `kurone-kito/idd-skill`), giving a trusted

maintainer a human off-ramp when the autonomous advisory-convergence

loop cannot converge on its own (Refs #1465). See

[`.github/copilot-instructions.md`](.github/copilot-instructions.md#local-external-check-waiver-policy)

for the full rationale.

- **Advisory-convergence deadline**: This source repository also

records `advisoryWait.convergenceDeadline: "PT9H"` as a local IDD

dogfooding policy (applies only to `kurone-kito/idd-skill`),

shortening the maintainer-authorized-waiver deadline from the

distributed `idd-template/` default (`PT24H`) to fit this

repository's more autonomous, higher-concurrency dogfooding setup

(Refs #1465, #2076).

- **Secondary-bot quiet window**: This source repository also records

`advisoryWait.secondaryBotLogin: "coderabbitai[bot]"` and

`advisoryWait.secondaryQuietWindow: "PT1H"` as a local IDD dogfooding

pre-merge readiness treats review as settled. This repository

dogfoods CodeRabbit alongside Copilot and has twice hit CodeRabbit

rate-limiting during a PR's review cycle, each time working around

it with an ad hoc one-hour wait before merging; this config turns

that informal practice into a proper `pre-merge-readiness` blocker

## For IDD work

Open `.github/instructions/idd-overview-core.instructions.md` and the

relevant phase file before starting work. See

[docs/idd-workflow.md](docs/idd-workflow.md) for the cross-agent

entry path and phase routing. See

[Model capability expectations](docs/idd-workflow.md#model-capability-expectations)

before running this loop on a lightweight local or compact cloud model.

## Dogfood: token-cost events

This source repository records IDD phase-boundary timestamps as a local

dogfooding measurement (`docs/token-cost.md`). Source-repo only — never

add this call to `idd-template/` or `.github/instructions/` phase files,

which distribute to adopters with no token-cost data to record.

When Claude runs the IDD loop in this repository, call

```sh

node scripts/token-cost-event.mjs --stage <id> --enter --vendor claude --issue <n>

```

when a listed stage starts, and the same with `--exit` when it ends.

Include `--issue <n>` on every call from `claim` onward, once an issue

is claimed — omit it only for `discover`, which precedes any claim. A

call with no `--issue` is unusable for per-issue attribution (#2418):

the harvester can only join it back to an issue when the number is

recorded on the event itself. Stage ids: `discover`, `claim`, `work`,

`submit-pr`, `review`, `merge`, `cleanup`. Ignore any failure from this

command — it must never block or slow the IDD loop.

## Issue-authoring skill (dogfooded)

The canonical issue-authoring skill bundle lives at

`skills/issue-authoring/`. Edit the canonical bundle, never a

generated copy: `node scripts/sync-docs.mjs --apply` regenerates

derived copies and `node scripts/audit-docs.mjs --check` fails on

drift.

`.claude/skills/issue-authoring/` is a generated mirror of the

canonical bundle's Markdown files (byte-identical per file), so Claude

Code auto-discovers the skill in this repository.