`forge map` prints the plan of the folder's repository: ready now, being built, and what waits on what #7608

forge map prints the plan of the repository you're in. It takes the repository from --repo owner/name, or from the folder's origin remote when that remote is on the configured workbench, and reuses the folderRepo helper forge pulls already uses.

• src/cli/api.ts: a new ForgeApi.map(owner, name) reads GET /api/v1/repos/:owner/:name/map. toPlan turns the answer into three groups that don't overlap:

- Working is the map's working list. - Ready is the ready issues that are also startable (unassigned and not held), so its count matches the map page's ready count. A map with no startable list falls back to the unassigned ready ones. - Waiting is every open issue with an open blocker in edges, leaving out the ones in Working. Edges to closed issues don't count.

• src/cli/main.ts: mapLines prints each group headed with its count: #N title — assignee, #N title — pillar (or no pillar), and #N title — waits on #A, #B. Titles are cut so no line is wider than width - 1, and a group stops at 15 lines with … N more after it. --json prints the API's answer unchanged. On an error it prints the API's message and exits 1, or 3 for a 401 and 5 for a 403. A bad --repo, or a folder that isn't a clone, exits 2 before any request is made. forge help, the file header and the README list the command.
• test/cli-map.test.ts: runs against a fake map server and checks the three groups and their counts, the cut at exactly 15 with … 5 more, cutting titles to the terminal width, that --json round-trips unchanged, the 404 and 403 messages and exit codes, the exit-2 cases with no request made, the fallback when startable is missing, and that help lists the command.

The new test and the files named by scripts/fast.ts (26 files, 269 tests) pass, and bun x tsc --noEmit is clean.

I didn't add an MCP tool or a terminal UI screen for this: the map API is already the agent's way in, and the issue scopes this to the CLI.

Try it: forge map in a clone of a workbench repository, forge map --repo trevato/forge, or forge map --json | jq .startable.

🤖 Generated with Claude Code

Closes #7379

forge map prints the plan of the repository you're in. It takes the repository from --repo owner/name, or from the folder's origin remote when that remote is on the configured workbench, and reuses the folderRepo helper forge pulls already uses.

• src/cli/api.ts: a new ForgeApi.map(owner, name) reads GET /api/v1/repos/:owner/:name/map. toPlan turns the answer into three groups that don't overlap:

- Working is the map's working list. - Ready is the ready issues that are also startable (unassigned and not held), so its count matches the map page's ready count. A map with no startable list falls back to the unassigned ready ones. - Waiting is every open issue with an open blocker in edges, leaving out the ones in Working. Edges to closed issues don't count.

• src/cli/main.ts: mapLines prints each group headed with its count: #N title — assignee, #N title — pillar (or no pillar), and #N title — waits on #A, #B. Titles are cut so no line is wider than width - 1, and a group stops at 15 lines with … N more after it. --json prints the API's answer unchanged. On an error it prints the API's message and exits 1, or 3 for a 401 and 5 for a 403. A bad --repo, or a folder that isn't a clone, exits 2 before any request is made. forge help, the file header and the README list the command.
• test/cli-map.test.ts: runs against a fake map server and checks the three groups and their counts, the cut at exactly 15 with … 5 more, cutting titles to the terminal width, that --json round-trips unchanged, the 404 and 403 messages and exit codes, the exit-2 cases with no request made, the fallback when startable is missing, and that help lists the command.

The new test and the files named by scripts/fast.ts (26 files, 269 tests) pass, and bun x tsc --noEmit is clean.

I didn't add an MCP tool or a terminal UI screen for this: the map API is already the agent's way in, and the issue scopes this to the CLI.

Try it: forge map in a clone of a workbench repository, forge map --repo trevato/forge, or forge map --json | jq .startable.

🤖 Generated with Claude Code

forge map prints the plan of the repository you're in. It takes the repository from --repo owner/name, or from the folder's origin remote when that remote is on the configured workbench. It reuses the folderRepo helper that forge pulls already uses.

• src/cli/api.ts: a new ForgeApi.map(owner, name) reads GET /api/v1/repos/:owner/:name/map. toPlan turns the answer into three groups that don't overlap:

- Working is the map's working list. - Ready is the ready issues that are also startable (unassigned and not held), so its count matches the map page's ready count. If the map has no startable list, it uses the unassigned ready issues instead. - Waiting is every open issue with an open blocker in edges, leaving out the ones in Working. Edges to closed issues don't count.

• src/cli/main.ts: mapLines prints each group under a heading with its count, with a blank line between groups:

- #N title — assignee - #N title — pillar (or no pillar) - #N title — waits on #A, #B

Titles are cut so no line is wider than width - 1. A group stops at 15 lines, followed by … N more. --json prints the API's answer unchanged. On an error it prints the API's message and exits 1, or 3 for a 401 and 5 for a 403. A bad --repo, or a folder that isn't a clone, exits 2 before any request is made. forge help, the file header, the README and docs/CLI.md all list the command. test/cli-docs.test.ts came in from main and requires the docs/CLI.md section.

• test/cli-map.test.ts: runs against a fake map server. It checks:

- the three groups and their counts - the cut at exactly 15 lines with … 5 more - cutting titles to the terminal width - that --json returns the answer unchanged - the 404 and 403 messages and exit codes - the exit-2 cases, with no request made - the fallback when startable is missing - that help lists the command

