agentleFS
samwelmungasamwelmunga/jenga-npm/.agents/skills/j-reconcile/SKILL.md

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".

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
  1. Very specific:

    Read project/configs/workflow.json for board paths.

    line 62
  2. Distinctive:

    Never type the list of completed statuses by hand.

    line 65
  3. Very specific:

    Before touching anything else, resolve the scope argument (if any — see "Scope argument" above) into a concrete set of epic/story/task ids:

    line 87
  4. Very specific:

    When scoped (scope_type: "epic" or "range"): only scan the board files whose id is in the resolved epic_ids / story_ids / task_ids — …

    line 157
  5. Distinctive:

    If implementation is confirmed — no action needed.

    line 181
  6. Distinctive:

    If implementation cannot be confirmed:

    line 183
  7. Distinctive:

    If a matching worktree or branch exists:

    line 185
  8. Distinctive:

    After a successful merge, the task stays at its completed status.

    line 188
  9. Distinctive:

    If the merge has conflicts, alert the user and do not change the status — leave it for manual resolution.

    line 189
  10. Distinctive:

    If no matching branch or worktree exists:

    line 190
  11. Very specific:

    Before treating a matching commit as grounds to promote, run two more checks.

    line 211
  12. Distinctive:

    If either check 4 or 5 matches, skip promotion for this task:

    line 235
  13. Very specific:

    Leave the task's status exactly as it is now — do not touch date_started, date_completed, or its project/todo.md entry.

    line 236
  14. Distinctive:

    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 …

    line 238
  15. Distinctive:

    If implementation is confirmed and neither check 4 nor 5 matched:

    line 245
  16. Distinctive:

    Update the task's status to Passed in its board file.

    line 246
  17. Very specific:

    If the task is listed in project/todo.md, comment it out by wrapping the line:

    line 248
  18. Distinctive:

    If implementation is not confirmed — no action needed.

    line 254
  19. Distinctive:

    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):

    line 257
  20. Very specific:

    After rolling up statuses, scan every story being rolled up (every completed-or-beyond story on the board when unscoped, or only the …

    line 275
  21. Very specific:

    Read the story file and locate the ## Definition of Done section.

    line 278
  22. Distinctive:

    If unchecked boxes are found: record the story ID, story title, and the full text of each unchecked item.

    line 280
  23. Very specific:

    If all DoD boxes are already ticked (- [x]), or the DoD section is absent, no gap is reported for that story.

    line 281
  24. Distinctive:

    If the script exits non-zero, report the failure in the reconcile report and continue to phase 6.

    line 315
  25. Very specific:

    If summary.uncharted_paths is 0, note "no unlinked code found" in the report and continue to phase 6.

    line 372
  26. Distinctive:

    When unscoped, every entry from phase 1 is eligible, exactly as before.

    line 404
  27. Very specific:

    If project/todo.md is left with only the header, the format comment, and blank lines, delete the file.

    line 408
  28. Very specific:

    If no changes were made, print: Board and todo.md are in sync — nothing to reconcile.

    line 435

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.sh was retired by E50_S14 and no longer exists — there is nothing to run. This file was previously generated from a bare skills/reconcile/SKILL.md source; E50_S15 deleted 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:

ArgumentResolves 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.sh

It 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. completed is the tester/scrum-master-set finished statuses; ladder is every script-set status the schema defines after Passed (e.g. Merged, and any the schema adds later). Ladder statuses are completed-and-beyond: reconcile must never promote one, demote one, or touch its date_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 the reason to 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, and owned_path_hints forward as the resolved scope through every phase below. When scope_type is "full", every phase runs exactly as documented for the unscoped case — nothing below changes behavior or output. When scope_type is "epic" or "range", each phase's "when scoped" instructions apply instead.

    owned_path_hints is 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-commit was passed (this is /commit step 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 a pre-reconcile item would warn on every commit; the commit's own pre-commit gate 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's action. A block failure 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):

  1. Search git history — run git log --all --oneline --grep="<task_id>" (e.g. E01_S01_T01). A matching commit is strong evidence of implementation.
  2. Check documentation artefacts — look for a plan or summary file under project/documentation/plans/ or project/documentation/summaries/ whose name contains the task ID.
  3. 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:

  1. 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>).
  2. 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.
  3. If no matching branch or worktree exists:
    • If the task's status is a completed status (the completed class, not ladder):
      • Change the task's status to Pending in its board file.
      • Clear date_started and date_completed.
      • Report the demotion.
    • If the task's status is a ladder status: change nothing — no status, no date_started, no date_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" (see assets/report_format.md) so a human can look.

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.

  1. Search git history for commits referencing the task ID.
  2. Check documentation artefacts as in phase 2.
  3. 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.

  1. Check for an active concurrency-slot holder — glob project/queue/concurrency-slots-*.json (there can be several; one per orchestrating session, per skills/j-do/SKILL.md's ### 4.4. Developer Concurrency Slot Enforcement). For each file found, check both .developer.holders and .tester.holders for 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.5 step 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.
  2. Check for an unmerged worktree or branch — run git worktree list and git 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 /reconcile run 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 its project/todo.md entry.
  • 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_completed to 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) in epic_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:

  1. Read the story file and locate the ## Definition of Done section. If the section is absent, skip this story gracefully (no error).
  2. Scan the DoD section for any lines matching ^- \[ \] (unchecked checkboxes).
  3. If unchecked boxes are found: record the story ID, story title, and the full text of each unchecked item.
  4. 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.sh

It 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 by unlinked_count descending. Each entry is a directory, not a file, because the useful unit for /uncharted segment is 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: true means every candidate file beneath the directory is unlinked — those are the strongest segment candidates and should be offered first. When false, 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 in directory_linkage.items and the spelling that matched in matched_as). Do not offer /uncharted segment for 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.
  • files is capped by --limit (default 10); files_truncated gives the remainder. The counts are always true totals, so never re-count files to 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 the reason shown, and:

    • never describe them as unlinked or add them to the unlinked totals;
    • never include them in the /uncharted segment offer.

    A group whose directory_linkage.status is not_checked is 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_checked entry 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 completed or ladder status; see Section 0) and whose implementation has been confirmed (phase 2), remove the line entirely from project/todo.md.
  • Newly-reconciled entries — entries that were commented out in phase 3 stay as <!-- RECONCILED: ... -->.
  • If project/todo.md is 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. ✅

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.