Tracker & Gate Audit Rules
.forge/tracker.yaml is the project status file. Leadership uses it for visibility.
Update Rules
- Add new features/tasks to the tracker (even at backlog stage)
- Update artifact status when you create or update a spec/plan
- Update phase when work advances
- A change to a feature’s
phasealso changes thePhasecolumn of its row in.forge/features.md, in the same commit. Then runpython3 .claude/lib/check-features-index.py; echo "EXIT=$?"from the worktree root before pushing. This holds for every writer:/forge-deliver’s stages,forge-spec-author,/forge-wave-decompose,/forge-reflect, or a hand edit. Why:Repo hygienefails a PR whosefeatures.mdrow disagrees with the tracker, and F20-l’s spec and plan PRs (#1016, #1025) each failed it at merge time after the phase had moved twice without the row. - Update
blocked_bywhen a blocker is identified or resolved - A started feature has an owner; a feature not yet started has none. Set
ownerin the same edit that setsstartedor movesphaseout ofbacklog, and keep it throughdone. Claiming a feature with/et-claimis that edit: it setsownerandstartedbefore any work, while the feature is still inbacklog. Abacklogfeature withstarted: nullcarriesowner: null. Adroppedfeature carriesowner: "N/A", the same convention as a dropped foundation slice’sassignee: "N/A", and both carrydecided_by: <first name>— who decided to drop it — set in the change that drops it. Unstarted work is not pre-assigned, inowneror innotes: anyone may take it, and whoever starts it setsowner. Why: the dashboard showsowneras who is working on a feature now, so an owner on unstarted work reads as work in progress, and a started feature with no owner hides who to ask./forge-doctorTier 2 checks both directions. ownerandassigneecarry a first name;delivery.teammaps it to a full name. When someone joins the team, add{ name, full_name, github }todelivery.teamin the same change that first sets their name in either field. Why: the dashboard’s Team table showsfull_name, a name missing from the list shows as the bare first name, and/et-claimfinds the claimer’s name by their GitHub login (github), refusing a login not on the list.- When you change a feature’s or a foundation slice’s phase or status, update that entry’s own
last_updated. The tracker has no top-level timestamp; git history records when the file changed. Why: two branches that both bump one top-level line always conflict on it, and the dashboard already takes the newest entrylast_updatedas the tracker’s update time. - Keep
notesbrief — one line, current state only, not a history log - Serialize automated writes under the tracker lock. A skill or command that writes tracker fields (
forge-pr-open,forge-worktree-up,/forge-deliver, possibly in parallel/forge-deliver --wave <N>sessions) brackets its Edit-tool edits withbash .claude/lib/tracker-write.sh begin…finish <n>.begintakes the lock (a.forge/.tracker.lockdirectory — a directory because the edits are separate tool calls and aflocklock lasts only one process, and macOS has noflock) and snapshots the file;finish <n>releases it, and refuses and restores the snapshot if more thannlines changed or the file no longer parses. The script fails open with a warning only when the lock cannot be created at all; a held lock is waited for, then refused. Two writers otherwise clobber each other’s edits. Terminal flips (wave-closed,done) are last-writer-wins-safe. See.claude/commands/forge-deliver.md§ Notes (“Tracker writes must be serialized under a lock”). - Write the tracker with the Edit tool, never
yq -i— by hand and in every skill.yqre-serialises the whole document, so a one-field change lands as a diff of hundreds of lines: trailing-comment columns collapse,notes: >folded blocks flatten into single unreadable lines, and blank-line grouping disappears. The command exits 0, so nothing warns you — which is whyblock-dangerous-bash.shrefusesyq -i/--inplaceontracker.yaml. Useyqto read (yq '.features["F5-i"].phase'— see “Feature lookups inyq” below) and the Edit tool to write — it fails loudly on a non-match and touches only the matched line. Anchor each edit so itsold_stringmatches one place only: a work-item field from the WI’s own- id:line down, a wave’sstatustogether with a line unique to that feature’s wave. If a reflow does land, lettracker-write.sh finishrestore its snapshot; outside abegin/finishbracket, stop and ask the developer to rungit restore .forge/tracker.yaml(it also discards every other uncommitted tracker change), then redo the edit surgically rather than hand-repairing the formatting. See.forge/lessons.mdL-003. - Mark completion in the delivering PR, not a follow-up. The state changes that record a thing finished — a feature’s or bug’s
status/phasereaching a terminal value, a spec’s acceptance criteria ticked[x](.claude/rules/specs.md), a plan’s success criteria ticked (.claude/rules/plans.md), a work-item’simpl_statusreaching its terminal value — are committed in the same PR that delivers the work, so the reviewer sees the intended end state in one diff and the tracker is correct the moment it merges. Do not wait for the work PR to merge and then raise a separate PR just to flip a status or tick boxes: that is a second review cycle that changes nothing but a checkbox. This holds for features, specs, plans, implementations and bugs alike. When the work is app-repo code and the tracker/spec live in the harness, the completion updates ride the accompanying harness branch/PR for that work, committed alongside — still one PR per repo, not a post-merge afterthought. The one field that legitimately waits for merge is a recorded merge-commit SHA; thefix_pr/ PR number is known at open time, and the terminal status becomes true when the PR merges. Why: a completion-only follow-up PR is a second review cycle that changes nothing but a status. One exception — a manual wave: its run sheets’ success criteria and the spec ACs its WIs own are ticked in the plan branch’s/forge-deliverStage 7 M2 commit, after the person’s confirmation, not in the delivering harness wave PR. The reason: no agent may complete the person’s record, and the run sheet and spec are not on the wave branch (which is cut frommainand carries only the record). Once the plan PR has merged there is no plan branch, the wave branch also carries the orchestrator’s writes, and M2’s commit lands there (/forge-deliverStage 0 Step 0a, lessons L-086 and L-215). A status checkpoint is not a follow-up PR:/forge-deliver’s “Status checkpoint at every exit” copies a live harness wave branch tomainwhile the wave waits, so marks already on that branch (a WI’swave-closed, ticked success criteria) can reachmainbefore the wave’s code merges. The wave’s ownstatusstayspr-openonmainuntil its wave PR merges, and the wave PR still delivers the work; read a WI’s terminal value together with its wave’sstatus.
Feature lookups in yq
features: in this project’s tracker.yaml is a map keyed by feature id (features: { F5-i: {...}, F5-k: {...} }), and no feature carries an id field. So:
- Look a feature up with the map form:
yq '.features["F5-k"].phase', and in a scriptyq ".features[\"$TICKET\"].phase". For one of its waves:.features["<id>"].waves[] | select(.wave == <N>). For a work item:… .workitems[] | select(.id == "<wi-id>")— work items are a list withidfields, so that innerselectis correct. - Never use the sequence form
.features[] | select(.id == "<id>"). On a map it matches nothing and exits 0: a read returns empty (a guard reading an override then fails open; a union of repos comes out empty), and ayq -iwrite changes nothing. The upstream template writes the sequence form; this project’s commands and skills use the map form and point here. .delivery.phases[] | select(.id == <n>)is correct as written:phasesis a list whose entries carryid.
Check with git grep -n 'select(.id ==' -- .claude (git’s view skips nested worktrees under .claude/worktrees/) — every hit should be a workitems[] or delivery.phases[] select, never one on features[].
Phase Gates
spec→ spec artifact existsplan→ spec approved (single-plan: the plan is authored inside this phase)workitem-decompose→ spec approved and the feature is being broken into work items (wave mode,/forge-wave-decompose); the Decomposition Plan and the wave plans are authored and reviewed inside this phase. It exits todevwhen Wave 1’s plans are approved (/forge-deliver), or toplanwhen/forge-wave-decomposefinishes on its own or/forge-deliver --no-implementruns — so a decomposed feature can sit atplanwithdecomposed: truedev→ plan approved (decomposed: the Decomposition Plan and Wave 1’s plans approved)review→ dev work completeship→ quality checks passed- Skipping a gate is the developer’s call — but ask and note in tracker
pausedanddroppedare exit states — record reason innotes; adroppedfeature also setsowner: "N/A"anddecided_by(§ Update Rules)
Workitem decomposition (in flight)
/forge-wave-decompose breaks an approved spec into work items shipped in waves (one PR per wave to main). A decomposed feature gains the fields documented in the wave-mode schema block in .forge/tracker.yaml; the load-bearing ones for status tracking are:
-
decomposed: true— the feature has a Decomposition Plan and work items -
spec_branch: "feature/<feature-id>-<description>"— a name recorded at decomposition and shown on the dashboard; no branch of that name is created or committed to, because WI branches come frommainand integrate on the wave branch (worktrees-and-waves.md § Wave Branches);nullwhen the spec has no user-facing ACs -
decomposition_plan: {path, status}— the orchestrator’s plan (wave mode only) -
waves[].workitems[](wave mode) or a flatworkitems[](feature mode), each WI carryingid,title,type(sub | verify | e2e | manual),tier(T1 | T2 | T3 | T-E2E | none),plan_path,plan_status(backlog | draft | in-review | approved), and once implementation startsimpl_status,branch,base_branch,pr_number/pr_urlandpr_role. A harness-onlysubWI (touched_repos: [<harness-repo>], documents only) opens no per-WI PR, so itspr_number,pr_urlandpr_rolestay unset; Stage 11 Pass 1 merges its pushed branch into the harness wave branch (design.forge/design/harness/harness-only-sub-work-items.md). -
pr_rolesays what the WI’s own PR (pr_number) is for:review— a per-WI review PR (type: suborverify). It is closed as superseded when the wave PR opens, or, for averifyWI, merged into the wave branch; either way nothing reachesmainthrough it./forge-pr-openwrites it.integration— thetype: e2eWI’s PR./forge-pr-openwrites it.ship— a per-WI PR that was merged straight tomaininstead of through a wave PR, so it is the PR that shipped the change. Nobody opens a PR asship:/forge-deliverStage 0 records it when it finds a per-WI PRMERGEDwith basemain, or the developer records it by hand.
A
shipPR gets the check a wave PR’s merge would otherwise have had:/forge-deliverreads the last run of every required check on the PR’s merged head, and a red or pending result halts the orchestrator (.claude/commands/forge-deliver.mdStage 7, “Checking a per-WI ship PR”). Why: forge-et-be#86 was merged straight tomainwith its Slow lane red, andmaincarried the change without its fix until #87 (F5-i finding F-003). -
ship_check_resolved_by(only on a WI whose ship PR’s check halted) — the URL of a passing run, on amaincommit that contains the PR’s merge commit, of every required check that was red or pending (a manual dispatch counts for theSlow laneonly when it ran without-f tests=false; a scheduled run counts only for theFast lane, as it runs noSlow lane—.forge/design/harness/test-run-cost.mdN-3, N-5). When the WI’s ship PRs halted in more than one repo, it is a list with one URL per repo. The developer sets it with the Edit tool once the fix is onmain;/forge-deliververifies it and then stops halting on that PR. -
A wave can ship without a wave PR in a repo. When every WI of the wave that touches a repo had its per-WI PR merged straight to
mainthere, Stage 14 counts that repo as merged once those PRs pass the same required-checks check (.claude/commands/forge-deliver.mdStage 14). F5-i Wave 1 shippedforge-et-beand the harness this way. -
waves[]entries carrywave,status(planned | in-progress | pr-open | merged | withdrawn),merged_at,depends_on, and an optionalgate:list — soft dependencies outside the feature that hold one wave’s dispatch or hand-off (never its plan authoring). Each entry is exactly one structured gate kind plus a one-linemeans:; the kinds, their evaluation and their validation are defined once in.claude/commands/forge-deliver.mdStage 7, “Per-wave gates”. A wave with nogatebehaves as before. -
A wave that will not run is withdrawn, never deleted. When a decision moves a wave’s work elsewhere or drops it, the wave keeps its row with
status: withdrawn,merged_at: nulland a one-linewithdrawn_reason:(the date, who decided, and where the work went), and each of its work items takesimpl_status: withdrawn, keeping itsplan_path./forge-delivercounts a withdrawn wave as finished, as it does a merged one: it never selects, dispatches or hands it off, a wave that depends on it may start, and the feature closes with it withdrawn. A wave that has started — any work item pastpending, or a wave PR open — is not withdrawn this way; ask the developer. Work items are withdrawn only with their wave: a single work item dropped from a live wave would hold that wave’s wait for every work item atpr-openopen forever, so its row is never deleted either — ask the developer whether to keep it or re-decompose the wave. Why: a deleted wave leaves a gap in the feature’s wave numbers, which.claude/rules/id-numbering.mdrule 3 forbids, and loses the record that the wave was planned (F38-a wave 2, deleted 2026-10-26 and restored as withdrawn 2026-10-27).
Manual work items (wave mode). type: manual is a WI a person carries out — a live check against a real external system, a physical device, a human judgment — never an agent. Its rules:
- it has
tier: none, a tier value allowed only onmanualWIs; - it lives only in a manual wave — a wave whose WIs are all
type: manual. A manual WI’s owndepends_onis empty; the wave’sdepends_oncarries its order after earlier waves; - its plan is a run sheet (
forge-plan-author’s run-sheet case), and its results go in a record file of its own,.forge/plans/<ticket>/<wi-id>-record.md, on the harness wave branch; impl_status: with-personis used only bymanualWIs;- two fields are set when
/forge-deliverStage 7 M1 hands it off:run_by(the name of the person running the WI) andhandoff_sha(theorigin/maincommit the harness wave branch was cut from). M1 also setstouched_repos: [<harness-repo>].
The manual-wave path (M1 hand-off, M2 close, M3 wave PR) is defined in .claude/commands/forge-deliver.md Stage 7.
Two fields on a sub WI (wave mode; .claude/commands/forge-deliver.md Stage 7, design .forge/design/harness/forge-deliver-f38-follow-ups.md):
run_by: main-session— the WI is run by the orchestrator’s own session, not dispatched to a background agent, because each of its writes needs a person’s approval at the time. The developer sets it by hand at decomposition (no skill writes it). On asubWIrun_bytakes this value only; on amanualWI it names a person.waits_on_pr: "<repo>#<number>"— aforge-et-iaacWI whose branch is stacked on another wave’s unmerged branch, pushed with no PR of its own, names the PR it waits on./forge-deliverStage 0 then waits while that PR is open instead of halting; the field is removed when the WI’s own PR opens.
impl_status lifecycle (wave mode): pending → dispatched → pr-open → wave-closed for sub, verify and e2e WIs; pending → with-person → pr-open → wave-closed for manual WIs; pending → withdrawn for a WI of a withdrawn wave (above). The dispatched → pr-open flip is written by each WI’s own /forge-pr-open run (the actor that opens the per-WI PR; for a harness-only sub WI, the run that pushes its branch and opens none) and is the transition the orchestrator’s “await all WIs at pr-open” integration barrier blocks on; a manual WI’s with-person → pr-open flip is written by /forge-deliver Stage 7 M2 after the person’s confirmation. The terminal value is wave-closed (written by /forge-pr-open --wave when the per-WI PR is superseded by its wave PR, or when a manual wave’s PR opens) — not merged. The Decomposition Plan itself has no impl_status (it ships no code).
Because review and implementation interleave, a decomposed feature can be at phase: dev (≥1 wave dispatched) while later-wave WIs are still at plan_status: backlog — the per-WI plan_status/impl_status pair is the authoritative state; feature-level phase is a coarse indicator only.
See .forge/plans/_TEMPLATE-decomposition-plan.md for the Decomposition Plan shape and .claude/commands/forge-deliver.md / forge-wave-decompose.md for the full wave-mode workflow.
Delivery Phase Rules
delivery.phases groups features into stakeholder-facing milestones. Each feature carries delivery_phase: <int> referencing a phase id. Phases are layered on top of the dependency graph — blocked_by still drives sequencing within a phase; phases drive the stakeholder narrative.
Phase status vocabulary (four values, distinct intents):
planning— being shaped right now. Used during the Gate 3 proposal step while phases are still being defined; rarely seen post-Gate-3 except during an explicit replan.in-progress— currently active. Exactly one phase at a time. This is the phase whose features the team is presently developing and shipping.complete— sealed. Every feature in this phase isdoneordropped, the developer has confirmed the seal, andsealed: <ISO date>is set.locked— defined but not opened yet. The phase has a title and theme and feature assignments, but development on its features has not started. After Gate 3 lands, every phase except the first islocked.
Invariants (enforced by ASK rather than by hook):
- At most one phase has
status: in-progressat any time. delivery.current_phaseequals theidof thein-progressphase, ornullif no phase is active.- A phase with
status: in-progressmust havestarted: <ISO date>set; phases inplanningorlockedkeepstarted: null. - A phase with
status: completemust havesealed: <ISO date>set; phases in any other status must havesealed: null.startedis preserved oncomplete(it records when work began). - A feature’s
delivery_phasemay reference any phase id (includinglockedorcomplete) or benull. Specing and planning a feature ahead of its phase is allowed; advancing it todevwhile its phase islockedis an ASK FIRST action — surface the override and record it innotes. - Renaming a phase title is safe (features reference
id, not title). Reassigning a feature to a different phase is safe but should be noted in the feature’snotes.
Status transitions and what to update:
- Defining phases (Gate 3, full mode):
/forge-decomposepopulatesdelivery.phasesand assigns each feature adelivery_phase. The first phase flips toin-progresswithstarted: <today>; all others staylockedwithstarted: null.current_phaseis set. - Sealing a phase: when every feature in a phase is
done(ordropped) and no open bug targets the phase (see “Bug Tracking” → phase-seal rule) and.forge/engagement-gate-runs.mdrecords the phase-boundary check for it (a headingPhase <N> boundary check — <date>, from.forge/checklists/phase-boundary-checklist.md; if it is missing, say so and offer to run it first), ask the developer to confirm the phase is sealable. On confirmation: flip the phase tocomplete, setsealed: <today>(preservestarted), flip the next phase toin-progressand set itsstarted: <today>, and updatecurrent_phase. Do not auto-seal — the developer’s verdict is required. - Opening a phase ahead of schedule: ASK FIRST — describe what’s still open in the current phase and confirm before flipping statuses. Set
started: <today>on the phase being opened. - Adding a feature post-Gate-3: new feature gets
delivery_phase: <id>(ornull); confirm placement with the developer. - Splitting/dropping a feature: preserve the
delivery_phaseon the split children unless the developer says otherwise; for dropped features, leavedelivery_phasein place for record, and setowner: "N/A"anddecided_by(§ Update Rules). - Moving a feature between phases (a new
delivery_phase, a started-early move, or a move back): in the same change, (1) re-read both phases’title,themeandnotesand update every one the move makes wrong. A theme lists the features with thatdelivery_phase: Phase 1’s first sentence is its own scope and its second names the started-early work, which joins Phase 1 only when done. (2) Updatefeatures.md § Delivery Plan(its rows, counts and paragraph), the dependency graph and the lanes. (3) Update every other statement of the feature’s phase:git grepits id with “Phase” across.forge/and.claude/(.forge/active-context.md,.forge/owed.md, the PRD, the guides, open specs and plans). Leave dated records as written (the engagement log, revision entries, gate runs, audits), and the specs and plans of features already done or dropped. The client pack follows its own rule: a started-early feature stays in Phase 2 there until it is done (PRD Rev 100, Rev 102). When a started-early feature reachesdone,/forge-reflectstep 5e moves it into the phase’s own scope: the theme’s first sentence, the acceptance criteria and the client pack, with a PRD revision. Why: on 2026-11-20 the dashboard still listed four started-early features in Phase 2’s theme, and the PRD, a guide and an open spec still put moved features in their old phase.
After a phase seals — the release lifecycle. Sealing a delivery phase is not the end of its delivery. Once every delivery phase in a release’s scope is complete, that release enters the release lifecycle — pre-UAT regression, handover to UAT, UAT, post-UAT stabilization, sign-off. It is modeled by a release in the top-level releases: list, not by another delivery phase (a delivery phase groups features; a release groups phases). This engagement accepts each phase in its own UAT round, so each phase has its own release, and Phase 1’s round runs while Phase 2’s work begins (Phase 2 stays locked until Phase 1 seals — below). See “Release & UAT Lifecycle” below.
Phase 1 seals at the end of its UAT round, not before it (the lead, 2026-11-19). Phase 1’s round has two drops (dates in .forge/active-context.md, Release plan): drop 1 is what is ready, and drop 2, during Empire’s testing, carries the Phase 1 work still open (at least F20-f, F20-j and F44) and any started-early feature finished by then. So, for Phase 1 only:
- Phase 1 stays
in-progress, andcurrent_phasestays1, until the round ends. It then seals by the rule above, after the phase-boundary check: by then each started-early feature not done has moved to Phase 2 (.forge/checklists/phase-boundary-checklist.md§3), and any other open Phase 1 item is finished or moved by the lead’s decision. - Release
P1opens before the seal, for drop 1, on the entry gate’s ASK-FIRST path, with this reason in itsnotes(§ The three gates). - Phase 2 stays
lockeduntil Phase 1 seals, but its features may advance todevfrom drop 1 on without the per-feature ASK FIRST in the invariants above: the lead approved this once for the whole phase on 2026-11-19 (Phase 2’snotesintracker.yaml). Note the early start in the feature’snotesas usual. - A UAT defect accepted in Phase 1’s round gets
delivery_phase: 1when it is fixed in drop 2, so it blocks Phase 1’s seal, anddelivery_phase: 2when the lead defers it to later work.
Why: the drop-2 features cannot be done before UAT starts, and sealing before them would have meant moving them out of Phase 1. Phase 2 seals before its own round, as the lifecycle below describes.
Optional for small projects. If the engagement has fewer than ~10 features and the team doesn’t want a phased narrative, leave delivery.phases: [] and current_phase: null. Every feature’s delivery_phase stays null. The dashboard hides the delivery view in that case.
Delivery dates (due_date). Each phase entry and each feature carries an optional due_date (ISO date). Dates are never set by /forge-decompose — it writes every delivery.phases[*].due_date and features[*].due_date as null. Set them afterward with the /forge-set-dates command, which prompts for a phase target date per phase and (opt-in only) cascades proportional per-feature dates. Phase-level dates are the primary deadline unit and drive the dashboard delivery view; per-feature dates are off by default. All due_date fields stay null until /forge-set-dates runs — the dashboard renders the null case gracefully (no date shown, feature-date column omitted). A phase may also carry milestone_date, the contractual milestone from the Statement of Work, edited by hand when the Statement of Work changes; when it is set, the dashboard shows the phase’s date and counts its pace against it, and shows due_date (the internal build target) only in the date’s tooltip. Why: the team reads the dashboard against the dates Empire was given, while the earlier build target stays recorded for planning.
Holidays (delivery.holidays). A list of {date: YYYY-MM-DD, name} entries: the team’s non-working weekdays. The dashboard’s pace line counts a working day as a weekday not on the list, so keep it covering every date up to the last phase’s due_date, from the team’s own holiday calendar (weekday holidays only). Edit it like any other tracker field. Why: a pace figure that counts Poya days as working days overstates the time left.
Bug Tracking
Post-ship defects live in the top-level bugs: collection in tracker.yaml (a sibling of features:), not nested under features. Rationale: a bug is genuinely M:N (a shared-primitive defect breaks several features at once), “what open bugs exist?” must be a flat query, and a bug’s lifecycle is independent of any feature’s phase. The structured fields are documented inline in tracker.yaml; the full description (repro / expected / actual / fix) lives in .forge/bugs.md, one section per bug, joined by id.
Id scheme: BUG-NNN — global, zero-padded. Not feature-suffixed (a bug may affect multiple features). The numbering rules for every id — used once, none skipped, never deleted, the younger entry renumbers on a clash — are .claude/rules/id-numbering.md; what is specific to bugs: a new bug takes the lowest number not yet taken, not the highest plus one, so free numbers below the highest id are filled first. Get it from bash <harness>/.claude/lib/next-bug-id.sh at the moment you write the entry: it reads the tracker on origin/main, every open harness PR (a PR holds a number it names in its title or branch, or whose entry it adds) and every pushed branch with no PR, prints the lowest free id, and fails rather than guess when a read fails. Repo hygiene fails a PR that adds a bug above a free number, naming the ids to use (next-id.py --check-pr). Filing several bugs in one change, run it once with --count <k> and use the ids it prints — the free numbers are not consecutive (after BUG-014 comes BUG-132), and it sees an entry only once it is written in this checkout or pushed. After a clash, next-bug-id.sh --ignore-pr <your PR> gives the number to renumber to (merging main in first only when GitHub reports a conflict, never rebasing — .claude/rules/git-conventions.md § Branching). Place the entry by its number, not at the end: tracker.yaml keeps a note at each run of free numbers saying where their entries go, and new bugs.md sections go in id order with the highest on top, so BUG-011 goes below BUG-015. Name a bug in a PR’s title or branch only when the PR files or fixes it; a PR that only discusses free numbers writes them without the BUG- prefix, or it holds them. A report that turns out not to be a bug is closed wontfix, never deleted.
The feature↔bug link is single-sourced from affects. Features do not store a duplicate bugs: list. The per-feature bug list is derived (by the dashboard) by filtering the collection on affects. If a human-readable mirror on the feature is ever wanted, it must be generated — never hand-edited. Every bug names at least one feature or foundation slice in affects, the one whose code or step is broken: a CI, build or harness-tooling defect names the slice that built the step (the Fast lane’s Trivy step is FS-4’s, BUG-343), never an empty list. Repo hygiene’s check-tracker-owners.py fails a bug whose affects is empty or names an id that is neither a key in features nor a slice in setup.foundation.slices. Why: a bug with no affects is listed under no feature or slice on the dashboard (BUG-343 was filed and closed that way).
A bug does not reopen its feature. The feature stays done; the bug carries its own status (open → in-progress → fixed, or → wontfix). The dashboard shows e.g. “feature-a · done · 1 open bug” — the shipped record stays intact while the defect stays visible.
delivery_phase is the scheduled-fix milestone, distinct from the affected feature’s (which is frozen history — where it shipped). It defaults to delivery.current_phase at discovery; bump it forward to defer — a deliberate, tracked action, not silent slippage.
Phase-seal rule (load-bearing, ASK-enforced): a delivery phase N cannot be sealed (complete) while any bug with status ∈ {open, in-progress} and delivery_phase: N exists. Before sealing, query the collection for such bugs; each must be either driven to fixed/wontfix or explicitly reassigned to a later phase (delivery_phase: N → N+1) — a deferral the developer confirms. The last phase has no later one: deferring a bug out of it sets delivery_phase: null, which the lead confirms, and a blocking UAT defect deferred that way still holds its release’s sign-off. This makes “couldn’t make the deadline → move to next phase” an auditable action, mirroring the existing developer-confirms-the-seal gate.
No per-bug due dates. Never record a due date, a fix-by line or a fix schedule on a bug in tracker.yaml or bugs.md: a bug is fixed before its delivery_phase’s UAT and hand-over, and the phase-seal rule enforces it. Record only real decisions on a bug — where it is fixed (a feature’s work item) or an approval it needed. Why: the lead reverted a per-bug fix-by schedule (forge-et-harness#411); the phase deadline already covers it.
Bugs are atomic; a shared fix can span several. Each defect is its own BUG-NNN with independent status / severity / delivery_phase — never collapse multiple defects into one entry (that hides which sub-bug is still open). Several small bugs fixed in one PR simply share the same fix_pr (e.g. BUG-002/003/004 all fix_pr: <repo>#62); each still closes individually.
A flaky test failure is filed per operating system. The team develops on macOS and on Windows (.forge/team-guide.md § The Team), and a test that fails under load on one can pass on the other. The same symptom seen on the other operating system is a new BUG-NNN whose spec_ref names the first, not a note added to it, and whose notes say it waits on the first bug’s cause: the cause is investigated once, and each bug then proves the fix, or the overload outcome of .forge/test-strategy.md § Flaky Tests, on its own operating system. Its Repro: names the operating system, what else was running on the machine, and the run’s recorded load (the browser gate’s result.json load, or the Machine load: line a test record prints). Why: each fix is checked on the kind of machine where the failure was seen, and each bug closes on its own (BUG-077 on Windows, BUG-082 on macOS).
A bug specific to one operating system says so in its title; any other bug does not. A bug is specific to one operating system when it is a flaky test failure (always filed per operating system, above) or a defect seen on one system only, such as a Windows path separator in a test (BUG-038) or a layout offset in Windows Chromium (BUG-246). Its title ends with (Windows) or (macOS) — or (Linux CI) for a failure seen only on GitHub’s Linux runner — in the tracker.yaml title and the bugs.md heading alike, and a flaky failure’s title starts with Flaky test:, Flaky tests: or Flaky <what>: (Flaky gate setup:). A UI, functional or data defect in the product carries no operating system, even when it was first seen under load on one machine (BUG-125) or only one system’s test run happened to show it (BUG-232, a pinned column that covered row controls, which only macOS’s overlay scrollbars let the size matrix catch); it carries one only when the defect itself exists on one system alone, as BUG-246’s layout shift does for Windows Chrome users. An open flaky bug always has one system, because the same symptom on the other system is filed as a new bug (the paragraph above); a closed bug that records failures on two systems, filed before that rule (BUG-084, BUG-110), carries no suffix. When a later run shows that an open bug is specific to one system (a retry on the other system does not reproduce it), the change that records that run adds the suffix to both titles. Repo hygiene runs python3 .claude/lib/check-tracker-owners.py, which fails when an open or in-progress bug’s title starts with Flaky and has no suffix, when any bug’s tracker.yaml title and bugs.md heading end differently, or when a title ends with a misspelt system such as (Mac) or (Linux). Why: the suffix is how the team picks the bugs it can fix and prove on its own machine, and the open flaky bugs that lacked it were taken for Mac work when the record showed they could be proved only on Windows (BUG-219, BUG-224; 2026-10-26).
The bug-fix flow is right-sized — NOT forge-deliver. Bugs do not go through spec authoring, gap-check, or decomposition/waves:
-
The
bugs.mdentry is the spec (repro + fix approach). No spec file. -
Plan is optional and proportionate — the
Fix:line suffices for a small bug; a short plan (approach + files + test) only when the fix is non-trivial (multi-file/repo, a design choice, real risk). The fix approach is always written down before code is touched. -
Claim it first, before any work:
/et-claim BUG-NNN(several bugs at once:/et-claim BUG-NNN BUG-MMM). It checks that nobody owns it, has an open PR for it or has pushed a branch named after it, then sets itsownerto your first name (the form featureowners use) and itsstatustoin-progressonmainthrough a small harness PR, which you merge (.claude/commands/et-claim.md). Why: an owner set only in the fixing PR is invisible until that PR merges, and teammates fixed the same bug twice. Once the claim PR has merged (the fixing PR changes the samestatusline), branchfix/BUG-NNN-<desc>(the existingfix/convention ingit-conventions.md). The claim is strict:- The claim PR merges before any fix work starts — before the fix branch, the first fix commit and any fix PR, draft included. It is its own small PR, never part of the fixing PR or its harness branch. Claude runs
python3 .claude/lib/claim-check.py <every BUG id it will fix>before it creates a fix branch or writes a fix, and goes on only when every id answersMINE; onFREEit runs/et-claimand waits for the merge, onPENDINGit waits for the merge, and onTAKENit stops and names the owner. - Every bug a branch fixes is claimed, not only the one in its name. A
fix/BUG-190-…branch that also fixes BUG-187 claims both first. - Only a bug already on
mainneeds a claim. A bug filed on a branch that has not merged needs none, whether the same PR fixes it or a later one does, because nobody else can see it to take it. A filer who will fix it files it already claimed —owner: <first name>andstatus: in-progresstogether; otherwise it is filedopenwithowner: null, never with the filer’s name as a reminder. Once a bug reachesmainasopen, fixing it takes/et-claimlike any other bug, its filer included.
The field stays once the bug is fixed: it is who fixed it, and the dashboard’s bug lists and Team section count by it. An
openbug has noownerand is not pre-assigned innotes: anyone may take it. The dashboard shows no owner on anopenbug or an unclaimedbacklogfeature (nostarted) whatever the tracker says, and/forge-doctorTier 2 checks both directions.Repo hygienerunspython3 .claude/lib/check-tracker-owners.pyon every harness PR, which fails when anin-progressorfixedbug or a started feature has noownerfromdelivery.team, when awontfixbug ordroppedfeature lacksowner: "N/A"and adecided_by, or when anopenbug or an unstarted feature has an owner — the way to take one is a claim, which sets the owner and the start together. - The claim PR merges before any fix work starts — before the fix branch, the first fix commit and any fix PR, draft included. It is its own small PR, never part of the fixing PR or its harness branch. Claude runs
-
Mandatory regardless of size: a regression test that fails before the fix and passes after, plus a pre-merge diff review —
/forge-review-pr <repo>#<N>once the PR is open, which writes the PR’s review record (.claude/rules/review-record.md). A direct adversarial review of the working diff counts in its place only when it is recorded as a skip record that names it:bash .claude/lib/forge-review-record.sh <owner/repo> <N> <head-sha> --skip "reviewed by /forge-pre-pr-review before push — <where its findings are>".- For a UI bug, also validate the fix in a running browser (the FE) — any team member, every time. Spin up the FE (and the backend, if the affected screen sits behind auth), reach the affected screen, and confirm the fix visually before calling it fixed. A green typecheck + unit suite does not prove a visual / layout / alignment fix; only the browser does. Prefer a live DOM measurement plus a before/after screenshot as the receipt.
-
In the fixing PR itself (its harness branch/PR — not a post-merge follow-up): set
status: fixed+fix_printracker.yamland add theResolved:line tobugs.md, committed alongside the fix’s other harness changes. If the bug still has noowner— a feature PR fixed it as a side effect, or it was filed on the same branch — setownerto the first name of the person whose PR fixed it in the same edit. The status becomes true when the PR merges, which is what unblocks the phase seal. Do not raise a separate PR after merge just to flip the status — see § Update Rules, “Mark completion in the delivering PR”. A bug closed without a fix setsstatus: wontfix(itsfix_prstaysnull),owner: "N/A"anddecided_by: <first name>— who decided not to fix it — in the harness PR that closes it, and itsResolved:line says why it will not be fixed and who decided, as BUG-149’s does. Why: a won’t-fix leaves no fix to read, so that line is the only record of why the defect was accepted; nobody owns a bug that will not be fixed, the same as a dropped feature, anddecided_byis who to ask about it.Repo hygiene’scheck-tracker-owners.pyfails when afixedorwontfixbug’sbugs.mdsection has no**Resolvedline, when anopenorin-progressone has, or when a bug in the tracker has nobugs.mdsection (five fixed bugs once had noResolved:line, found only by hand on 2026-10-26). -
Record whether the cause will recur — the bug’s Reflect step. The same PR adds a
**Lesson:**line to the bug’sbugs.mdsection, afterResolved:, answering one question: is the cause a pattern that will happen again? It takes one of three forms:L-NNN(an existing lesson the bug is another instance of — add the bug to that lesson’s source list), a newL-NNNwritten in the same PR in the § Lessons Entry Format form (with, where a reviewer could catch the next instance, a row inbackend-reviewer,frontend-reviewerortest-strategy.mdthat points at it), ornone — one-off: <why>. A bug closedwontfixgets the line too. Two bugs with the same cause make a pattern, so check the otherLesson:lines for the same cause before writingnone./forge-review-prtreats a missingLesson:line on a bug-fix PR as an Important finding. Why: features close with a mandatory Reflect that promotes findings to lessons, and bugs had no equivalent, so the same defect was fixed in three separate PRs before anyone wrote it down (L-098). Bugs fixed before this rule are mapped inbugs.md § Lesson backfill.
Append-only. fixed/wontfix bugs keep their tracker.yaml entry and bugs.md section as a historical record (the dashboard filters to open by default). A heavy bug may graduate to its own .forge/bugs/BUG-NNN.md via the optional doc: field.
UAT-originated bugs (the parallel-gate case). A defect raised during UAT is routed into this same bugs: collection and linked back from its UAT issue via bug_ref (the issue’s release_id names the release). Its delivery_phase follows the default above — delivery.current_phase when it is found:
- Phase 1’s round, before Phase 1 seals (it seals at the end of its round — § Delivery Phase Rules): a defect fixed in drop 2 gets
delivery_phase: 1and blocks Phase 1’s seal; one the lead defers to later work getsdelivery_phase: 2. - A round run while a later phase is being built gives its bugs that phase:
delivery_phase: 2for a Phase 1 defect raised after Phase 1 has sealed. The phase-seal rule then keeps Phase 2 from sealing until they are fixed, which is the timeline’s “fixes go into the Phase 2 window” (.forge/client/project-timeline.md). - A round run after the last phase has sealed has no active phase, so its bugs carry
delivery_phase: nulland drive no phase seal.
Either way, a blocking defect also blocks its release’s sign-off (see “Release & UAT Lifecycle” → Sign-off gate). The phase-seal rule and the sign-off gate are the same shape at two levels — a defect blocks the phase it is scheduled into and, when blocking, the release that found it. Don’t confuse the two: a delivery_phase: null bug is not “unscheduled and ignorable”, it’s “scheduled against the release that found it, not a phase” (a blocking one also gates that release’s sign-off).
All of the above is enforced by ASK, not by hook — surface the rule and confirm with the developer, consistent with the delivery-phase invariants.
Release & UAT Lifecycle
After a delivery phase seals, it goes through a stabilization-and-acceptance lifecycle the feature/phase model can’t represent. Each run of that lifecycle is a release: one entry in the top-level releases: list. A triaged uat_issues: collection holds what comes back from UAT, each issue naming its release in release_id. A release groups delivery phases the way a delivery phase groups features — it is a distinct top-level concept, not a delivery phase and not a feature phase: testing (per-feature testing already lives in wave verify/e2e WIs; adding a feature-level testing phase would double-count it).
One release per phase’s UAT round. This engagement accepts each phase in its own UAT round (.forge/client/project-timeline.md), so each phase has its own release, named after it: P1 (scope_phases: [1], Phase 1’s round, run while Phase 2’s work begins and opened before Phase 1 seals — § Delivery Phase Rules) and P2 (scope_phases: [2], the final round, whose sign-off is V1 sign-off). More than one release can be open at once — P1 may still be stabilizing when P2 opens — and each runs its own lifecycle and its own gates. A signed-off or live release stays in the list as history, and its evidence stays under .forge/release/<id>/. The end of Phase 1’s round (10 Dec, project-timeline.md) is a planned date: it ends UC-1’s first round and moves P1 to stabilize or sign-off, and it is not by itself P1’s sign-off. A re-test of P1’s fixes is UC-1 round 2, run on the same UAT environment, which is kept, with its data, from Phase 1’s round to the end of Phase 2’s (AD #23, the lead, 2026-11-18), so P1 can stay open while Phase 2 is built and P2 opens (the lead, 2026-11-14). Why: Phase 1’s round runs while Phase 2 is active, which one release object written for the period after the last phase could not model.
A UAT environment is paused, revived and removed by hand, never on a schedule. The round’s end date plans the removal; it does not trigger it. The same holds for pausing it between Phase 1’s and Phase 2’s rounds (AD #23): a person stops it, and later revives it, as Shyamin Ayesh (DevOps) decides; no AWS schedule or rule stops a service, stops the database or destroys anything on a date (the lead, 2026-11-18). A person runs forge-et-iaac’s uat.yaml with destroy (started by hand only; F38-h FR-6) once the lead decides the environment is no longer needed — planned for after Phase 2’s round, since one instance serves both rounds (AD #23) — and records the date in .forge/design/environments-and-identity.md §4. No workflow, scheduler or script removes it on a date. Why: a round can run past its planned end, and the environment Empire is testing must not disappear under them (the lead, 2026-11-14). While it stays up it costs about $9–14 a week (.forge/client/sow-cost-annexe.md §4), so remove it once Phase 2’s round no longer needs it.
The schema for both collections is documented inline in tracker.yaml. These are the rules. The lifecycle is driven interactively by the /forge-release command — a state-aware orchestrator that detects the current stage and proposes the next step — though every transition can also be hand-edited; the command automates the steps below, it does not replace them.
Lifecycle
build-complete → regression → uat → stabilize → signed-off → live
build-complete— every delivery phase inscope_phasesis sealed (complete), or the release was opened early on the entry gate’s ASK-FIRST path (P1on this engagement — § Delivery Phase Rules); the release is open but regression hasn’t started.regression— internal pre-UAT testing/regression cycles (RC-n) are running against the assembled product (cross-feature flows, not per-wave — that already happened during build).uat— the build is handed to the client; a UAT cycle (UC-n) is being executed.stabilize— between/after UAT rounds; accepted defects are being fixed before the next round.uatandstabilizemay alternate across multiple rounds.signed-off— the client has formally accepted the release.live— the signed-off build has been deployed to production. This is a go-live marker (recordslivedate +live_by), not a production-support subsystem: post-go-live defects use the normal bug-fix flow (“Bug Tracking”), not a new collection.
All transitions are ASK-enforced — surface the gate, the developer/lead confirms, never auto-advance (same posture as the phase-seal and bug-fix gates). /forge-release enforces this: it proposes, the human confirms, then it writes.
Cycles
Each release’s cycles[] holds its discrete testing runs. Two types:
regression(idRC-n) — internal, pre-UAT.uat(idUC-n) — client-executed;roundincrements for re-tests (a re-run ofUC-1isUC-1round 2).
RC-n and UC-n are numbered across the engagement, not restarted per release: if P1 ran RC-1 and UC-1, P2’s first cycles are RC-2 and UC-2, so a cycle id names one cycle (.claude/rules/id-numbering.md).
Cycle status: planned → running → passed | passed-with-risks | failed. Each cycle carries a compact summary in the tracker (status, owner, dates, a flows[] critical-flow checklist, blocking_issues[], accepted_risks[]) and points at detailed plan and report evidence files under .forge/release/<id>/. Regression cycles reference per-feature *-test-stats.jsonl numbers — they do not re-run them (avoids double-counting build-time results); they add cross-feature/assembled-product flow coverage only.
Evidence-backed (no self-approved validation). Every cycle marked passed and every manual/exploratory flow marked passed must point at an evidence: file. No “all flows validated” claim without the receipts — same doctrine as the gate-evidence rule.
The three gates (all ASK-enforced)
Each gate applies to one release, and counts only that release’s cycles and UAT issues.
- Entry gate (
build-completeactivation): a release may open only when every delivery phase in itsscope_phasesiscomplete. Opening it earlier is ASK FIRST and recorded in the release’snotes. - Handover gate (
regression → uat): at least one of the release’sregressioncycles must bepassedorpassed-with-risks— the team’s internal certification that the assembled product is ready for UAT. - Sign-off gate (
stabilize → signed-off): the release may not be signed off while any blockinguat_issueofkind: defectwith itsrelease_idis unresolved (status ∈ {triage, accepted, fixed}—fixedstill awaits verification), and its latestuatcycle must bepassed/passed-with-risks. Change-requests do not block sign-off unless explicitly flaggedblocking: true; by default they route to a later phase or release. Sign-off requires a recordedsignoff_by+signed_offdate. The developer/lead confirms; never auto-sign-off.
Go-live (signed-off → live) is a confirmed marker, not a blocking gate: once signed off, record the release’s first production deployment (live date + live_by) on developer confirmation. Each phase’s release has its own marker, so Phase 1 reaching production before P2 is signed off is recorded on P1; a later production deploy of the same release (a hotfix patch) is recorded by its tag and release/vX.Y.Z branch, not by the tracker (.claude/rules/release-and-branch-protection.md § Release Process). It does not gate on anything further — post-go-live defects use the normal bug-fix flow. (Deliberately scoped as a go-live milestone, not a production-support/incident subsystem.)
UAT issue triage + routing
Each uat_issue is triaged by kind, and routing depends on it:
defect→ a genuine bug. On acceptance it routes into the existingbugs:collection + right-sized bug-fix flow (see “Bug Tracking”); the UAT issue keeps abug_ref: BUG-NNNlink and mirrors the bug’s resolution. The routed bug’sdelivery_phaseis the phase being built when it is found, ornullafter the last phase has sealed (the parallel-gate case above); during Phase 1’s round that is1, or2when the lead defers the fix (§ Bug Tracking). Change-requests are deliberately kept out of the bug ledger — forcing them in would corrupt “what open bugs exist?”.change-request→ new/changed behaviour the client wants. On acceptance it becomes a normal backlog feature (added manually via the standard flow //forge-deliver, with adelivery_phaseno earlier than the phase being built, ornullfor a later release when no phase is active) or is deferred to a later release; tracked viaresolution+feature_ref(e.g.backlog F0 (P2)). Never a bug, never auto-creates afeatures:entry — the developer backlogs it manually (manual-first). Whether it is priced under the proposal’s §16 change-request loop or done as ordinary work is the lead’s decision, recorded in itsresolution.query→ a question, not a code change. Answered andclosed.
Planning the fixes. After a UAT release, the lead triages what Empire raised and plans how and when each item is fixed: in the next UAT release, a later one, or later work. Accepted UAT defects usually come before the next phase’s features when they compete for the team’s time (the lead, 2026-11-18); a change request is planned case by case, and one that adds scope goes through change control (.forge/client/project-timeline.md §4).
Issue status: triage → accepted | rejected | deferred, then accepted defects flow → fixed → closed (mirroring bug_ref’s lifecycle). Full prose (repro / steps / client comment / screenshots) lives in .forge/release/<release_id>/uat-issues.md, one section per issue joined by id — the same prose-home pattern as bugs.md.
Driving it — /forge-release (and by hand)
The lifecycle is driven by the /forge-release command (.claude/commands/forge-release.md) — a state-aware orchestrator that reads the tracker, detects the current stage, and interactively proposes the next step (open → regression → uat → triage → sign-off → go-live). It scaffolds cycle plans/reports from the .forge/release/ templates, derives candidate critical flows from feature ACs, and runs each gate check. It is manual-first in posture (framework §5.1): like every Forge gate it proposes and the human confirms — no auto-advance, no self-sign-off, no hook. Every step also remains hand-editable; the command automates the rules above, it does not replace them, and when the two disagree the rules win.
There is no hook for this lifecycle (consistent with the gate-by-ASK posture) and no /forge-validate cycle-runner yet — cycle running is folded into /forge-release; a separate runner is a later extraction only if it grows heavy. Every release stays in releases:; /forge-release works on one release at a time, named by its id or, by default, the newest one that is neither signed-off nor live, and it proposes opening a release for any sealed phase that no release covers yet.
Worked example (round-trips the schema)
A two-phase project accepts each phase in its own UAT round:
- Entry. Phase 1 seals and Phase 2 becomes
in-progress(on this engagement Phase 1 instead seals at the end of its round, andP1opens early for drop 1 — § Delivery Phase Rules). The developer confirms the first release opens: areleases:entry withid: P1,status: build-complete,scope_phases: [1],opened: <today>. - Regression. A regression cycle
RC-1(type: regression,round: 1) runs the critical assembled-product flows. It passes with one accepted risk →status: passed-with-risks, withRC-1-report.mdand per-flow evidence. The release moves toregressionthen — handover gate satisfied (RC-1 passed-with-risks) — the developer confirmsregression → uat. - UAT. The build is handed over:
status: uat,handover_date: <today>, cycleUC-1opens. The client raises two issues, each withrelease_id: P1:UAT-001(kind: defect,blocking: true) → accepted → routed tobugs:asBUG-000withdelivery_phase: 2(Phase 2 is being built; on this engagement a defect fixed in Phase 1’s drop 2 gets1instead, because Phase 1 seals at the end of its round — § Delivery Phase Rules),bug_ref: BUG-000. The defect is fixed via the bug-fix flow (fix/BUG-000-…, regression test, PR review) →BUG-000.status: fixed,UAT-001.status: fixed.UAT-002(kind: change-request) → accepted into Phase 2 → backlog featureF0withdelivery_phase: 2,status: accepted,feature_ref: F0,resolution: "backlog F0 (P2)". It does not enterbugs:and does not blockP1’s sign-off.
- Stabilize → sign-off.
P1moves tostabilizewhileBUG-000is fixed, thenUC-1round 2 re-tests and passes. Sign-off gate: no blockingP1defect unresolved (UAT-001verified →closed),P1’s latest UAT cyclepassed. The lead confirms →status: signed-off,signed_off: <today>,signoff_by: <lead>. - Go-live. If the client takes Phase 1 live, the developer confirms →
status: live,live: <today>,live_by: <name>. TheP1record stays in the list as history. - The final round. A second entry,
id: P2,scope_phases: [2], opens — early, for a regression run before Phase 2 seals, is the entry gate’s ASK-FIRST path, recorded in itsnotes. Its cycles continue the numbering:RC-2, thenUC-2. Phase 2 seals (it could not whileBUG-000was open), so no phase is active by the time Empire tests. A defect raised inUC-2is routed withdelivery_phase: null, gated byP2’s sign-off alone;P2’s sign-off is V1 sign-off.
Every step above is driven by /forge-release (it detects the stage and proposes the next action) or hand-edited — same result either way.
Rework Lineage
A feature gains an optional follow_up_of: [<feature-id>...] naming the feature(s) it reworks/continues — “this feature is a later pass over those.”
follow_up_ofis distinct fromblocked_by:blocked_byis dependency / sequencing (“can’t start until these land”);follow_up_ofis continuation (“this redoes / uplifts those”). A feature can have both.- It is also distinct from a spec/plan Rev: a Rev covers typo fixes and clarifications too, so it is not a rework signal. Rework lineage is recorded only via
follow_up_of. follow_up_ofis authoritative for lineage; the reciprocal “reworked by” marker is derived by the dashboard. Do not hand-maintain a reverse list.- The dashboard’s Rework signal counts features with a non-empty
follow_up_ofand maps each to the features it reworks.
Lessons Entry Format
.forge/lessons.md holds engagement-level lessons learned, queued for upstream sync to forge-harness. The dashboard’s Lessons signal parses the file, so the entry format must match what the file and the dashboard regenerator actually use:
- Each lesson is an
h2heading:## L-NNN — <short title naming the lesson, not the change>. IDs are global, the highest plus one, with no number skipped or reused; take them frompython3 .claude/lib/next-id.py lesson(--count <k>for several) (.claude/rules/id-numbering.md). - The first body lines are a field list, and
- **Date:** YYYY-MM-DDis the line the weekly cadence reads. Also carry- **Source commits in this repo:**,- **Sync target:** upstream | project-only(exactly one of the two, nothing after it: a lesson that is partly general isupstream), and- **Synced:** _pending_ | <forge-harness commit>. A lesson found wrong later is withdrawn, never deleted: its entry stays, a> **Withdrawn YYYY-MM-DD:**note with the reason goes under its heading,Synced:readsnot applicable — withdrawn YYYY-MM-DD, and it is never synced; itsSync target:no longer matters. The Lessons tile counts each lesson under one status — awaiting upstream sync, synced upstream, project-only, withdrawn, or invalid (any other combination, to be fixed) — and shows a status only when a lesson has it. Repo hygiene enforces the same rules:.claude/lib/check-lesson-sync-labels.pyfails the PR on any lesson the tile would count as invalid. - Body sections:
### Problem observed,### Change made,### Lesson, optional### Verification, and an optional### Update — YYYY-MM-DDwhen a later change alters what the lesson says to do (the lesson’s own text stays as written). - Append new entries to the bottom (chronological order, newest last — per the file’s own header).
- Findings promoted from
.forge/specs/<feature>-findings.mdduring Reflect get aPromoted: L-NNNback-reference at the source.
An entry without a parseable **Date:** line is not counted in cadence — that is the correct outcome for malformed entries, so fix the entry rather than the parser.
End-of-Session Check
Wrapping up tracked work and developer hasn’t stated status → ask: “Before we wrap up — should I update the tracker? [Current item] is at [current status].”
Harness Version Sync
tracker.yaml carries harness_version — it pins the last upstream forge-harness version whose template/CHANGELOG content has been synced into this project.
- Whenever upstream changelog entries are ported into this harness, bump
harness_versionto the highest synced version in the same change. - Source of truth for available versions:
forge-harness/CHANGELOG.yaml(top entry = latest). - If a partial sync is intentional, do not bump — record the partial scope in
notesand leave the pin at the last fully-synced version.
Gate Audit Protocol
The pre-implementation gates (/forge-prd-check, /forge-arch-probe, /forge-decompose) need persistent audit because the artifacts they verify (PRD, architecture, backlog) don’t have built-in ## Revisions sections like specs do.
Audit storage matches artifact scope:
- Engagement-level gates → audit file at
.forge/engagement-gate-runs.md. Plus snapshot in.forge/project-prd.md## Gate Statustable and structured state in.forge/tracker.yamlundersetup.*. - Per-feature gates (spec/plan review, adversarial review, security review) → reuse spec body +
## Revisions, plan## Notes+## Progress. No new files. - Tool-call-level gates (hooks, lint, typecheck) → ephemeral. Stderr only. No persistent audit.
When engagement-level commands run in full mode, three writes happen atomically:
- Append
## Gate N Run Mblock to.forge/engagement-gate-runs.md. - Update Gate N row in
.forge/project-prd.md## Gate Statustable. - Update
.forge/tracker.yamlsetup.<gate>(status, last_gate_run, accepted_risks, spikes for Gate 2).
Skip all three writes in dry-run mode — print findings only.
Never assume gate outcome. Ask the developer for the verdict (pass / pass-with-risks / pass-with-spikes / fail) before writing. Ask for id, owner, and reasoning of each accepted risk or scoped spike.