The branch has main merged in. The conflicts in README.md, src/cli/api.ts and src/cli/main.ts came from the new forge asks --ship/--close/--undo work. Both sides are kept, and the imports and the switch are joined by hand. bun x tsc --noEmit is clean. The 27 test files that scripts/fast.ts names (281 tests, cli-map and cli-docs among them) pass.

I didn't add an MCP tool or a terminal UI screen: agents already read the map through the API, and the issue asks only for the CLI.

Try it: forge map in a clone of a workbench repository, forge map --repo trevato/forge, or forge map --json | jq .startable.

🤖 Generated with Claude Code

Closes #7379

The full suite on this head squashed onto main (accaa65) was red, so the pull has not joined the merge queue.

Red tests:

• a real roll of two forge processes on one data directory > an old forge that exits on SIGTERM refuses what routers still send it

The gate's log: /api/v1/repos/trevato/forge/gates/1793498673681-628892395cba/log

It is proved again on a push.

forge map prints the plan of the repository you're in. It takes the repository from --repo owner/name, or from the folder's origin remote when that remote is on the configured workbench. It reuses the folderRepo helper that forge pulls already uses.

• src/cli/api.ts: a new ForgeApi.map(owner, name) reads GET /api/v1/repos/:owner/:name/map. toPlan turns the answer into three groups that don't overlap. Every row takes its title, assignee and pillar from the map's issues list.

- Working is the map's working list. - Ready is the ready issues that are also startable (unassigned and not held), so its count matches the map page's ready count. If the map has no startable list, it uses the unassigned ready issues instead. - Waiting is every open issue with an open blocker in edges, leaving out the ones in Working. Edges to closed issues don't count.

• src/cli/main.ts: mapLines prints each group under a heading with its count, with a blank line between groups:

- #N title — assignee - #N title — pillar (or no pillar) - #N title — waits on #A, #B

Titles go through inert() and are cut so no line is wider than width - 1. A group stops at 15 lines, followed by … N more. --json prints the API's answer unchanged. On an error it prints the API's message and exits 1, or 3 for a 401 and 5 for a 403. A bad --repo, or a folder that isn't a clone, exits 2 before any request is made. forge help, the file header, the README and docs/CLI.md all list the command.

• test/cli-map.test.ts: runs against a fake map server. It checks:

- the three groups and their counts - the cut at exactly 15 lines with … 5 more - cutting titles to the terminal width - that --json returns the answer unchanged - the 404 and 403 messages and exit codes - the exit-2 cases, with no request made - the fallback when startable is missing - that help lists the command

Since the last review:

• The red gate: it stopped about a second in. The rehearsal test failed because the old forge did not come up. test/crew-early.test.ts failed with ENOENT reading src/core/migrations/20261027090000-home-visit.ts, a file that is on both main and this branch. Both files pass here on the same head (21 tests, 0 fail), and neither reaches the CLI code, so I think the gate's checkout was faulty. I changed no test, and this push lets the gate run again.
• juniper's second point: done. toPlan's issue() no longer takes a row. Every group reads from the map's issues list.
• juniper's first point: I opened no follow-up issue, because the terminal app already shows this plan. src/tui/screens/plan.ts lists working, ready now and waiting, from the same reads as MCP map.

The 27 test files that scripts/fast.ts names (281 tests) pass, and bun x tsc --noEmit is clean.

Try it: forge map in a clone of a workbench repository, forge map --repo trevato/forge, or forge map --json | jq .startable.

🤖 Generated with Claude Code

Closes #7379

The full suite on this head squashed onto main (accaa65) was red, so the pull has not joined the merge queue.

Red tests:

• a real roll of two forge processes on one data directory > an old forge that lingers past a probe period refuses nobody
• model budget: zero, an own subscription, a capped grant > an own subscription runs, for its own repositories only
• model budget: zero, an own subscription, a capped grant > a capped grant runs, and stops being offered at the cap
• a push in flight on the old forge completes across the roll, and no connection is refused

The gate's log: /api/v1/repos/trevato/forge/gates/1793498933815-7b693187e59c/log

It is proved again on a push.

forge map prints the plan of the repository you're in. It takes the repository from --repo owner/name, or from the folder's origin remote when that remote is on the configured workbench. It reuses the folderRepo helper that forge pulls already uses.

• src/cli/api.ts: a new ForgeApi.map(owner, name) reads GET /api/v1/repos/:owner/:name/map. toPlan turns the answer into three groups that don't overlap. Every row takes its title, assignee and pillar from the map's issues list.

- Working is the map's working list. - Ready is the ready issues that are also startable (unassigned and not held), so its count matches the map page's ready count. If the map has no startable list, it uses the unassigned ready issues instead. - Waiting is every open issue with an open blocker in edges, leaving out the ones in Working. Edges to closed issues don't count.

• src/cli/plan.ts: mapLines lays out the plan with no I/O. Each group gets a heading with its count, with a blank line between groups:

- #N title — assignee - #N title — pillar (or no pillar) - #N title — waits on #A, #B

Titles go through inert() and are cut so no line is wider than width - 1. A group stops at 15 lines, followed by … N more.

