Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 6 additions & 4 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,9 @@ Each entry links the GitHub issue (the canonical spec) and the merge PR (the shi

### Removed

- **Monthly Progress sync and sprint issue publication** — removed 3,758 lines of scripts and dedicated tests after their intended adoption windows finished. Only one monthly issue was ever created (`Progress: April 2026`, #46; none in May–July), and the four sprint issues (#230, #234, #237, #239) were all created on 2026-07-03/04 with none since. No core lifecycle script or dev-relay integration invokes either feature, and `task-progress-reporting` accumulated no Learnings. The task mirrors under `backlog/tasks/` remain core and unchanged. Closes [#340](https://github.com/sungjunlee/dev-backlog/issues/340).
- **Monthly Progress sync and sprint issue publication** — removed 3,758 lines of scripts and dedicated tests after their intended adoption windows finished. Only one monthly issue was ever created (`Progress: April 2026`, #46; none in May–July), and the four sprint issues (#230, #234, #237, #239) were all created on 2026-07-03/04 with none since. No core lifecycle script or dev-relay integration invokes either feature, and `task-progress-reporting` accumulated no Learnings. Closes [#340](https://github.com/sungjunlee/dev-backlog/issues/340).
- **Required task mirrors** — the GitHub-native core now resolves task specification, AC, and lifecycle directly from live Issues. Fresh setup and complete sprint execution require no `backlog/tasks/` or `backlog/completed/`; `sync-pull --legacy-export` remains an explicit one-way diagnostic/rollback boundary. Closes [#347](https://github.com/sungjunlee/dev-backlog/issues/347).
- **Zero-adopter local tracker and generic compatibility machinery** — measured adoption found 0 of 17 consumers selecting a non-default tracker and GitHub remotes in all 18 known consumers. The local JSON store, local lifecycle tests, and generic/local design surface are removed; GitHub failure is fail-loud with no fallback, while Backlog.md remains manual import/explicit export compatibility only. Closes [#348](https://github.com/sungjunlee/dev-backlog/issues/348).

## [0.9.0] — 2026-07-27

Expand All @@ -21,7 +23,7 @@ Net effect: **−2,556 lines** of scripts and tests (26,984 → 24,428) with no
- **Local canonical store is JSON; task files become derived mirrors** (BREAKING for `tracker: local`). `backlog/local-tracker.json` is the sole local authority, and `backlog/tasks/` + `backlog/completed/` are one-way projections — exactly the role they already held in `github` mode. The binding rule: a mirror is **never** parsed back as truth, so the `tracker-task-truth` "never two co-authoritative stores" constraint is satisfied more cleanly than the shape it replaces, where Markdown was canonical *and* hand-editable *and* lock-arbitrated at once. `local-tracker.js` 1,391 → 597 lines. Closes [#321](https://github.com/sungjunlee/dev-backlog/issues/321) / PR [#327](https://github.com/sungjunlee/dev-backlog/pull/327).
- **Concurrent-write safety is revision-based compare-and-swap, not a lock.** The store carries a monotonic `revision`; a mutation reads at N, writes a complete fsynced candidate, and claims `.local-tracker.revision-{N+1}.json` through no-overwrite `link`. A losing writer *helps the existing claim across* — it is content-complete — then re-reads and retries within a bounded budget; exhaustion fails closed rather than writing unconditionally. Crash debris is inert by construction: revision-identified files a later writer can complete or clean, never a mutual-exclusion primitive left in an unknown state.
- **Tracker selection moves to `backlog/.tracker`**, a single line read with `readFileSync().trim()` and validated fail-closed. `config.yml` is never written again — which is what removes the reason its 395-line selection tokenizer existed. It is still *read* for its other fields through the unchanged `lib.js:parseSimpleYaml`. Legacy compatibility is exact: an existing `tracker:` key with no `.tracker` resolves as before and is migrated on the next setup run without editing `config.yml`, so the PR #301 Learning "preserve user YAML bytes" now holds permanently and trivially; a repo with neither still defaults to `github` with zero migration. `setup-dev-backlog.js` 1,007 → 567 lines. Closes [#322](https://github.com/sungjunlee/dev-backlog/issues/322) / PR [#328](https://github.com/sungjunlee/dev-backlog/pull/328).
- **Adapter tiering and a size budget are now design contract**: a seam (`tracker.js`), remote translators (**≤200 lines**, holding no durable state), and exactly one storage substrate (`local`). The rule — *an adapter over 200 lines is not an adapter, it is a substrate; stop and re-tier* — is what keeps "support more trackers" a linear cost. Recorded in `docs/tracker-adapter-design.md` § "Adapter Tiers (v0.9.0)". Closes [#320](https://github.com/sungjunlee/dev-backlog/issues/320) / PR [#326](https://github.com/sungjunlee/dev-backlog/pull/326).
- **Adapter tiering and a size budget are now design contract**: a seam (`tracker.js`), remote translators (**≤200 lines**, holding no durable state), and exactly one storage substrate (`local`). The rule — *an adapter over 200 lines is not an adapter, it is a substrate; stop and re-tier* — is what keeps "support more trackers" a linear cost. Recorded in the [historical v0.9.0 adapter design](https://github.com/sungjunlee/dev-backlog/blob/v0.9.0/docs/tracker-adapter-design.md) § "Adapter Tiers (v0.9.0)". Closes [#320](https://github.com/sungjunlee/dev-backlog/issues/320) / PR [#326](https://github.com/sungjunlee/dev-backlog/pull/326).

### Fixed

Expand Down Expand Up @@ -49,7 +51,7 @@ Headline: **configured tracker adapters** — exactly one adapter owns canonical

### Added

- **Configured tracker adapters — one adapter owns canonical task truth per repo** (O9). A deep, capability-gated tracker seam: the active tracker is chosen only from configuration, defaults to `github` when unset, resolution probes only the configured adapter, and the runtime never silently switches trackers on failure. Required lifecycle and identity stay small; milestones, PR relationships, mirrors, progress issues, comments, and closing semantics are capability-gated and fail closed before mutation. Design frozen in `docs/tracker-adapter-design.md`. Shipped in phases:
- **Configured tracker adapters — one adapter owns canonical task truth per repo** (O9). A deep, capability-gated tracker seam: the active tracker is chosen only from configuration, defaults to `github` when unset, resolution probes only the configured adapter, and the runtime never silently switches trackers on failure. Required lifecycle and identity stay small; milestones, PR relationships, mirrors, progress issues, comments, and closing semantics are capability-gated and fail closed before mutation. Design frozen in the [historical v0.8.0 adapter design](https://github.com/sungjunlee/dev-backlog/blob/v0.8.0/docs/tracker-adapter-design.md). Shipped in phases:
- `tracker.js` configured-only resolver plus the core adapter seam; the `local` slot stays explicitly unavailable until the local adapter lands. Interface and `gh`-coupling inventory were frozen first. Closes [#272](https://github.com/sungjunlee/dev-backlog/issues/272) / PR [#280](https://github.com/sungjunlee/dev-backlog/pull/280) and [#273](https://github.com/sungjunlee/dev-backlog/issues/273) / PR [#282](https://github.com/sungjunlee/dev-backlog/pull/282).
- Tracker-neutral task identity: one exact task-ref seam for GitHub `#N` and local `{PREFIX}-N[.M]`; sprint state exposes additive `tracker`/`id`/`ref` and retains GitHub `issue_number` so existing consumers keep working. Closes [#274](https://github.com/sungjunlee/dev-backlog/issues/274) / PR [#284](https://github.com/sungjunlee/dev-backlog/pull/284).
- GitHub behind the seam: the GitHub adapter owns required lifecycle translation and confines direct `gh` calls to itself plus explicit milestone/mirror/progress/PR/comment/triage transports; core callers resolve only the configured tracker. GitHub is now the frozen compatibility baseline. Closes [#275](https://github.com/sungjunlee/dev-backlog/issues/275) / PR [#286](https://github.com/sungjunlee/dev-backlog/pull/286).
Expand Down Expand Up @@ -83,7 +85,7 @@ Headline: **configured tracker adapters** — exactly one adapter owns canonical
- `skills/dev-backlog/SKILL.md` reassess-signal paragraph compressed to defer accounting details to `references/integration-contract.md`; craftkit provenance stated once per SKILL.md; stale "upcoming backlog-doctor" wording moved to present tense. Closes [#246](https://github.com/sungjunlee/dev-backlog/issues/246).
- `skills/dev-backlog/references/integration-contract.md` component example swapped to the live `sprint-execution` slug. Closes [#248](https://github.com/sungjunlee/dev-backlog/issues/248).
- `docs/spec-system-design.md` gains a dated provenance note for the 0.7.0 spec-* move; the dead research-survey link now cites git history (pre-`cd31a2b`) with the restore decision tracked in [craftkit#124](https://github.com/sungjunlee/craftkit/issues/124). Closes [#249](https://github.com/sungjunlee/dev-backlog/issues/249).
- `spec/system-map.md` "Executable Evidence" now records the O8/O9 acceptance proof (PR [#303](https://github.com/sungjunlee/dev-backlog/pull/303)) as merged and both objectives `[validated]`, and adds a Project-Wide Invariant for Windows-first-class execution; the `docs/tracker-adapter-design.md` twin line is synced. Closes [#315](https://github.com/sungjunlee/dev-backlog/issues/315) / PR [#317](https://github.com/sungjunlee/dev-backlog/pull/317).
- `spec/system-map.md` "Executable Evidence" now records the O8/O9 acceptance proof (PR [#303](https://github.com/sungjunlee/dev-backlog/pull/303)) as merged and both objectives `[validated]`, and adds a Project-Wide Invariant for Windows-first-class execution; the [historical v0.8.0 adapter design](https://github.com/sungjunlee/dev-backlog/blob/v0.8.0/docs/tracker-adapter-design.md) twin line is synced. Closes [#315](https://github.com/sungjunlee/dev-backlog/issues/315) / PR [#317](https://github.com/sungjunlee/dev-backlog/pull/317).
- Signal-driven reassess: the post-multi-track reassess cycle ran and found no v0.8.0 release blockers (backlog-doctor 8/8, capabilities-doctor ok, component-lint clean); report `backlog/triage/2026-07-20-reassess.md`. Closes [#312](https://github.com/sungjunlee/dev-backlog/issues/312) / PR [#316](https://github.com/sungjunlee/dev-backlog/pull/316).

### Removed
Expand Down
9 changes: 5 additions & 4 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,16 +24,17 @@ The `spec-charter`, `spec-system-map`, and `spec-grill` skills moved to [craftki

- **GitHub Issues = source of truth** for task definitions (what to do)
- **Sprint files = execution hub** (how to do it, context, notes, progress)
- **Task files = thin GitHub mirror** (sync cache, AC checkboxes only)
- **Backlog.md compatible** — task file format follows Backlog.md; sprints/ is a custom addition
- **No required GitHub task mirror** — resolve task intent and AC from live Issues
- **Legacy task export is explicit** — `sync-pull --legacy-export` is rollback/diagnostic material only
- **Backlog.md compatible** — legacy task exports follow Backlog.md shape; sprints/ is a custom addition
- **Cross-platform** — works on Claude Code and Codex (both have `gh` CLI)
- **Explicit sync** — pull/push is manual; no silent background sync
- **No hidden sync** — provider writes and legacy exports are deliberate operations

## Two-Layer Architecture

```
GitHub (what) ↔ gh CLI ↔ backlog/sprints/ (how + context)
backlog/tasks/ (thin mirror)
backlog/tasks/ (optional legacy export)
```

## Project Spec Home
Expand Down
38 changes: 15 additions & 23 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,18 +17,15 @@ under Upgrade behavior.

README.md is the product overview and human quick start. The agent execution contract, sprint-file rules, and full script reference live in [skills/dev-backlog/SKILL.md](skills/dev-backlog/SKILL.md).

The implementation still exposes local-tracker and task-export compatibility
while the 2026-08 migration is staged. Those paths are frozen, are not the
target product boundary, and never become co-authoritative. See the
The zero-adopter local tracker has been removed. GitHub is the only runtime
task authority. Backlog.md-compatible files remain an explicit one-way legacy
import/export boundary and never become co-authoritative. See the
[authority and routing contract](skills/dev-backlog/references/authority-contract.md).

```text
backlog/.tracker: github | local
backlog/.tracker: github
|
+-- github -> GitHub Issues (canonical) -> no required task mirror
|
`-- local -> backlog/local-tracker.json (canonical, no gh)
-> tasks/ derived compatibility projections
`-- GitHub Issues (canonical) -> no required task mirror

backlog/sprints/ execution hub: plan, context, progress
^
Expand Down Expand Up @@ -110,22 +107,16 @@ bash /path/to/dev-backlog/skills/dev-backlog/scripts/sprint-close.sh backlog
Fresh GitHub setup creates only `backlog/.tracker` and `backlog/sprints/`;
`backlog/tasks/` and `backlog/completed/` are not required or created.

Transition compatibility only: an existing fully offline repository may still
choose `--tracker local`. In that explicitly selected legacy mode,
`backlog/local-tracker.json` remains its sole task authority; `backlog/tasks/`
and `backlog/completed/` are derived read-only projections. Mutate the JSON
authority only through the configured tracker lifecycle, use normalized refs
such as `BACK-1` in the Plan, and run the same `status`, `next`, and
`sprint-close` commands. This is separate from the GitHub-native core. Local
mode deliberately does not invent milestones, PR relationships, comments, or closing-keyword links.
Those requests fail before side effects with actionable remediation; JSON-capable
commands return the same structured error contract. Do not adopt local mode for
new repositories or add features to it during the GitHub-native migration.
Backlog.md compatibility is a one-way legacy boundary. Import means a
human-reviewed compatible Markdown record is used to create or amend a GitHub
Issue. Export is the explicit `sync-pull.js --legacy-export` diagnostic or
rollback snapshot. Runtime execution never reads task files as task truth, and
the Backlog.md CLI or runtime is never required.

For task `list`, `read`, `create`, `update`, and `close`, the stable invocation
boundary is the configured adapter exported by `scripts/tracker.js`. Operators
and agents resolve it with the target `backlogDir` and call those methods in
either mode; the exact procedure and signatures are documented in
the GitHub mode; the exact procedure and signatures are documented in
[the process guide](skills/dev-backlog/references/process.md#required-core-lifecycle-invocation-boundary).

### Upgrade behavior
Expand All @@ -135,16 +126,17 @@ There is zero automatic tracker-selection migration. A repository with neither
in GitHub mode with its existing `#N`, numeric `issue_number`, milestone,
comment, and closing behavior. When `.tracker` is
absent, runtime reads a legacy YAML selection as a compatibility fallback.
Running `setup-dev-backlog.js` migrates that resolved choice to `.tracker`
Only the legacy value `github` is accepted. Running `setup-dev-backlog.js`
pins that resolved choice to `.tracker`
without editing `config.yml`; setup never migrates task files and runtime never
chooses a tracker from availability or failure.
Existing automation that invokes `sync-pull.js` without a flag must add
`--legacy-export`; otherwise the command refuses before provider access or task
materialization. This opt-in preserves rollback/diagnostic exports without
putting them back on the normal workflow. It is an intentional CLI migration,
not an automatic tracker or task-data migration.
The implementation-level contract and proof map live in
[docs/tracker-adapter-design.md](docs/tracker-adapter-design.md).
The retained compatibility seams, consumer evidence, and subtraction proof
live in [docs/compatibility-subtraction.md](docs/compatibility-subtraction.md).

Then use the skill during your coding session:

Expand Down
Loading
Loading