j.reconcile
Skill0 starsChanged 23 days agoApache-2.0View on GitHub
Reconcile the scrum board with actual implementation state. Cross-checks every task's board status against git history and worktrees, merges orphaned worktree branches, demotes unimplemented "Done" items, promotes secretly-implemented items, flags code with no board provenance and offers /uncharted segment for it, and cleans stale entries from todo.md. Use when the board feels out of sync, after a big merge session, when tasks were completed outside the normal workflow, or when todo.md has grown stale. Trigger on phrases like "sync the board", "clean up the board", "reconcile", "board is out of date", "todo is stale", or "check what's really done".
In this repository151 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- j.brainstormSkill
- j.breakSkill
- j.btwSkill
- j.check-inSkill
- j.clearifySkill
- j.close-storySkill
- j.cloud-connectSkill
- j.commitSkill
- j.connectSkill
- j.continueSkill
- j.conventionsSkill
- j.dashboard-shareSkill
- j.dashboardSkill
- j.deep-diveSkill
- j.distributeSkill
- j.docSkill
- j.doc-syncSkill
- j.doooSkill
- j.doSkill
- j.jenga-configSkill
- j.jenga-permission-levelSkill
- j.jengaSkill
- j.errorSkill
- j.evaluateSkill
- j.examplifySkill
- j.gitignoreSkill
- j.helpSkill
- j.ideaSkill
- j.improveSkill
- j.initSkill
- j.jbpSkill
- j.lgtmSkill
- j.pi-planSkill
- j.playbook-newSkill
- j.playbookSkill
- j.proceedSkill
- j.publishSkill
- j.reconcile-originSkill
- j.redoSkill
- j.skillifySkill
- j.smoke-testSkill
- j.spinoffSkill
- j.statusSkill
- j.testSkill
- j.todoSkill
- j.toolsSkill
- j.unchartedSkill
- j.wtfSkill
- skill-nameSkill
- j.brainstormSkill
- j.breakSkill
- j.btwSkill
- j.check-inSkill
- j.clearifySkill
- j.close-storySkill
- j.cloud-connectSkill
- j.commitSkill
- j.connectSkill
- The first 60 shown.
The file
Show its rules and text
We split this skill into the rules it gives an agent
28 rules. About 0 are common, 16 are distinctive, and 12 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈16
Distinctive · estimate
This author's own choices. Worth a look.
12
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Very specific: line 62
Read project/configs/workflow.json for board paths.
- Distinctive: line 65
Never type the list of completed statuses by hand.
- Very specific: line 87
Before touching anything else, resolve the scope argument (if any — see "Scope argument" above) into a concrete set of epic/story/task ids:
- Very specific: line 157
When scoped (
scope_type: "epic"or"range"): only scan the board files whose id is in the resolved epic_ids / story_ids / task_ids — … - Distinctive: line 181
If implementation is confirmed — no action needed.
- Distinctive: line 183
If implementation cannot be confirmed:
- Distinctive: line 185
If a matching worktree or branch exists:
- Distinctive: line 188
After a successful merge, the task stays at its completed status.
- Distinctive: line 189
If the merge has conflicts, alert the user and do not change the status — leave it for manual resolution.
- Distinctive: line 190
If no matching branch or worktree exists:
- Very specific: line 211
Before treating a matching commit as grounds to promote, run two more checks.
- Distinctive: line 235
If either check 4 or 5 matches, skip promotion for this task:
- Very specific: line 236
Leave the task's status exactly as it is now — do not touch date_started, date_completed, or its project/todo.md entry.
- Distinctive: line 238
Do not merge the branch/worktree found in check 5 yourself — that is a live pipeline's own work-in-progress, not an orphaned branch like …
- Distinctive: line 245
If implementation is confirmed and neither check 4 nor 5 matched:
- Distinctive: line 246
Update the task's status to Passed in its board file.
- Very specific: line 248
If the task is listed in project/todo.md, comment it out by wrapping the line:
- Distinctive: line 254
If implementation is not confirmed — no action needed.
- Distinctive: line 257
After all tasks recorded in Phase 1 have been reconciled (every task on the board when unscoped, or only the in-scope tasks when scoped):
- Very specific: line 275
After rolling up statuses, scan every story being rolled up (every completed-or-beyond story on the board when unscoped, or only the …
- Very specific: line 278
Read the story file and locate the ## Definition of Done section.
- Distinctive: line 280
If unchecked boxes are found: record the story ID, story title, and the full text of each unchecked item.
- Very specific: line 281
If all DoD boxes are already ticked (- [x]), or the DoD section is absent, no gap is reported for that story.
- Distinctive: line 315
If the script exits non-zero, report the failure in the reconcile report and continue to phase 6.
- Very specific: line 372
If summary.uncharted_paths is 0, note "no unlinked code found" in the report and continue to phase 6.
- Distinctive: line 404
When unscoped, every entry from phase 1 is eligible, exactly as before.
- Very specific: line 408
If project/todo.md is left with only the header, the format comment, and blank lines, delete the file.
- Very specific: line 435
If no changes were made, print: Board and todo.md are in sync — nothing to reconcile.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Reconcile — Board ↔ Code Synchronisation
skills/j-reconcile/ is the canonical, hand-edited directory for this skill, per CLAUDE.md's "The Canonical Naming Contract" (the E50 reopening of 2026-09-09, which promoted skills/j-reconcile/ from generated twin to sole canonical form). The j- prefix is there for collision safety — a real directory under a distinct name, so a host tool shipping its own same-named built-in command cannot shadow it (Claude Code's native skill resolution is a literal-string, directory-name-based match; see project/documentation/skill-authoring.md's "Invocation Convention").
⚠️
scripts/generate-j-alias.shwas retired byE50_S14and no longer exists — there is nothing to run. This file was previously generated from a bareskills/reconcile/SKILL.mdsource;E50_S15deleted that directory. This file is now the sole canonical, hand-edited source for this skill — edit it directly.
Walks the full board (epics → stories → tasks), verifies each item's status against what actually exists in git, and fixes any drift. Also cleans project/todo.md of entries that are already done. Then runs the same check in reverse — code that exists with no board item and no EST-tagged commit behind it — and offers /uncharted segment for what it finds.
Scope argument
/reconcile optionally accepts a single scope argument that bounds every phase below to a subset
of the board instead of always walking the whole thing:
| Argument | Resolves to |
| (none) | Full board — unchanged from today's behavior. |
E12 (bare epic id) | That epic, in full. |
E12_S03 or S03 (bare story id) | The story's containing epic, in full — not just the named story. See "Default-scope-to-epic rule" below. |
E12_S03_T01 (bare task id) | The task's containing epic, in full — same default-scope-to-epic rule. |
S03-05 or E12_S03-05 (a story range) | Exactly the named stories (and their tasks), plus rollup limited to only the epic(s) those stories belong to. Does not expand to unrelated stories in the same epic(s). Only story-level ranges are supported — an epic-level range (E01-03) or a task-level range (T01-03) is rejected with a clear reason. |
| Anything unresolvable (unknown id, malformed range, an ambiguous partial) | A clear error before any board file is touched — no partial result, no silent full-board fallback. |
Default-scope-to-epic rule (settled — do not relitigate): a scope argument naming a story or
task (not an epic) always resolves to that item's containing epic, in full — never just the
named story/task in isolation. Story and epic rollup (Phase 4) cannot be evaluated correctly
without seeing all sibling stories/tasks, so scoping to a lone story or task would risk an
incorrect rollup decision. If you want to reconcile exactly a set of stories without pulling in
the rest of their epic(s), use the range syntax (S03-05) instead — a range does not apply the
default-scope-to-epic expansion.
Omitting the argument entirely keeps today's full-board behavior completely unchanged, in every phase below.
Scope resolution itself is deterministic and handled entirely by
skills/j-reconcile/scripts/resolve-reconcile-scope.sh (see Phase 0 immediately below) — this skill
only interprets that script's output; it does not re-parse scope arguments or re-derive range
expansion.
Commit-flow marker (--from-commit)
/reconcile also accepts the flag --from-commit, alongside (never instead of) the scope argument. It is
not a scope argument and does not change what is reconciled. It means exactly one thing: this call is
/commit's own mandatory reconcile step (/commit step 1), and /reconcile therefore does not fire its
pre-reconcile pre-flight gate (see "Pre-reconcile gate" below). Only /commit step 1 passes it; any call
without the flag, including one a user types, is a direct invocation and fires the gate. Remove the flag from
the argument list before Phase 0: resolve-reconcile-scope.sh accepts at most one argument and must never see
it.
Instructions
0. Read configuration
Read project/configs/workflow.json for board paths. Fall back to project/board/ if missing.
Load the completion vocabulary — before anything else, on every run (this includes --from-commit).
Never type the list of completed statuses by hand; derive it from the schema:
skills/j-reconcile/scripts/completed-statuses.shIt prints one JSON object, {"completed":[...],"ladder":[...],"incomplete":[...]}, built from the ## Status
Values table in templates/SCRUM_BOARD_SCHEMA.md (--classify "<status>" answers for a single status, and
prints unknown for a value the schema does not define; treat unknown as incomplete). Carry it through every
phase below:
- Completed-or-beyond =
completed∪ladder. This is what every "completed status" test below means.completedis the tester/scrum-master-set finished statuses;ladderis every script-set status the schema defines afterPassed(e.g.Merged, and any the schema adds later). Ladder statuses are completed-and-beyond: reconcile must never promote one, demote one, or touch itsdate_completed. They are script-set and never agent-judged (see the schema), so reconcile does not second-guess them. - Incomplete =
incomplete∪unknown(Pending, In Progress, Blocked, ...). - Non-zero exit (the schema is missing, unparseable, or has drifted from the pinned core): stop and report the script's stderr as the reconcile failure. Do not fall back to a hand-typed list and do not touch any board file.
Phase 0 — Resolve scope
Before touching anything else, resolve the scope argument (if any — see "Scope argument" above) into a concrete set of epic/story/task ids:
skills/j-reconcile/scripts/resolve-reconcile-scope.sh <scope-argument>Omit <scope-argument> entirely for an unscoped, full-board run (the script's own no-argument
path, matching today's default).
- On
{"status":"error","reason":"..."}(non-zero exit) — stop immediately. Report thereasonto the user as the reconcile failure. Do not proceed to Phase 1, and do not touch any board file,project/todo.md, or write a reconcile report. This is the enforcement point for the story's AC: an invalid or unresolvable scope argument fails with a clear error before any board file is touched — no partial result and no silent full-board fallback. On success — stdout is a single JSON object:
{ "scope_type": "full" | "epic" | "range", "epic_ids": [...], "story_ids": [...], "task_ids": [...], "owned_path_hints": [...] }Carry
scope_type,epic_ids,story_ids,task_ids, andowned_path_hintsforward as the resolved scope through every phase below. Whenscope_typeis"full", every phase runs exactly as documented for the unscoped case — nothing below changes behavior or output. Whenscope_typeis"epic"or"range", each phase's "when scoped" instructions apply instead.owned_path_hintsis best-effort and non-authoritative (see Phase 5) — treat it only as a positive filter, never as proof that an unlisted path is unrelated to the scope.
Pre-reconcile gate
Fires pre-flight checklist phase pre-reconcile (project/documentation/preflight-checklists.md) at exactly
one point: after Phase 0 has resolved the scope successfully (a read-only step) and before Phase 1 or any
other step touches a board file, project/todo.md, a worktree or a branch.
- If
--from-commitwas passed (this is/commitstep 1's reconcile): do not fire the gate. Skip this section and go straight to Phase 1. A reconcile run inside a commit flow runs while the work being committed is still uncommitted, so apre-reconcileitem would warn on every commit; the commit's ownpre-commitgate covers it. - Otherwise (a direct invocation): follow "Calling the checker from a skill" in the schema document: mint a
run id, call
checklist.sh check pre-reconcile --run <id>, and branch on the exit code and each item'saction. Ablockfailure halts here, before Phase 1: no board file is touched and no reconcile report is written.
Mark the situation. Immediately after minting the run id and before the first check, write
the situation marker, and clear it on every exit path (success, a block halt, a declined
confirm, an error):
MARKER="$([ -f scripts/checklist-marker.sh ] && echo scripts/checklist-marker.sh || echo node_modules/@jenga-ai/agent/scripts/checklist-marker.sh)"
TOKEN="$(bash "$MARKER" write --situation pre-reconcile --run "$RUN_ID" --skill j.reconcile)"
bash "$MARKER" clear --token "$TOKEN"This is what lets the enforcing hook see the phase; the protocol, the stack semantics and the TTL are
in "Situation marker" in that document. A failed write is not a reason to abandon the phase — the
gate above still runs and only the hook-enforced backstop is lost: report its stderr and continue.
The --from-commit skip above skips the marker too: a run
that does not fire the gate has no phase to mark.
With no registry, or an empty one, the gate is silent and /reconcile behaves exactly as before.
1. Snapshot the board
When unscoped (scope_type: "full"): scan every file in epics/, stories/, and tasks/,
exactly as before.
When scoped (scope_type: "epic" or "range"): only scan the board files whose id is in the
resolved epic_ids / story_ids / task_ids — for "epic" scope this is the epic file itself
plus every story/task file under it; for "range" scope this is exactly the named story/task
files plus the epic file(s) in epic_ids (the epic(s) those stories belong to). Files for
out-of-scope items are not scanned and play no further part in this run.
For each scanned item, record:
id,title,status(the pre-reconcile status — needed in phase 4)date_completed(if set)
Also read project/todo.md. When unscoped, parse every non-comment, non-blank line into the list
of todo entries, as before. When scoped, only parse lines that reference an id in the resolved
scope (epic_ids / story_ids / task_ids) — out-of-scope lines are left out of the list
entirely, which is what keeps Phase 6 from touching them later.
2. Verify "completed" tasks — are they really implemented?
For every task recorded in Phase 1 (i.e. every task on the board when unscoped, or only the
in-scope tasks when scoped) whose status is completed-or-beyond (a completed or ladder status; see
Section 0):
- Search git history — run
git log --all --oneline --grep="<task_id>"(e.g.E01_S01_T01). A matching commit is strong evidence of implementation. - Check documentation artefacts — look for a plan or summary file under
project/documentation/plans/orproject/documentation/summaries/whose name contains the task ID. - Read the task's acceptance criteria and spot-check the codebase for the key deliverables described (e.g. if the task says "create
scripts/foo.sh", verify the file exists).
If implementation is confirmed — no action needed; the status is correct.
If implementation cannot be confirmed:
- List git worktrees (
git worktree list) and branches (git branch --all) that appear to match the task ID or its slug (the branch naming convention is<E##_S##_T##-short-slug>). - If a matching worktree or branch exists:
- Inform the user and ask for confirmation before merging.
- On confirmation, merge the branch into the current branch (
git merge <branch>). - After a successful merge, the task stays at its completed status.
- If the merge has conflicts, alert the user and do not change the status — leave it for manual resolution.
- If no matching branch or worktree exists:
- If the task's status is a
completedstatus (thecompletedclass, notladder):- Change the task's status to Pending in its board file.
- Clear
date_startedanddate_completed. - Report the demotion.
- If the task's status is a
ladderstatus: change nothing — no status, nodate_started, nodate_completed. A ladder status is set by a script from observed evidence, not by an agent's judgment, so reconcile does not overturn it. Report it under "LADDER STATUS — UNVERIFIED, LEFT UNCHANGED" (seeassets/report_format.md) so a human can look.
- If the task's status is a
3. Verify "incomplete" tasks — are they secretly implemented?
For every task recorded in Phase 1 (i.e. every task on the board when unscoped, or only the
in-scope tasks when scoped) whose status is not completed-or-beyond — i.e. an incomplete or unknown
status (Pending, In Progress, Running, Blocked, etc.; see Section 0). A task in a ladder status is never a
candidate here: it is not promoted to Passed, its status is not rewritten, and its date_completed is not
stamped or changed.
- Search git history for commits referencing the task ID.
- Check documentation artefacts as in phase 2.
- Spot-check acceptance criteria against the codebase.
Before treating a matching commit as grounds to promote, run two more checks. These exist because
a commit referencing a task ID is evidence the code was touched, not evidence it is finished —
a separate, still-running /do pipeline for this exact task may have a real fix sitting unmerged
in a worktree while an earlier, incomplete commit already landed on the branch this /reconcile
pass is reading. This is the exact race documented in
project/rapports/problems/E40_S01_T05-premature-main-reconcile-vs-worktree-fix.md — a /reconcile
pass promoted a task to Passed/Done from a matching commit alone while a fallback developer/tester
pipeline for that same task still had its bugfix unmerged on a worktree branch.
- Check for an active concurrency-slot holder — glob
project/queue/concurrency-slots-*.json(there can be several; one per orchestrating session, perskills/j-do/SKILL.md's### 4.4. Developer Concurrency Slot Enforcement). For each file found, check both.developer.holdersand.tester.holdersfor a key matching this task's id (E##_S##_T##) — or, if this task belongs to a story-bundle dispatch, the containing story's id (E##_S##), since a bundle acquires one shared slot keyed to the story id rather than one per task (### 1.5step 3 of that skill). A matching key means a developer or tester subagent for this exact item is (or very recently was) live in another session. - Check for an unmerged worktree or branch — run
git worktree listandgit branch --all, and look for an entry matching this task's<E##_S##_T##-short-slug>naming convention (skills/j-do/SKILL.md's worktree-naming convention, e.g. its Light Execution Path and Fallback to Full Task-Scope Pipeline sections) that has not yet been merged into the branch this/reconcilerun is executing against. A match means real work for this task exists on a branch this reconcile pass hasn't accounted for yet.
If either check 4 or 5 matches, skip promotion for this task:
- Leave the task's status exactly as it is now — do not touch
date_started,date_completed, or itsproject/todo.mdentry. - Do not merge the branch/worktree found in check 5 yourself — that is a live pipeline's own work-in-progress, not an orphaned branch like phase 2's merge case.
- Report it in the reconcile report as "likely still in-flight — skipped" (see
assets/report_format.md's "⏳ IN-FLIGHT — SKIPPED" section) — not silently promoted, and not silently left unmentioned. - Continue to the next task in Phase 3 — this is a per-task skip, not a phase abort.
If implementation is confirmed and neither check 4 nor 5 matched:
- Update the task's status to Passed in its board file.
- Set
date_completedto today (ISO 8601). - If the task is listed in
project/todo.md, comment it out by wrapping the line:<!-- RECONCILED: <original line> --> - Report the promotion.
If implementation is not confirmed — no action needed; the status is already correct.
4. Roll up story and epic statuses
After all tasks recorded in Phase 1 have been reconciled (every task on the board when unscoped, or only the in-scope tasks when scoped):
- When unscoped: roll up every story and every epic on the board, exactly as before.
- When scoped (
scope_type: "epic"): roll up only the in-scope stories and the one in-scope epic. - When scoped (
scope_type: "range"): roll up only the in-scope stories, and only the epic(s) inepic_ids(the epic(s) those named stories belong to) — never an unrelated story in the same epic(s) that wasn't itself named in the range, per the story's AC.
For each story being rolled up: if all of its tasks are now completed-or-beyond (a ladder task counts as
completed), set the story to Done (if not already) — unless the story's own status is a ladder
status, in which case leave it exactly as it is (rewriting it to Done would be a demotion). If any task was
demoted, and the story was previously completed-or-beyond, set the story back to In Progress. For each
epic being rolled up: apply the same roll-up logic over its stories, including the same ladder exemption.
DoD Gap Detection
After rolling up statuses, scan every story being rolled up (every completed-or-beyond story on the
board when unscoped, or only the in-scope stories when scoped) whose status is completed-or-beyond (a completed or ladder status; see Section 0) for unchecked Definition of Done items:
- Read the story file and locate the
## Definition of Donesection. If the section is absent, skip this story gracefully (no error). - Scan the DoD section for any lines matching
^- \[ \](unchecked checkboxes). - If unchecked boxes are found: record the story ID, story title, and the full text of each unchecked item.
- If all DoD boxes are already ticked (
- [x]), or the DoD section is absent, no gap is reported for that story.
At the end of Phase 4, if any DoD gaps were found across any stories, include a "DoD Gaps" section in the reconcile report (see assets/report_format.md) listing each affected story and its unchecked items.
Unaffected by the mid-story verification rule (E17_S08): the tester's mid-story pass leaves not-yet-reachable DoD boxes unticked but writes story status In Progress, never a completed status, so a story with legitimately-unchecked mid-story boxes is never in this scan's completed-or-beyond scope. An unchecked box on a Passed/Done story therefore remains a genuine gap and is reported as before.
Important: Gap detection is report-only. Do not automatically change the status of any story or epic based on unchecked DoD boxes — surface the gaps so a human can review and decide.
5. Detect unlinked code (no board provenance)
Phases 2 and 3 ask "does this board item exist in the code?". This phase asks the inverse — "does this code exist on the board?" — and finds paths with no Jenga provenance at all.
Run:
skills/j-reconcile/scripts/detect-unlinked-code.shIt emits a single JSON object and exits 0 whether or not it finds anything; read
summary.uncharted_paths rather than branching on the exit status. All the deterministic work —
exclusions, the board check, the commit check, grouping — is in the script. Everything below is
judgement and presentation.
A path is reported as unlinked only when both provenance signals are absent: no board file
references it, and no commit naming a board item added it. Either signal alone is provenance,
so a file created by a task(...) commit is not reported even if no board file names it by path.
Signal B accepts the current EST tags (epic(...), story(...), task(E##_S##_T##)) and the two
older conventions still present in this repo's history (E04_S01: ... and
feat(train): implement E01_S05 - ...).
The script reuses the board-linkage check from
skills/j-uncharted/scripts/resolve-segment-target.sh through its batch interface. Do not
re-derive linkage yourself, and do not substitute a grep over project/board/ if the script
fails — a second answer to "is this path on the board" is what that reuse exists to prevent.
If the script exits non-zero, report the failure in the reconcile report and continue to phase 6.
Scoping (best-effort, not authoritative)
detect-unlinked-code.sh itself takes no scope argument and is never modified by this phase — it
always scans the whole repository, exactly as it does today. When a scope was resolved in Phase 0
and scope_type is not "full", filter the report (not the script's own output) down to
paths that fall under one of the resolved scope's owned_path_hints prefixes before presenting
groups[] / covered_groups[] / not_checked[] to the user; a path outside every
owned_path_hints prefix is left out of the scoped report entirely.
This filtering happens only in this judgement/presentation layer, and it is explicitly
best-effort, not authoritative: owned_path_hints is derived only from each in-scope item's
own docs: frontmatter list (see resolve-reconcile-scope.sh's own contract), so it can be empty
or simply not mention every path the scope actually owns. State this caveat directly in the report
(see assets/report_format.md) — never claim a path is "outside the epic" solely because it
didn't happen to appear in owned_path_hints; say the filtering is best-effort instead. When
scope_type: "full", this phase is completely unchanged — report every finding, unfiltered.
Reading the result
groups[]— the actionable findings, sorted byunlinked_countdescending. Each entry is a directory, not a file, because the useful unit for/uncharted segmentis a directory or feature. Every group directory has itself been checked against the board, so these are directories with no provenance of their own either.fully_unlinked: truemeans every candidate file beneath the directory is unlinked — those are the strongest segment candidates and should be offered first. Whenfalse, the directory holds a mix and only the listed files are unlinked.covered_groups[]— files with no provenance of their own that nonetheless sit under a directory the board does reference (directory_linkage.status: "linked", with the owning board items indirectory_linkage.itemsand the spelling that matched inmatched_as). Do not offer/uncharted segmentfor these — the board already owns that directory and a segment run would duplicate existing items. Mention them in the report as a one-line count so the information is not lost, and move on.filesis capped by--limit(default 10);files_truncatedgives the remainder. The counts are always true totals, so never re-countfilesto report a number.not_checked[]— this is a third state, not a quiet synonym for unlinked. It means the linkage question could not be answered for that path (it is outside the repository, it is the repo root, there is no board directory, or it is a stale index entry that no longer exists on disk). Report these under their own heading with thereasonshown, and:- never describe them as unlinked or add them to the unlinked totals;
- never include them in the
/uncharted segmentoffer.
A group whose
directory_linkage.statusisnot_checkedis a different case: its files were checked and are genuinely unlinked, only the directory verdict is missing. Keep offering it, but say the directory itself could not be verified.Saying "no board item references this" about a path we never managed to check is a false claim of a verified absence. If a
not_checkedentry looks like it matters, the follow-up is to investigate that path directly, not to assume the worst about it.notices[]— surface verbatim in the report if non-empty.
The /uncharted segment offer
Drive this off summary.uncharted_paths and groups[], not unlinked_paths —
unlinked_paths includes the covered files, which must never be offered.
(unlinked_paths == uncharted_paths + covered_paths.)
If summary.uncharted_paths is 0, note "no unlinked code found" in the report and continue to
phase 6. Otherwise present the top groups and offer /uncharted segment, using the numbered
form from CLAUDE.md's Interaction Pattern with the free-text option last:
Found <N> path(s) with no board provenance, in <M> director(y|ies):
1. <directory> — <unlinked_count> file(s)<, entire directory if fully_unlinked>
2. <directory> — <unlinked_count> file(s)
...
Neither these files nor their directories are referenced by any board item, and no commit
naming a board item introduced them. How would you like to handle it?
1. Run `/uncharted segment <directory>` on <top group> now
2. Choose a different group to run `/uncharted segment` on
3. Skip for now — carry on with the rest of the reconcile pass
4. Other (describe below)List at most the top 10 groups; if there are more, say how many were not shown.
This offer is non-blocking. Declining it — option 3, an unrecognised answer, or no answer at
all — changes nothing about the rest of the reconcile run. Record the finding in the report and
continue to phase 6 regardless. Detection is report-only in the same way DoD gap detection
is: never change a board status, create a board item, or modify any file on the strength of this
phase. If the user picks option 1 or 2, finish the reconcile pass first, then hand off to
/uncharted segment at the end so the board is consistent before new items are written.
6. Clean project/todo.md
Walk the todo entries parsed in phase 1 — when scoped, that list already excludes any entry that doesn't reference an in-scope id (Phase 1 only parsed in-scope lines), so this phase never removes or comments out an out-of-scope entry even if it would otherwise qualify under the rules below. When unscoped, every entry from phase 1 is eligible, exactly as before.
- Already-done entries — if an entry references a task/story/epic whose pre-reconcile status (from the snapshot in phase 1) was already completed-or-beyond (a
completedorladderstatus; see Section 0) and whose implementation has been confirmed (phase 2), remove the line entirely fromproject/todo.md. - Newly-reconciled entries — entries that were commented out in phase 3 stay as
<!-- RECONCILED: ... -->. - If
project/todo.mdis left with only the header, the format comment, and blank lines, delete the file.
6.5. Check project/todo.md formatting
Run bash "$([ -f scripts/check-todo-format.sh ] && echo scripts/check-todo-format.sh || echo node_modules/@jenga-ai/agent/scripts/check-todo-format.sh)". This runs unconditionally and is never scope-filtered — a malformed line has no resolvable ref, so it cannot be attributed to any particular epic/story/task scope the way phase 6's cleanup rules can. Exit 0 with no output means nothing to report; skip the MALFORMED TODO ENTRIES section entirely. A non-zero exit prints one line <N>: <text> per malformed entry — carry these verbatim into the report's MALFORMED TODO ENTRIES section (see assets/report_format.md). Report only: never edit project/todo.md on the strength of this check, since fixing a line correctly requires knowing the author's actual intent (which ref, and whether the trailing "(infra)"-style suffix in a misordered line was meant to stay in the title).
7. Print a summary
Output a reconciliation report using the format in assets/report_format.md — the report's very
first substantive line is always Scope: ..., reflecting the scope resolved in Phase 0 (see that
file's Section rules for the exact forms), so a scoped run is never mistaken for a full pass —
with one additional section from phase 5 placed just before TODO CLEANUP:
🗺️ UNLINKED CODE (no board item for the files or their directory)
📁 <directory> — <N> file(s) [entire directory]
📁 <directory> — <N> file(s)
Offered `/uncharted segment`: <accepted for <directory> | declined>
Covered: <N> file(s) in <M> director(y|ies) already owned by a board item — not offered
❓ NOT CHECKED (board linkage could not be determined — not a finding of unlinked)
<path> — <reason>Omit UNLINKED CODE when summary.uncharted_paths is 0, omit its Covered: line when
summary.covered_paths is 0, and omit NOT CHECKED when
not_checked[] is empty. Keep the two separate: merging them would report paths as unlinked
that were never actually checked.
If no changes were made, print: Board and todo.md are in sync — nothing to reconcile. ✅
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