• src/cli/main.ts: the map command reads the plan and prints it. --json prints the API's answer unchanged. On an error it prints the API's message and exits 1, or 3 for a 401 and 5 for a 403. A bad --repo, or a folder that isn't a clone, exits 2 before any request is made. forge help, the file header, the README and docs/CLI.md all list the command. The README and docs/CLI.md say that Ready is the startable subset, so its count matches the map page.
• test/cli-map.test.ts: runs against a fake map server. It checks:

- the three groups and their counts - the cut at exactly 15 lines with … 5 more - cutting titles to the terminal width - that --json returns the answer unchanged - the 404 and 403 messages and exit codes - the exit-2 cases, with no request made - the fallback when startable is missing - that help lists the command

The red gate: I think the gate machine caused it, not this change. Its four red tests are in test/rehearsal.test.ts, test/model-grant.test.ts and test/release-handover.test.ts. They roll two forge processes, or wait on model grants, and none of them reach src/cli. On this head they pass here: 20 tests, 0 fail. The rehearsal failure was "the old forge did not come up", the same as on the gate before. That earlier gate also hit an ENOENT on a migration file that is in the tree. I couldn't read the newer gate's details, because its log URL now answers 404. I changed no test.

The terminal app already shows this plan in src/tui/screens/plan.ts, so I opened no follow-up issue for it.

The 27 test files that scripts/fast.ts names (281 tests) pass, and bun x tsc --noEmit is clean.

Try it: forge map in a clone of a workbench repository, forge map --repo trevato/forge, or forge map --json | jq .startable.

🤖 Generated with Claude Code

Closes #7379

The full suite on this head squashed onto main (accaa65) was red, so the pull has not joined the merge queue.

It named no test (a type error, a timeout, a setup step).

The gate's log: /api/v1/repos/trevato/forge/gates/1793499189025-df28692f87fb/log

It is proved again on a push.

forge map prints the plan of the repository you're in. It takes the repository from --repo owner/name, or from the folder's origin remote when that remote is on the configured workbench. It reuses the folderRepo helper that forge pulls already uses.

• src/cli/api.ts: a new ForgeApi.map(owner, name) reads GET /api/v1/repos/:owner/:name/map. toPlan turns the answer into three groups that don't overlap. Every row takes its title, assignee and pillar from the map's issues list.

- Working is the map's working list. - Ready is the ready issues that are also startable (unassigned and not held), so its count matches the map page's ready count. If the map has no startable list, it uses the unassigned ready issues instead. - Waiting is every open issue with an open blocker in edges, leaving out the ones in Working. Edges to closed issues don't count.

• src/cli/plan.ts: mapLines lays out the plan with no I/O. Each group gets a heading with its count, with a blank line between groups:

- #N title — assignee - #N title — pillar (or no pillar) - #N title — waits on #A, #B

Titles go through inert() and are cut so no line is wider than width - 1. A group stops at 15 lines, followed by … N more.

• src/cli/main.ts: the map command reads the plan and prints it. --json prints the API's answer unchanged. On an error it prints the API's message and exits 1, or 3 for a 401 and 5 for a 403. A bad --repo, or a folder that isn't a clone, exits 2 before any request is made. forge help, the file header, the README and docs/CLI.md all list the command. The README and docs/CLI.md say that Ready is the startable subset.
• test/cli-map.test.ts: runs against a fake map server. It checks:

- the three groups and their counts - the cut at exactly 15 lines with … 5 more - cutting titles to the terminal width - that --json returns the answer unchanged - the 404 and 403 messages and exit codes - the exit-2 cases, with no request made - the fallback when startable is missing - that help lists the command

The import from api.ts in main.ts is back on one line, as on main, and the README's forge map paragraph is rewrapped to 78 columns.

The red gates: the last one stopped before any test ran. The check runs mkdir -p .forge-cache, and the tsc step right after it could not create .forge-cache/tsc.tsbuildinfo because that directory was missing. The gate's working directory changed under it, which no change in this diff can cause. The two gates before it failed on tests that roll forge processes or wait on model grants (rehearsal, model-grant, release-handover). None of those reach src/cli, and they pass here on this head: 20 tests, 0 fail. I changed no test.

The terminal app already shows this plan in src/tui/screens/plan.ts, so I opened no follow-up issue for it.

The 27 test files that scripts/fast.ts names (281 tests) pass, and bun x tsc --noEmit is clean.

Try it: forge map in a clone of a workbench repository, forge map --repo trevato/forge, or forge map --json | jq .startable.

🤖 Generated with Claude Code

Closes #7379

The full suite on this head squashed onto main (accaa65) was red, so the pull has not joined the merge queue.

It named no test (a type error, a timeout, a setup step).

The gate's log: /api/v1/repos/trevato/forge/gates/1793499279023-9a71c1629451/log

It is proved again on a push.

forge map prints the plan of the repository you're in. It takes the repository from --repo owner/name, or from the folder's origin remote when that remote is on the configured workbench. It reuses the folderRepo helper that forge pulls already uses.

• src/cli/api.ts: a new ForgeApi.map(owner, name) reads GET /api/v1/repos/:owner/:name/map. toPlan turns the answer into three groups that don't overlap. Every row takes its title, assignee and pillar from the map's issues list.

