Local Issues

Project-local issue tracker under .aiwg/issues/

Local Issues

Prompt-first procedure: Describe the outcome you want in your agent conversation. The agent should select and load the appropriate AIWG assets, explain material changes, request any needed approval, and report verification evidence. Exact commands and flags appear only in the CLI reference.

AIWG can keep a project-local issue tracker under `.aiwg/issues/` for projects that do not use Gitea or GitHub as the working tracker. The local tracker is a Git-friendly store: issue bodies live in markdown files, event metadata lives in JSONL files, and indexes are rebuildable.

During agent-led project setup, the assistant may use the agent-owned setup operation to configure `.aiwg/aiwg.config` so issue operations route to the local store by setting `remotes.issue_tracker` to `local`. This does not migrate external issues by itself; use the import/export commands below for explicit migration or synchronization work.

Layout

.aiwg/issues/
├── config.json
├── next-id
├── items/
│   └── ISSUE-0001.md
├── events/
│   ├── ISSUE-0001.jsonl
│   └── bodies/
│       └── evt-....md
├── index/
│   └── issues.index.json
└── locks/

The canonical files are `items/` and `events/`. The `index/` directory is a cache and can be rebuilt with the agent-owned issue operation.

Basic Commands

Use AIWG to complete this documented outcome: Basic Commands
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Every new local issue is policy-planned before its first write. Safe drafts remain one issue. Drafts that cross an enforced policy boundary are split into independently assessed issues with stable provenance markers, dependency order, and sibling links. Flagged drafts require the digest shown by `issue plan`:

Use AIWG to complete this documented outcome: Every new local issue is policy-planned before its first write. Safe drafts remain one issue. Drafts that cross an enforced policy boundary are split into independently assessed issues with stable provenance markers, dependency order, and s
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Rejected drafts that cannot be separated produce suggestions and make no filesystem change. A partial multi-issue result includes the next segment and all stable markers; retrying the same draft reuses matching issues instead of duplicating them. The `issue-create` skill applies this same composer before Gitea, GitHub, Jira, Linear, and higher-level workflow writes.

the agent-owned issue operation can filter by status, label, type, priority, assignee, and search text. `issue-audit the provider option local` and `address-issues the provider option local` consume bounded slices from the same provider instead of reading the whole backlog.

Label filters and workflow mutations should use stable roles from `.aiwg/aiwg.config` `issues.labels`; see Issue Label Taxonomy. A role may map to a local-specific string through `provider_names.local`, while retaining the same semantics used by Gitea and GitHub.

Fortemi Core Migration Note

Local issue search remains served by the local issue provider in the Fortemi Core migration preview. The rebuildable `.aiwg/issues/index/issues.index.json` cache is still the source for the agent-owned issue operation and related filters. the agent-owned issue operation commands intentionally do not accept `the backend option fortemi-core`; use the local issue provider for issue operations and use the agent-owned index operation commands for artifact-index Fortemi Core queries. Fortemi exports may include `aiwg.issue` records if a later ADR joins local issues into the shared artifact index, but this does not change the local issue CLI contract or require a Fortemi backend for issue operations.

Import And Export

Use snapshots to move issue state between local issues and external trackers:

Use AIWG to complete this documented outcome: Use snapshots to move issue state between local issues and external trackers
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Use the live option when the CLI should read from or write to the provider API directly instead of a snapshot file:

AIWG_GITEA_TOKEN=... the agent-owned issue operation import the from option gitea the live option the repo option org/repo the external-id option 1463
GITHUB_TOKEN=... the agent-owned issue operation import the from option github the live option the repo option org/repo the external-id option 42
AIWG_GITEA_TOKEN=... the agent-owned issue operation export PROJECT-0001 the to option gitea the live option the repo option org/repo
GITHUB_TOKEN=... the agent-owned issue operation export PROJECT-0001 the to option github the live option the repo option org/repo

Live export creates an external issue when the local issue has no matching `source.external_id`. If the local issue already points at the target provider, live export fetches the remote issue first and refuses to mutate when conflicts are present. Review conflicts with the agent-owned issue operation or pass the force option only after choosing the local version as the winner. Posted comments are mapped back to local event metadata automatically.

An imported snapshot preserves the external issue ID and URL in the issue frontmatter:

source:
  provider: gitea
  external_id: "1463"
  external_url: https://git.example.test/org/repo/issues/1463
links:
  external:
    - https://git.example.test/org/repo/issues/1463

Imported comments keep their external comment IDs on local event metadata. Exported comments include local event IDs so a later posting step can map external comment IDs back to local events.

Use AIWG to complete this documented outcome: Imported comments keep their external comment IDs on local event metadata. Exported comments include local event IDs so a later posting step can map external comment IDs back to local events.
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

`comment-map.json` is an array:

[
  {
    "local_event_id": "evt-local",
    "external_comment_id": "51710"
  }
]

Conflict Reports

Before any two-way sync mutates either side, generate and inspect a conflict report:

Use AIWG to complete this documented outcome: Before any two-way sync mutates either side, generate and inspect a conflict report
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

The report compares local and external title, body, status, labels, and mapped comment bodies. A non-empty `conflicts` array means an operator or higher-level sync policy must choose the winner before writing changes.

Backup Guidance

For local-only issue work, commit or stash canonical issue files before bulk operations:

git status -- .aiwg/issues
git add .aiwg/issues/items .aiwg/issues/events .aiwg/issues/config.json .aiwg/issues/next-id
git commit -m "backup local issue state before sync"

For one-off backups outside Git, archive the canonical files and skip transient locks:

zip -r aiwg-issues-backup.zip .aiwg/issues -x ".aiwg/issues/locks/*"

Do not store external tracker API tokens in `.aiwg/issues/`, `.aiwg/aiwg.config`, or snapshot files. Keep credentials in environment variables, the OS credential store, or provider-specific CLI configuration. Live sync reads `AIWG_GITEA_TOKEN` or `GITEA_TOKEN` for Gitea, and `AIWG_GITHUB_TOKEN` or `GITHUB_TOKEN` for GitHub. Use the api-url option for non-default Gitea or GitHub Enterprise API endpoints.

Git Conflict Guidance

Resolve conflicts by preserving canonical records first:

  • `items/ISSUE-0001.md`: keep valid YAML frontmatter, then merge the markdown body normally.
  • `events/ISSUE-0001.jsonl`: preserve every complete JSON line from both sides unless the same event ID appears twice.
  • `events/bodies/*.md`: keep body files referenced by surviving JSONL events.
  • `config.json` and `next-id`: keep the highest observed `next` value so IDs are not reused.
  • `index/*`: rebuild after resolving canonical files.

After conflict resolution:

Use AIWG to complete this documented outcome: After conflict resolution
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

If an event line is damaged, recover the body file first, then recreate the event as a new comment rather than hand-editing an uncertain event ID.