Tracker

The tracker mirrors the workflow chain into an issue tracker: as you approve artifacts, insrc creates and links the matching issues so the whole define → design → plan → build hierarchy is visible to a team that never opens the daemon. It's opt-in and provider-pluggable — GitHub is the only adapter today (driven through the gh CLI), with the seams in place for Jira and others.

Nothing in the workflow chain is GitHub-specific — it speaks a small vocabulary (Epic / Story / Task issues, parent→child links, a status label, and a design-summary comment). A provider is an adapter behind that vocabulary. Two design principles carry over from the rest of insrc: we don't own the connection (the GitHub adapter shells out to your authenticated gh — no API keys stored, no direct REST), and the tracker only ever touches issues it created (it adopts an existing ref by label, never edits or duplicates someone else's issue).

What it mirrors

Issue titles lead with the hierarchical workflow id; the rendered .md artifact is re-written on approval to carry a **Tracker:** owner/repo#N link, so the doc points at the issue and the issue points back at the doc. Native issue types (Epic/Story/Task) are applied when the org has them and fail open to an untyped issue when it doesn't. A small set of status labels (insrc:in-progress, insrc:blocked) is what tracker.sync reads back.

Setup

One-shot bootstrap that gets a repo's tracker ready. Run it from the CLI (or the TUI command bar):

$ insrc # then, in the ':' command bar:
: tracker setup            # labels + native issue types
: tracker setup --project   # also create a Project + its board views

The engine walks an idempotent, non-fatal checklist and reports each step as done / already / manual / skipped / failed. It performs every automatable step (create the insrc:* labels, create the org issue types, optionally create a Project) and, for the steps a machine can't complete, returns the exact command to run — e.g. an org issue-type create that needs the admin:org scope, or the UI-only Project board views. A failure or manual gate on one step never blocks the others.

Config

Optional, at ~/.insrc/github.json. The tracker is opt-in: with no matching entry (or no file at all) the adapter resolves to none and both auto-push and the manual tracker.* workflows are disabled. A repo without an explicit entry falls back to its git remote's owner/repo and the built-in label/type defaults, so the common case needs no config beyond "type": "github".

{
  "default": {
    "type":  "github",
    "owner": "myorg",
    "repo":  "myrepo",
    "pushTasks":       false,
    "commitArtifacts": true
  },
  "repos": {
    "/abs/path/to/repo": { "type": "github", "owner": "myorg", "repo": "other-repo" }
  }
}

The resolved target for a repo comes only from its own per-repo entry or its own git remote — a global default never silently retargets a repo it wasn't configured for.

Usage

Automatic — on approval

Once a repo has a github config, approving an artifact pushes the matching issue with no extra command (the deterministic path — used by a human insrc workflow approve or a non-GitHub-capable model):

• Approve the HLD → create/adopt the Epic issue.
• Approve an LLD → create/adopt the Story issue and splice it into the Epic's task list.
• In both cases: write the ref into the artifact's meta.tracker, re-render the .md with the tracker link, and post the design summary as an issue comment.

Manual — the tracker.* workflows

For explicit control (e.g. a batch push, a status refresh, or attaching a design summary), the three tracker workflows run via insrc_workflow_run (or the CLI):

tracker.sync and tracker.post require a prior tracker.push (they resolve the issue refs off the Epic's meta) and only approved amendments post. As with the whole chain, the tracker enforces its own scope boundary: it never edits an issue it didn't create.

Other providers

GitHub is the first adapter, not the only intended one. The provider is selected by the config type field and isolated behind three seams — config resolution (src/workflow/config/github.ts), the issue operations (src/workflow/tracker/github.ts: create typed issue, link sub-issue, comment, set status label), and the shared renderers/conventions that turn an artifact into a title + body + summary. A new adapter (say Jira) implements the same operation set against its own API and registers a "type": "jira" config shape; the define → design → plan → build pipeline, the approve-time hooks, and the tracker.push / sync / post workflows are unchanged, because they only ever speak Epic/Story/Task + comment + status. Until such an adapter lands, github and none are the supported values.