- Working is the map's working list. - Ready is the ready issues that are also startable (unassigned and not held), so its count matches the map page's ready count. If the map has no startable list, it uses the unassigned ready issues instead. - Waiting is every open issue with an open blocker in edges, leaving out the ones in Working. A blocker that is closed, or that appears only in edges, holds nothing.

• src/cli/plan.ts: mapLines lays out the plan with no I/O. Each group gets a heading with its count, with a blank line between groups:

- #N title — assignee - #N title — pillar (or no pillar) - #N title — waits on #A, #B

Titles go through inert() and are cut so no line is wider than width - 1. A group stops at 15 lines, followed by … N more.

• src/cli/main.ts: the map command reads the plan and prints it. --json prints the API's answer unchanged. On an error it prints the API's message and exits 1, or 3 for a 401 and 5 for a 403. A bad --repo, or a folder that isn't a clone, exits 2 before any request is made. forge help, the file header, the README and docs/CLI.md all list the command. The README and docs/CLI.md say that Ready is the startable subset.
• test/cli-map.test.ts: runs against a fake map server. It checks:

- the three groups and their counts - the cut at exactly 15 lines with … 5 more - cutting titles to the terminal width - that --json returns the answer unchanged - the 404 and 403 messages and exit codes - the exit-2 cases, with no request made - the fallback when startable is missing - that help lists the command - new: an issue in Working with a closed blocker, and one with an open blocker, stay in Working and never in Waiting. An issue whose blocker appears only in edges waits on nothing. The test fails if either the closed-blocker rule or the Working-over-Waiting rule is removed from toPlan.

The red gates: none of them came from this diff. The last two failed in setup, each on a file missing from the gate's own checkout. In one, .forge-cache was gone right after mkdir -p. In the other, the second bun install found no package.json after the first had run. The earlier ENOENT on a migration file that is in the tree fits the same pattern. I opened #7634 for it, with the three gate logs and what done means, and linked the P0 merge-queue issue #7615 to wait on it. The rehearsal failure on main is already #7632. I changed no test to get past any of this.

The terminal app already shows this plan in src/tui/screens/plan.ts, so I opened no follow-up issue for it.

The 27 test files that scripts/fast.ts names (282 tests) pass, and bun x tsc --noEmit is clean.

Try it: forge map in a clone of a workbench repository, forge map --repo trevato/forge, or forge map --json | jq .startable.

🤖 Generated with Claude Code

Closes #7379

The full suite on this head squashed onto main (accaa65) was red, so the pull has not joined the merge queue.

It named no test (a type error, a timeout, a setup step).

The gate's log: /api/v1/repos/trevato/forge/gates/1793499399099-82a21fdd2bca/log

It is proved again on a push.

forge map prints the plan of the repository you're in. It takes the repository from --repo owner/name, or from the folder's origin remote when that remote is on the configured workbench. It reuses the folderRepo helper that forge pulls already uses.

• src/cli/api.ts: a new ForgeApi.map(owner, name) reads GET /api/v1/repos/:owner/:name/map. toPlan turns the answer into three groups that don't overlap. Every row takes its title, assignee and pillar from the map's issues list.

- Working is the map's working list. - Ready is the ready issues that are also startable (unassigned and not held), so its count matches the map page's ready count. If the map has no startable list, it uses the unassigned ready issues instead. - Waiting is every open issue with an open blocker in edges, leaving out the ones in Working. A blocker that is closed, or that appears only in edges, holds nothing.

• src/cli/plan.ts: mapLines lays out the plan with no I/O. Each group gets a heading with its count, with a blank line between groups:

- #N title — assignee - #N title — pillar (or no pillar) - #N title — waits on #A, #B

Titles go through inert() and are cut so no line is wider than width - 1. A group stops at 15 lines, followed by … N more.

• src/cli/main.ts: the map command reads the plan and prints it. --json prints the API's answer unchanged. On an error it prints the API's message and exits 1, or 3 for a 401 and 5 for a 403. A bad --repo, or a folder that isn't a clone, exits 2 before any request is made.
• Docs: forge help, the file header, the README and docs/CLI.md all list the command and say that Ready is the startable subset. The README now also says the same plan is a screen in the terminal UI: press m on a repository's issues list (src/tui/screens/plan.ts).
• test/cli-map.test.ts: runs against a fake map server. It checks:

- the three groups and their counts - the cut at exactly 15 lines with … 5 more - cutting titles to the terminal width - that --json returns the answer unchanged - the 404 and 403 messages and exit codes - the exit-2 cases, with no request made - the fallback when startable is missing - closed or edge-only blockers, and that Working wins over Waiting - that help lists the command

The red gates: none of them came from this diff. The latest gate also went red 0.6 s in. The cause was ENOENT on src/crew/flow_label.ts and on a migration, both files on main, inside the gate's own checkout. That is the fourth gate on this pull to lose files from its own working tree. I added its log to #7634, which the P0 merge-queue issue #7615 now waits on. I changed no test to get past it. Until #7634 is fixed, a push here may meet the same failure.

The 27 test files that scripts/fast.ts names (282 tests) pass, as does test/cli-docs.test.ts, and bun x tsc --noEmit is clean.

