@nanobpm/nano-workforce 0.200.4 → 0.200.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.200.4",
+  "version": "0.200.5",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",

package/resources/prompts/feature.md

@@ -133,6 +133,17 @@ you on the right side of it:
    (`Refs #N` / `Part of #N`) and **leave #N open** (or convert #N into a
    tracking/umbrella issue for the remainder). The classifier flags a PR that
    closes #N while leaving part of #N's stated scope undelivered and untracked.
+   **This rule governs your COMMIT MESSAGES and your PR TITLE too, not just the PR
+   body.** This repo family squash-merges with `COMMIT_MESSAGES`, so a `Closes #N`
+   in **any commit body** closes the issue on merge — even after you correct the PR
+   body to `Part of #N`. The **PR title becomes the squash commit SUBJECT**, so a
+   closing keyword in the title (`fix: parser slice (Closes #N)`) likewise closes #N
+   on merge. A partial slice whose PR body says `Part of #N` but whose first commit —
+   or whose title — still carries `Closes #N` *still* closes the broader parent on
+   merge, and the scope gate scans the title and commit bodies as well as the PR
+   body. So when you split scope, write `Part of #N` (never a closing keyword) in the
+   PR **title**, the PR body, and every commit body; if an early commit already
+   closed it, amend/reword that commit before you push.
 2. **A deferred remainder must be a FILED, tracked issue — never just prose.** If
    your PR defers part of its scope, **file a follow-up issue for each deferred
    item** and link it in the PR body with an explicit tracking marker the classifier

package/resources/prompts/plan.md

@@ -84,10 +84,15 @@ For every distinct child issue number `N` you find:
 - Otherwise, emit **one task** for it (see the output contract), with:
   - `id` = `issue-N`,
   - `title` = the sub-issue's title,