Try it: forge map in a clone of a workbench repository, forge map --repo trevato/forge, or forge map --json | jq .startable.

🤖 Generated with Claude Code

Closes #7379

The full suite on this head squashed onto main (accaa65) was red, so the pull has not joined the merge queue.

Red tests:

• a real roll of two forge processes on one data directory > an old forge that lingers past a probe period refuses nobody
• model budget: zero, an own subscription, a capped grant > a capped grant runs, and stops being offered at the cap
• a push in flight on the old forge completes across the roll, and no connection is refused

The gate's log: /api/v1/repos/trevato/forge/gates/1793499497216-1e898d0466b7/log

It is proved again on a push.

forge map prints the plan of the repository you're in. It takes the repository from --repo owner/name, or from the folder's origin remote when that remote is on the configured workbench. It reuses the folderRepo helper that forge pulls already uses.

• src/cli/api.ts: a new ForgeApi.map(owner, name) reads GET /api/v1/repos/:owner/:name/map. toPlan turns the answer into three groups that don't overlap. Every row takes its title, assignee and pillar from the map's issues list.

- Working is the map's working list. - Ready is the ready issues that are also startable (unassigned and not held), so its count matches the map page's ready count. If the map has no startable list, it uses the unassigned ready issues instead. - Waiting is every open issue with an open blocker in edges, leaving out the ones in Working. A blocker that is closed, or that appears only in edges, holds nothing.

• src/cli/plan.ts: mapLines lays out the plan with no I/O. Each group gets a heading with its count, with a blank line between groups:

- #N title — assignee - #N title — pillar (or no pillar) - #N title — waits on #A, #B

Titles and tails go through inert(), and titles are cut so no line is wider than width - 1. A group stops at 15 lines, followed by … N more.

• src/cli/main.ts: the map command reads the plan and prints it. --json prints the API's answer unchanged. On an error it prints the API's message and exits 1, or 3 for a 401 and 5 for a 403. A bad --repo, or a folder that isn't a clone, exits 2 before any request is made.
• Docs: forge help, the file header, the README and docs/CLI.md all list the command and say that Ready is the startable subset. The README also points to the terminal UI's plan screen (m on a repository's issues list).
• test/cli-map.test.ts: runs against a fake map server. It checks:

- the three groups and their counts - the cut at exactly 15 lines with … 5 more - cutting titles to the terminal width - that --json returns the answer unchanged - the 404 and 403 messages and exit codes - the exit-2 cases, with no request made - the fallback when startable is missing - closed or edge-only blockers, and that Working wins over Waiting - that help lists the command - new: OSC and CSI escape sequences in a title, assignee or pillar come out as U+FFFD with no control bytes left. The test fails if inert() is taken off the title.

The red gates: the latest gate shows the cause directly. In test/model-grant.test.ts, git said Unable to read current working directory: No such file or directory: the gate's checkout was deleted while it ran. The rehearsal and release-handover reds in the same gate are consistent with that, and none of the red tests reach src/cli. I added this log to #7634, which the P0 issue #7615 waits on. I changed no test to get past it. This pull can only join the queue once #7634 is fixed and the gate runs again.

The 27 test files that scripts/fast.ts names (283 tests) pass, and bun x tsc --noEmit is clean.

Try it: forge map in a clone of a workbench repository, forge map --repo trevato/forge, or forge map --json | jq .startable.

🤖 Generated with Claude Code

Closes #7379

The full suite on this head squashed onto main (accaa65) was red, so the pull has not joined the merge queue.

Red tests:

• a real roll of two forge processes on one data directory > an old forge that lingers past a probe period refuses nobody
• model budget: zero, an own subscription, a capped grant > a capped grant runs, and stops being offered at the cap
• a push in flight on the old forge completes across the roll, and no connection is refused

The gate's log: /api/v1/repos/trevato/forge/gates/1793499618869-b9ffa1fc5bfd/log

It is proved again on a push.

forge map prints the plan of the repository you're in. It takes the repository from --repo owner/name, or from the folder's origin remote when that remote is on the configured workbench. It reuses the folderRepo helper that forge pulls already uses.

• src/cli/api.ts: a new ForgeApi.map(owner, name) reads GET /api/v1/repos/:owner/:name/map. toPlan turns the answer into three groups that don't overlap. Every row takes its title, assignee and pillar from the map's issues list.

- Working is the map's working list. - Ready is the ready issues that are also startable (unassigned and not held), so its count matches the map page's ready count. If the map has no startable list, it uses the unassigned ready issues instead. - Waiting is every open issue with an open blocker in edges, leaving out the ones in Working. A blocker that is closed, or that appears only in edges, holds nothing.

• src/cli/plan.ts: mapLines lays out the plan with no I/O. Each group gets a heading with its count, with a blank line between groups:

- #N title — assignee - #N title — pillar (or no pillar) - #N title — waits on #A, #B

Titles and tails go through inert(), and titles are cut so no line is wider than width - 1. A group stops at 15 lines, followed by … N more.

• src/cli/main.ts: the map command reads the plan and prints it. --json prints the API's answer unchanged. On an error it prints the API's message and exits 1, or 3 for a 401 and 5 for a 403. A bad --repo, or a folder that isn't a clone, exits 2 before any request is made.
• Docs: forge help, the file header, the README and docs/CLI.md all list the command and say that Ready is the startable subset. The README and docs/CLI.md point to the terminal UI's plan screen (m on a repository's issues list). docs/CLI.md now also shows the MCP map call, { "name": "map", "arguments": { "app": "alice/shop" } }.
• test/cli-map.test.ts: runs against a fake map server. It checks:

- the three groups and their counts - the cut at exactly 15 lines with … 5 more - cutting titles to the terminal width - that --json returns the answer unchanged - the 404 and 403 messages and exit codes - the exit-2 cases, with no request made - the fallback when startable is missing - closed or edge-only blockers, and that Working wins over Waiting - escapes in a title, assignee or pillar printing inert - that help lists the command

The red gates: none of them came from this diff. The three red tests are the ones #7632 describes for every full gate on main@accaa65, seen on #7463 and #7588 as well. test/rehearsal.test.ts fails, and fail-fast's SIGTERM then turns model-grant and release-handover red. I had read model-grant's lost working directory as evidence for #7634; it is teardown, and I said so in a comment there. #7634 still covers the earlier setup failures, where files were missing before any test ran. This pull can only join the queue once #7632 is fixed. I changed no test to get past it.

The 27 test files that scripts/fast.ts names (283 tests) passed on the last code change, and test/cli-docs.test.ts passes after this docs change. bun x tsc --noEmit is clean.

Try it: forge map in a clone of a workbench repository, forge map --repo trevato/forge, or forge map --json | jq .startable.

🤖 Generated with Claude Code

Closes #7379

The full suite on this head squashed onto main (accaa65) was red, so the pull has not joined the merge queue.

Red tests:

• a real roll of two forge processes on one data directory > an old forge that lingers past a probe period refuses nobody
• model budget: zero, an own subscription, a capped grant > a capped grant runs, and stops being offered at the cap
• a push in flight on the old forge completes across the roll, and no connection is refused

The gate's log: /api/v1/repos/trevato/forge/gates/1793499741353-5e584bb51535/log

It is proved again on a push.

forge map prints the plan of the repository you're in. It takes the repository from --repo owner/name, or from the folder's origin remote when that remote is on the configured workbench. It reuses the folderRepo helper that forge pulls already uses.

• src/cli/api.ts: a new ForgeApi.map(owner, name) reads GET /api/v1/repos/:owner/:name/map. toPlan turns the answer into three groups that don't overlap. Every row takes its title, assignee and pillar from the map's issues list.

- Working is the map's working list. - Ready is the ready issues that are also startable (unassigned and not held), so its count matches the map page's ready count. If the map has no startable list, it uses the unassigned ready issues instead. - Waiting is every open issue with an open blocker in edges, leaving out the ones in Working. A blocker that is closed, or that appears only in edges, holds nothing.

• src/cli/plan.ts: mapLines lays out the plan with no I/O. Each group gets a heading with its count, with a blank line between groups:

- #N title — assignee - #N title — pillar (or no pillar) - #N title — waits on #A, #B

An empty group says nothing being built, nothing ready or nothing waiting under its heading. Titles and tails go through inert(), and titles are cut so no line is wider than width - 1. A group stops at 15 lines, followed by … N more.

• src/cli/main.ts: the map command reads the plan and prints it. --json prints the API's answer unchanged. On an error it prints the API's message and exits 1, or 3 for a 401 and 5 for a 403. A bad --repo, or a folder that isn't a clone, exits 2 before any request is made.
• Docs: forge help, the file header, the README and docs/CLI.md all list the command and say that Ready is the startable subset. The README and docs/CLI.md point to the terminal UI's plan screen (m on a repository's issues list), and docs/CLI.md shows the MCP map call.
• test/cli-map.test.ts: runs against a fake map server. It checks:

- the three groups and their counts - the cut at exactly 15 lines with … 5 more - cutting titles to the terminal width - that --json returns the answer unchanged - the 404 and 403 messages and exit codes - the exit-2 cases, with no request made - the fallback when startable is missing - closed or edge-only blockers, and that Working wins over Waiting - escapes printing inert - that help lists the command - new: an empty group's line under its heading

The red gates: none of them came from this diff. The three red tests are the rehearsal failure that #7632 records for every full gate on main@accaa65, along with the model-grant and release-handover reds that fail-fast's SIGTERM causes. Main is still at accaa65 and #7632 is still open, so the gate on this push will most likely go red the same way. I changed no test to get past it.

The 27 test files that scripts/fast.ts names (284 tests) pass, and bun x tsc --noEmit is clean.

Try it: forge map in a clone of a workbench repository, forge map --repo trevato/forge, or forge map --json | jq .startable.

🤖 Generated with Claude Code

Closes #7379

The full suite on this head squashed onto main (accaa65) was red, so the pull has not joined the merge queue.

Red tests:

• a real roll of two forge processes on one data directory > an old forge that lingers past a probe period refuses nobody
• a push in flight on the old forge completes across the roll, and no connection is refused
• model budget: zero, an own subscription, a capped grant > a capped grant runs, and stops being offered at the cap

The gate's log: /api/v1/repos/trevato/forge/gates/1793499864968-96e4c22bdd09/log

It is proved again on a push.