-  - `prompt` = a self-contained brief built from the sub-issue's body, and end
-    the prompt with an explicit instruction to the implementing agent to open its
-    PR against this specific sub-issue and include `Closes #N` in the PR body so
-    the sub-issue is linked and auto-closed on merge.
+  - `prompt` = a self-contained brief built from the sub-issue's body carrying
+    **#N's FULL stated scope** (every acceptance criterion / checkbox of the
+    sub-issue — an adopted sub-issue task owns its whole sub-issue, so the brief
+    must not silently cover only part of it), and end the prompt with an explicit
+    instruction to the implementing agent to open its PR against this specific
+    sub-issue and include `Closes #N` in the PR body so the sub-issue is linked and
+    auto-closed on merge. A closing keyword is only correct because the task
+    delivers #N in full; **never pair `Closes #N` with a brief scoped to a subset
+    of #N** (see "Closing keywords" below).
   - `dependsOn` = **honour any inter-sub-issue ordering the human declared.** Scan
     the sub-issue's body for an explicit dependency directive — a line such as
     `Depends-on: #7`, `Depends on #7`, or `Blocked by #7` (case-insensitive; there
@@ -192,6 +197,58 @@ a cohesive published artifact at the same time. Reserve genuinely separate packa
 for the consumer-facing cases above, and say in the task prompt which consumer
 justifies the split.
 
+### Closing keywords → only a FULL-scope slice may close its issue
+
+When you decompose one issue into several slices, each slice delivers only **part**
+of that issue's acceptance criteria. A slice scoped to a subset of an issue's scope
+**must not be told to close that issue** — that is the exact planning defect this
+rule exists to prevent (a node scoped to one of an issue's three acceptance
+criteria was told to "close" it, the remainder was lost, and a human had to file
+the follow-up and rewrite the PR by hand).
+
+So, when you author each slice's `prompt`:
+
+- **Only instruct a closing keyword (`Closes/Fixes/Resolves #N`) in a slice whose
+  brief delivers #N's FULL stated scope — and say so in an issue-anchored
+  whole-scope phrase the deterministic validator recognises.** If exactly one
+  slice covers the whole issue (the common single-task case), it may close it. If
+  you split the issue across slices, the parent issue is **broader** than any one
+  slice — so **no slice** closes it with a bare brief: instruct each partial slice
+  to reference the parent non-blockingly (`Part of #N` / `Refs #N`) and **leave
+  #N open**, OR designate one final slice that carries the `Closes #N`. That final
+  slice is the exception only when its brief makes it **own and verify #N's
+  COMPLETE stated scope** — every acceptance criterion, not just the remainder.
+  `dependsOn` on the sibling slices orders the merges, but it does **not** by
+  itself make the final slice's brief full-scope: a final slice scoped only to
+  "the remaining criterion" is still a partial brief and must **not** close #N.
+  Scope the final closer to re-verify the whole issue (its brief must direct it to
+  check every checkbox and confirm the siblings' merged work satisfies them)
+  before it emits `Closes #N`.
+  **The validator (`validateDeliveryGraph`) enforces this deterministically:** an
+  `agent.prompt` that closes an issue is rejected unless the brief also carries an
+  explicit **issue-anchored whole-scope acknowledgement TIED TO THE ISSUE IT
+  CLOSES**. Anchor the acknowledgement to the **same** issue — e.g. "delivers #N's
+  full stated scope", "every acceptance criterion of #N", "all of #N", "the whole
+  issue #N". A marker that names a **different** issue than the one you close
+  (acknowledge #11's scope, but `Closes #12`), or one that attributes the scope to
+  **siblings/other slices** ("the full scope of #N is handled by siblings"), does
+  **not** count — the validator credits a whole-scope phrase to issue #N only when it
+  sits in the same clause as #N (or when the prompt references exactly one issue) and
+  is not attributed to others. When a prompt closes more than one issue, give **each**
+  closing target its own anchored acknowledgement. A **bare adverb of completeness does not count** —
+  "fully", "completely", "end-to-end", "in full", "in its entirety" can modify a
+  *partial* deliverable ("implement one criterion fully"), so the validator
+  ignores them; always name the issue's whole scope, not just an adverb.
+- **The remainder must be tracked, never dropped.** Every acceptance criterion of
+  the split issue must be covered by **some** slice in this plan (collectively the
+  slices must deliver #N's whole scope). Do not emit a slice set that silently
+  under-delivers the parent while one slice closes it.
+- **This governs the COMMIT MESSAGES you tell the agent to write, too.** This repo
+  family squash-merges with `COMMIT_MESSAGES`, so a `Closes #N` in **any commit
+  body** closes the issue on merge even if the PR body says `Part of #N`. When a
+  slice is partial, instruct the agent to write `Part of #N` (never a closing
+  keyword) in **both** the PR body and every commit body.
+
 ## Output contract
 
 Write a JSON object of **result variables** to the file named by the

package/resources/prompts/scope-classify.md

@@ -46,13 +46,46 @@ result.
 
 ## What to do
 
-1. **Read the PR body.** `gh pr view <prNumber> --repo <repo> --json body,title`.
+1. **Read the PR body, the PR TITLE, AND the commit bodies.**
+   `gh pr view <prNumber> --repo <repo> --json body,title`.
    Extract every issue the body **closes with a GitHub closing keyword** —
    `close/closes/closed`, `fix/fixes/fixed`, `resolve/resolves/resolved` followed by
-   `#N`, `owner/repo#N`, or a full issue URL. A **non-closing** reference (`Refs #N`,
+   `#N`, `owner/repo#N`, or a full issue URL. GitHub also recognises an **optional colon**
+   between the keyword and its target (`Closes: #12`, `Fixes: owner/repo#12`), so treat the
+   colon form as a closing reference too. A **non-closing** reference (`Refs #N`,
    `Part of #N`, `Depends-on #N`, `Follow-up: #N`) does **not** close an issue —
    ignore those for the closing-scope check (but note the follow-up links; see below).
 
+   **Scan the PR TITLE with these exact same closing-keyword rules too.** This repo
+   family squash-merges, so the **PR title becomes the squash commit SUBJECT**
+   (`AGENTS.md` "PR titles must be Conventional too — they become the release trigger"),
+   and GitHub honours a closing keyword in the squash subject exactly like one in the
+   body or a commit. So a conventional title such as `fix: parser slice (Closes #12)`
+   **closes #12 on merge** even when the body only says `Part of #12` and every commit
+   is clean. Treat a closing keyword found in the **title** exactly like one in the PR
+   body — add its `#N` to the set of closed issues you judge below (and if the slice is
+   partial, tell the human to reword the title to a non-closing form).
+
+   **Then scan the PR's commit messages for the same closing keywords.** Use the
+   **full commit history** — fetch base and head, then
+   `git log --format='%H%n%B' origin/<base>..<head>` (or `git log origin/<base>..<head>`).
+   **Do NOT rely on `gh pr view <prNumber> --repo <repo> --json commits` for this:**
+   the GitHub CLI silently truncates the `commits` field at **100 entries**, so on a
+   101–250-commit PR it can miss an offending `Closes #N` in a later commit and
+   incorrectly clear the scope gate. If you must use the API instead of `git log`,
+   page it explicitly (`gh api --paginate .../pulls/<prNumber>/commits`) rather than
+   the capped `--json commits`. Likewise do **not** use `gh pr diff` here — it returns
+   only the patch, not the commit subjects/bodies, so it cannot detect a closing
+   keyword and would incorrectly clear the PR. This matters because this repo
+   family **squash-merges with `COMMIT_MESSAGES`**: the squash commit concatenates
+   every commit body, so a `Closes #N` left in **any commit body closes #N on
+   merge** even when the PR body was later corrected to `Part of #N`. Treat a
+   closing keyword found in a commit body **exactly** like one in the PR body — add
+   its `#N` to the set of closed issues you judge below. A PR whose body says
+   `Part of #N` but whose commit body still carries `Closes #N`, while part of #N's
+   scope is undelivered and untracked, is a genuine under-delivery you must block
+   (name the offending commit and tell the human to reword/amend it to `Part of #N`).
+
 2. **If there are no closing-keyword issues, the PR closes nothing** — there is no
    broader-scoped parent to under-deliver. Return **`scopeBlocked: false`** and stop.
 

package/scripts/scope-closing-keyword.test.ts

@@ -0,0 +1,139 @@
+// Guard for issue #858: a planner must not scope an agent node to PART of an issue while still
+// telling it to CLOSE that issue, and the scope gate + agent contract must cover COMMIT bodies.
+//
+// Field case (merlin, delivery graph `5e36636255ab`): node `i12`'s prompt said "implement
+// nano-supervisor#12 and open a PR … that closes it", but the body only described one of #12's
+// three acceptance criteria. The agent did exactly that and wrote `Closes #12` in BOTH the PR body
+// and the commit body. The convergence scope gate blocked, but a human still had to file the
+// follow-up and rewrite the PR. The defect was in planning: a node scoped narrower than its issue
+// must not be told to close it. The repo squash-merges with `COMMIT_MESSAGES`, so a `Closes #N` in a
+// commit body closes the issue on merge even after the PR body is corrected — so the agent contract,
+// the planner, and the scope gate must all reason about commit bodies, not just the PR body.
+//
+// These are prompt CONTRACTS (not code paths): the planner (`plan.md`), the implementation agent
+// (`feature.md`), and the scope gate (`scope-classify.md`) are all prompt-driven. This test pins the
+// guidance so a future prompt edit cannot silently drop the guard that closes this failure class.
+import { test } from "node:test";
+import { assert } from "#test-assert";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const PROMPTS_DIR = join(import.meta.dirname, "..", "resources", "prompts");
+const read = (name: string): string => readFileSync(join(PROMPTS_DIR, name), "utf8");
+
+// The GitHub closing keywords, as the gate/agent must recognise them. A "closing keyword" in prose
+// is any of these; a non-closing ref (`Part of`, `Refs`, `Follow-up`) is explicitly NOT.
+const CLOSING_KEYWORDS = ["close", "fix", "resolve"];
+
+// The closing-keyword SYNTAX each prompt must document for EVERY verb family — the canonical
+// instruction triplet `Closes/Fixes/Resolves` (or the inflected `close/closes/closed …
+// fix/fixes/fixed … resolve/resolves/resolved` listing). Asserting the syntax (not a bare
+// `includes("fix")`, which passes for unrelated reasons) means dropping a family from a contract —
+// e.g. removing `Fixes` — turns the test red instead of leaving it green.
+const CLOSING_SYNTAX = [
+  /closes?\/fixes?\/resolves?/i,
+  /close\/closes\/closed[\s\S]*fix\/fixes\/fixed[\s\S]*resolve\/resolves\/resolved/i,
+];
+
+test("feature.md: the closing-keyword rule covers COMMIT MESSAGES, not just the PR body", () => {
+  const feature = read("feature.md").toLowerCase();
+  // The agent contract must tell the agent a closing keyword in a commit body closes the issue on
+  // merge (the COMMIT_MESSAGES squash concern), so a partial slice must write `Part of #N` in both.
+  assert(
+    feature.includes("commit messages") || feature.includes("commit body") || feature.includes("commit bodies"),
+    "feature.md must tie the closing-keyword rule to commit messages/bodies",
+  );
+  assert(feature.includes("commit_messages"), "feature.md must name the COMMIT_MESSAGES squash behaviour");
+});
+
+test("plan.md: a partial slice must not be told to close its broader-scoped parent issue", () => {
+  const plan = read("plan.md");
+  const lower = plan.toLowerCase();
+  // The decomposition step must carry explicit closing-keyword guidance for split issues.
+  assert(lower.includes("closing keyword"), "plan.md must discuss closing keywords for slices");
+  // A full-scope requirement must gate a closing keyword, and a partial slice must use `Part of #N`.
+  assert(lower.includes("full"), "plan.md must require FULL scope before a slice closes an issue");
+  assert(plan.includes("Part of #N"), "plan.md must steer a partial slice to `Part of #N`");
+  // The planner guidance must also reach commit messages (the COMMIT_MESSAGES squash concern).
+  assert(lower.includes("commit_messages") || lower.includes("commit bod"), "plan.md must cover commit bodies");
+});
+
+test("scope-classify.md: the scope gate scans COMMIT bodies for closing keywords too", () => {
+  const gate = read("scope-classify.md");
+  const lower = gate.toLowerCase();
+  // The gate must read the PR's commits (not only its body) for closing keywords.
+  assert(lower.includes("commit"), "scope-classify.md must mention commits");
+  // It must name the commit body/message as the thing to scan…
+  assert(
+    lower.includes("commit bod") || lower.includes("commit message"),
+    "scope-classify.md must instruct reading commit bodies/messages",
+  );
+  // …AND prescribe an actual FULL-HISTORY retrieval mechanism the contract permits (`git log` or an
+  // explicitly `--paginate`d API call). Merely mentioning "commit bodies" — or the capped, explicitly
+  // FORBIDDEN `--json commits` — is not enough: deleting the real retrieval instruction would leave a
+  // substring-only check green while the gate silently loses its ability to see a `Closes #N` in a
+  // later commit of a >100-commit PR (issue #858 round-5 review).
+  assert(
+    /git\s+log/.test(lower) || lower.includes("--paginate"),
+    "scope-classify.md must prescribe a full-history commit retrieval (`git log` or a `--paginate`d " +
+      "API call), not the capped `--json commits`",
+  );
+  // It must explain WHY: the COMMIT_MESSAGES squash carries a commit-body closing keyword to merge.
+  assert(lower.includes("commit_messages"), "scope-classify.md must name the COMMIT_MESSAGES squash behaviour");
+});
+
+test("scope-classify.md: the scope gate scans the PR TITLE for closing keywords (squash subject)", () => {
+  const gate = read("scope-classify.md");
+  const lower = gate.toLowerCase();
+  // A closing keyword in the PR title becomes the squash commit SUBJECT and closes the issue on merge,
+  // so the gate must scan the title with the same closing-keyword rules as the body/commits — not only
+  // fetch it (issue #858 round-16 review). Pin the instruction, not just the `--json body,title` fetch.
+  assert(lower.includes("title"), "scope-classify.md must reference the PR title");
+  assert(
+    /scan\s+the\s+pr\s+title|title[\s\S]{0,80}closing[- ]keyword|closing[- ]keyword[\s\S]{0,80}title/.test(lower),
+    "scope-classify.md must instruct scanning the PR TITLE with the closing-keyword rules",
+  );
+  // …and explain WHY the title matters: it becomes the squash commit subject.
+  assert(
+    /squash\s+(?:commit\s+)?subject|title\s+becomes\s+the\s+squash/.test(lower),
+    "scope-classify.md must explain the title becomes the squash commit subject",
+  );
+});
+
+test("feature.md: the no-close-on-partial rule also governs the PR TITLE (squash subject)", () => {
+  const lower = read("feature.md").toLowerCase();
+  // The agent authors the PR title, so its contract must warn that a closing keyword there closes the
+  // issue on merge (title -> squash subject), not only the body/commit bodies (issue #858 round-16).
+  assert(lower.includes("title"), "feature.md must reference the PR title in the closing-keyword rule");
+  assert(
+    /title\s+becomes\s+the\s+squash|squash\s+(?:commit\s+)?subject/.test(lower),
+    "feature.md must tie the PR title to the squash commit subject",
+  );
+});
+
+test("all three prompts recognise the full set of GitHub closing keywords", () => {
+  for (const name of ["feature.md", "plan.md", "scope-classify.md"]) {
+    const lower = read(name).toLowerCase();
+    for (const kw of CLOSING_KEYWORDS) {
+      assert(lower.includes(kw), `${name} must reference the closing keyword family "${kw}"`);
+    }
+  }
+});
+
+// Stronger than the substring check above: pin the closing-keyword SYNTAX in each prompt, so a future
+// edit that drops a verb family from the contract (e.g. `Closes/Resolves` with `Fixes` removed) fails
+// loudly instead of staying green because the word "fix" still appears somewhere unrelated.
+test("all three prompts document the closing-keyword SYNTAX for every verb family (close/fix/resolve)", () => {
+  for (const name of ["feature.md", "plan.md", "scope-classify.md"]) {
+    const text = read(name);
+    assert(
+      CLOSING_SYNTAX.some((re) => re.test(text)),
+      `${name} must document the Closes/Fixes/Resolves closing-keyword triplet (or the inflected ` +
+        `close/closes/closed … listing), not merely the bare substrings`,
+    );
+    assert(
+      /\bcloses?\s+#(?:n|\d)/i.test(text),
+      `${name} must show the actionable \`Closes #N\` instruction form`,
+    );
+  }
+});