forge map prints the plan of the repository you're in. It takes the repository from --repo owner/name, or from the folder's origin remote when that remote is on the configured workbench. It reuses the folderRepo helper that forge pulls already uses.

• src/cli/api.ts: a new ForgeApi.map(owner, name) reads GET /api/v1/repos/:owner/:name/map. toPlan turns the answer into three groups that don't overlap. Every row takes its title, assignee and pillar from the map's issues list.

- Working is the open issues in the map's working list. A closed issue, or one missing from issues, is left out instead of printing with an empty title. - Ready is the ready issues that are also startable (unassigned and not held), so its count matches the map page's ready count. If the map has no startable list, it uses the unassigned ready issues instead. - Waiting is every open issue with an open blocker in edges, leaving out the ones in Working. A blocker that is closed, or that appears only in edges, holds nothing.

• src/cli/plan.ts: mapLines lays out the plan with no I/O. Each group gets a heading with its count, with a blank line between groups:

- #N title — assignee - #N title — pillar (or no pillar) - #N title — waits on #A, #B

An empty group says so under its heading. Titles and tails go through inert(), and titles are cut so no line is wider than width - 1. A group stops at 15 lines, followed by … N more.

• src/cli/main.ts: the map command reads the plan and prints it. --json prints the API's answer unchanged. On an error it prints the API's message and exits 1, or 3 for a 401 and 5 for a 403. A bad --repo, or a folder that isn't a clone, exits 2 before any request is made.
• Docs: forge help, the file header, the README and docs/CLI.md all list the command. They point to the terminal UI's plan screen (m on a repository's issues list), and docs/CLI.md shows the MCP map call.
• test/cli-map.test.ts: runs against a fake map server. It checks:

- the three groups and their counts - the cut at exactly 15 lines with … 5 more - cutting titles to the terminal width - that --json returns the answer unchanged - the 404 and 403 messages and exit codes - the exit-2 cases, with no request made - the fallback when startable is missing - closed or edge-only blockers, and that Working wins over Waiting - escapes printing inert - the empty-group line - that help lists the command - new: a closed or unlisted issue in working is not shown as Working. The test fails without the filter.

Plan.raw stays as it is. It holds the same object --json prints, not a copy, so it costs a reference, not a second response.

The red gates: none of them came from this diff. The three red tests are the rehearsal failure that #7632 records for every full gate on main@accaa65, plus the model-grant and release-handover reds that fail-fast's SIGTERM causes. #7632 is still open, so the gate on this push will most likely go red the same way. I changed no test to get past it.

The 27 test files that scripts/fast.ts names (285 tests) pass, and bun x tsc --noEmit is clean.

Try it: forge map in a clone of a workbench repository, forge map --repo trevato/forge, or forge map --json | jq .startable.

🤖 Generated with Claude Code

Closes #7379

The full suite on this head squashed onto main (accaa65) was red, so the pull has not joined the merge queue.

It named no test (a type error, a timeout, a setup step).

The gate's log: /api/v1/repos/trevato/forge/gates/1793499943106-09ad8e44e8d1/log

It is proved again on a push.

forge map prints the plan of the repository you're in. It takes the repository from --repo owner/name, or from the folder's origin remote when that remote is on the configured workbench. It reuses the folderRepo helper that forge pulls already uses.

• src/cli/api.ts: a new ForgeApi.map(owner, name) reads GET /api/v1/repos/:owner/:name/map. toPlan turns the answer into three groups that don't overlap. Every row takes its title, assignee and pillar from the map's issues list.

- Working is the open issues in the map's working list. A closed issue, or one missing from issues, is left out. - Ready is the ready issues that are also startable (unassigned and not held), so its count matches the map page's ready count. If the map has no startable list, it uses the unassigned ready issues instead. - Waiting is every open issue with an open blocker in edges, leaving out the ones in Working. A blocker that is closed, or that appears only in edges, holds nothing.

• src/cli/plan.ts: mapLines lays out the plan with no I/O. Each group gets a heading with its count, with a blank line between groups:

- #N title — assignee - #N title — pillar (or no pillar) - #N title — waits on #A, #B

An empty group says so under its heading. Titles and tails go through inert(), and titles are cut so no line is wider than width - 1. A group stops at 15 lines, followed by … N more.

• src/cli/main.ts: the map command reads the plan and prints it. --json prints the API's answer unchanged. On an error it prints the API's message and exits 1, or 3 for a 401 and 5 for a 403. A bad --repo, or a folder that isn't a clone, exits 2 before any request is made.
• Docs: forge help, the file header, the README and docs/CLI.md all list the command. They point to the terminal UI's plan screen (m on a repository's issues list), and docs/CLI.md shows the MCP map call.
• test/cli-map.test.ts: runs against a fake map server. It checks:

- the three groups and their counts - the cut at exactly 15 lines with … 5 more - cutting titles to the terminal width - that --json returns the answer unchanged - the 404 and 403 messages and exit codes - the exit-2 cases, with no request made - the fallback when startable is missing - closed or edge-only blockers, and that Working wins over Waiting - closed or unlisted issues in working - escapes printing inert - the empty-group line - that help lists the command

No new commit this round. Neither of juniper's two suggestions should land here, and the gate failure has nothing to fix in this branch. An empty commit would only start another gate on the same broken setup.

• One reader for the CLI and the terminal UI: this can't work as suggested. The terminal UI's plan screen runs inside the forge and reads the database directly (repoGraph, readyNow, mapHeldFor). forge map is a client on someone's machine and only has the HTTP API. What keeps them agreeing is that both take Ready from the server: the map's startable list is computed there, and toPlan filters by it instead of working Ready out again.
• --json printing the groups too: --json promises the forge's answer as it came, which is the rule forge asks --json follows and what the round-trip test pins. Scripts get the same Ready group with forge map --json | jq .startable, with no filter of their own. Changing the output's shape would be a separate decision for every CLI command.

The red gate: it stopped on its first step with Module not found "scripts/gate.ts", a file on main, before any test ran. That is the lost-checkout problem in #7634; I added this log there. Beyond that, every full gate on main@accaa65 also goes red in test/rehearsal.test.ts (#7632). Both issues are still open, so this pull can't go green until they are fixed. I changed no test to get past either.

On head b11e1749, the 27 test files that scripts/fast.ts names (285 tests) pass, and bun x tsc --noEmit is clean.

Try it: forge map in a clone of a workbench repository, forge map --repo trevato/forge, or forge map --json | jq .startable.

🤖 Generated with Claude Code

Closes #7379

The full suite on this head squashed onto main (51ca9a6) was red, so the pull has not joined the merge queue.

Red tests:

• the Files page of a 40-file diff: fastest cold view of 3 and fastest repeat view of 5 stay under their ceilings

The gate's log: /api/v1/repos/trevato/forge/gates/1793565896938-4105d6ec6fb0/log

It is proved again on a push.

forge map prints the plan of the repository the current folder belongs to. It has three groups: Ready now (open issues nothing open blocks), Being built (issues with an open pull or an assignee) and Waiting (each blocked issue and the open issues in front of it). It reads the forge's /map endpoint through src/cli/api.ts, and src/cli/plan.ts turns that into plain data. A closed issue counts as done and is never listed. An empty group prints a line saying it is empty under its heading, so the output never looks broken. Titles, assignees and pillar names are printed with escape sequences made harmless, so an issue title can't take over the terminal. docs/CLI.md and the README point to the MCP map tool and the terminal UI's plan screen for the same view.

About the red gate: the failure was the Files page test in test/pull-timing.test.ts (fastest cold view of 3, fastest repeat view of 5). That test times page renders against a fixed limit. This pull changes nothing it measures: the diff is only src/cli/*, the docs and test/cli-map.test.ts. The gate's log link returned not_found for me, so I couldn't see why it failed. Most likely the machine was busy during the run. I merged current main into the branch, and on that tree test/pull-timing.test.ts and test/cli-map.test.ts pass (16 tests, 0 failures) and bun x tsc --noEmit is clean. I didn't loosen the test's time limits, because nothing in this pull gives a reason to.

To try it: inside a clone of this repository, run forge map. The tests are bun test test/cli-map.test.ts.

🤖 Generated with Claude Code

forge map prints the plan of the repository a folder is a clone of, in three groups that don't overlap: Working (what the crew is on, with the assignee), Ready (the map's startable issues, so its count matches the map page) and Waiting (each issue with an open blocker, naming the blockers it waits on). The repository comes from --repo owner/name or the folder's origin remote. --json prints the forge's /api/v1/repos/:owner/:name/map answer as it came.

This update merges main, which added forge search in the same places. The conflicts in src/cli/main.ts, README.md and docs/CLI.md were both sides adding something, so both are kept:

• src/cli/main.ts: map and search each have their own case line and their own function.
• README.md: the forge map line and the two forge search lines are all in the command list.
• docs/CLI.md: the "forge map" section comes before the "forge search" section. The two sections had shared one closing code fence, so the map section's JSON example gets its own again.

bun x tsc --noEmit is clean, and test/cli-*.test.ts, tui-plan, mcp-search and map pass (144 tests). The rest of the suite is left to the forge's check on this push.

To try it, run forge map inside a clone, or forge map --repo trevato/forge from anywhere; add --json for the raw answer.

🤖 Generated with Claude Code

forge map prints the plan of the repository a folder is a clone of, in three groups that don't overlap:

• Working: what the crew is on, with the assignee.
• Ready: the map's startable issues, so its count matches the map page.
• Waiting: each issue with an open blocker, naming the blockers.

The repository comes from --repo owner/name or from the folder's origin remote. --json prints the forge's /api/v1/repos/:owner/:name/map answer as it came.

The check failed because main had moved again: it split src/cli/main.ts into one module per command under src/cli/commands/, and main.ts now dispatches from the list in commands/index.ts instead of a switch. This merge keeps main's version of main.ts. forge map moves, unchanged, into src/cli/commands/map.ts with its line for forge help, and is added to the list in commands/index.ts after asks. The command list in the comment at the top of main.ts names forge map again.

bun x tsc --noEmit is clean, and test/cli-*.test.ts and test/tui-plan.test.ts pass (132 tests), including the 12 in cli-map.test.ts. The rest of the suite is left to the forge's check on this push.

To try it, run forge map inside a clone, or forge map --repo trevato/forge from anywhere; forge help lists it after forge asks.

🤖 Generated with Claude Code