@codedology/code-forge 0.7.0 → 0.7.1

package/CHANGELOG.md

@@ -6,6 +6,14 @@ waits on a second real consumer (plan §10.4, Q17).
 
 ## [Unreleased]
 
+## [0.7.1] — 2026-10-07
+
+### Fixed
+
+- A structured clean pass (passed: true, no findings, every hunk acknowledged, a non-blank summary) is no longer refused
+  as too_short on a larger diff: it needs 40 output tokens whatever the diff size (clean passes measured 108-121 tokens;
+  issue #6). An answer with any finding, or a blank summary, keeps review.min_tokens_out.
+
 ## [0.7.0] — 2026-10-07
 
 ### Fixed

package/README.md

@@ -8,16 +8,24 @@ for cross-model, parallel, evidence-gated feature delivery — on Claude Code, C
 > `examples/` have all landed (`docs/reference/blocks.json` lists every build block). What changed
 > in each version is in [CHANGELOG.md](CHANGELOG.md).
 
-## What's new in 0.6
+## What's new in 0.7
 
 Next release:
 
+- **Short clean reviews count.** A clean pass (no findings, every hunk acknowledged, a summary)
+  needs only 40 output tokens on any diff size, so a correct short "no defect" review is no
+  longer refused as `too_short`.
+
+In 0.7.0:
+
 - **The close gate now checks every file.** `block close` could close a block with critical
   findings still open: files inside an owned folder were skipped, and so was work committed
   before `block open` or done in another worktree. Now every reviewed file is checked, a newer
   failed review beats an older approval, a critical needs your waiver, a change outside the
   block's files is refused, and `--no-require-reviews` asks you at a terminal.
 
+## What's new in 0.6
+
 In 0.6.1:
 
 - **Never relax a rule alone.** A new skill rule (R17): the orchestrator and the delegate never

package/docs/reference/blocks.json

@@ -4,7 +4,7 @@
     "plans/code-forge-plan-v1.3.md §10.4",
     "plans/NIGHT-LOG.md"
   ],
-  "block_count": 55,
+  "block_count": 56,
   "baseline_ids": ["B0", "B1", "B2", "B3", "B4", "B5", "B6", "B7", "B8"],
   "baseline_note": "Wave 0-1 blocks, landed before v1.3; depends_on may name them, but they have no entry under blocks.",
   "blocks": {
@@ -748,6 +748,20 @@
         "B50"
       ],
       "note": "root-added 2026-10-07; GitHub issue #2 field note 2026-10-07; also amends src/state/block.mjs, src/review/triage.mjs, src/worker/loop.mjs, skill/SKILL.md, skill/references/{code,review,decisions}.md, skill/references/adapters/{claude-code,solo}.md, docs/how-it-works.md, docs/tutorial-first-test.md, docs/concepts.md"
+    },
+    "B53": {
+      "title": "Clean-pass token floor for any diff size (issue #6): a structured clean pass (passed: true, no findings, hunks acknowledged in order, a non-blank summary) needs min(review.min_tokens_out, 40) output tokens; any finding, passed: false or a blank summary keeps the full floor",
+      "wave": 12,
+      "level": "L1",
+      "status": "landed",
+      "owned": [
+        "src/review/validate-review.mjs",
+        "test/review/validate-review.test.mjs"
+      ],
+      "depends_on": [
+        "B52"
+      ],
+      "note": "root-added 2026-10-07; GitHub issue #6; also amends src/review/engine.mjs (smallDiff removed), schema/code-forge.schema.json, docs/reference/config.md, docs/how-it-works.md, skill/references/review.md"
     }
   }
 }

package/docs/reference/config.md

@@ -105,7 +105,7 @@ Every other key defaults as shown, or is entirely absent from a minimal file. `a
 | `review.context.min_context_lines` | integer |  | `10` | min 0 |
 | `review.block_budget_tokens` | integer |  | `150000` | min 1 |
 | `review.block_budget_usd` | number \| null |  | `null` |  |
-| `review.min_tokens_out` | integer |  | `120` | min 1 |
+| `review.min_tokens_out` | integer |  | `120` | min 1; The stub guard: a review answer with fewer output tokens is unavailable (too_short). A clean pass (passed: true, no findings, a non-blank summary) needs only min(this, 40), whatever the diff size (B53). |
 | `review.batch_small_files` | boolean |  | `true` |  |
 | `review.session_timeout_s` | integer |  | `300` | min 1 |
 | `review.max_rounds_per_file` | integer |  | `4` | min 2; max 6 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codedology/code-forge",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Plan/harden/code/review orchestration CLI and Agent Skill for cross-model, parallel, evidence-gated feature delivery.",
   "repository": {
     "type": "git",

package/schema/code-forge.schema.json

@@ -136,7 +136,7 @@
           "anyOf": [{ "type": "number", "exclusiveMinimum": 0 }, { "type": "null" }],
           "default": null
         },
-        "min_tokens_out": { "type": "integer", "minimum": 1, "default": 120 },
+        "min_tokens_out": { "type": "integer", "minimum": 1, "default": 120, "description": "The stub guard: a review answer with fewer output tokens is unavailable (too_short). A clean pass (passed: true, no findings, a non-blank summary) needs only min(this, 40), whatever the diff size (B53)." },
         "batch_small_files": { "type": "boolean", "default": true },
         "session_timeout_s": { "type": "integer", "minimum": 1, "default": 300 },
         "max_rounds_per_file": { "type": "integer", "minimum": 2, "maximum": 6, "default": 4 },

package/skill/references/review.md

@@ -19,7 +19,7 @@ Every reviewer, recheck, judge and S2 session runs with cwd = a fresh empty temp
 
 ## §4 The stub guard — what counts as a review (R11)
 
-A result is a review only if the process exited 0, the JSON validates against the finding schema, `reviewed_hunks` equals the packet's hunk headers exactly and in order, and the output has at least `review.min_tokens_out` tokens. Anything else is ledger `review.unavailable` (`exit`, `schema`, `hunks_mismatch`, `too_short`, `timeout`, `budget` — the run reached `budget.usd`, `ledger.md` §3.1) and **is not approval**; the worker retries once on the level's fallback, then the file stays unreviewed and the block cannot close. A session that hangs is killed at `review.session_timeout_s` (default 300), process group and all, and is spawned once more on the same packet and level; only a second timeout is `unavailable: timeout`. Each timed-out attempt leaves a `review.session_timeout` ledger note with the last 4 KB of its stderr (redacted, never the packet) and only the byte count and last event types of its stdout.
+A result is a review only if the process exited 0, the JSON validates against the finding schema, `reviewed_hunks` equals the packet's hunk headers exactly and in order, and the output has at least `review.min_tokens_out` tokens (a clean pass — `passed: true`, no findings, a non-blank summary — needs only 40, whatever the diff size). Anything else is ledger `review.unavailable` (`exit`, `schema`, `hunks_mismatch`, `too_short`, `timeout`, `budget` — the run reached `budget.usd`, `ledger.md` §3.1) and **is not approval**; the worker retries once on the level's fallback, then the file stays unreviewed and the block cannot close. A session that hangs is killed at `review.session_timeout_s` (default 300), process group and all, and is spawned once more on the same packet and level; only a second timeout is `unavailable: timeout`. Each timed-out attempt leaves a `review.session_timeout` ledger note with the last 4 KB of its stderr (redacted, never the packet) and only the byte count and last event types of its stdout.
 
 ## §5 The convergence rule — bounded fix rounds (R15)
 

package/skill/scripts/forge

@@ -10,7 +10,7 @@
 #      copied install with no package next to it); `test/skill/shim.test.mjs` asserts the pin
 #      equals package.json's version.
 # The shim holds no logic of its own: every verb, flag and message is the CLI's.
-PINNED_VERSION="0.7.0"
+PINNED_VERSION="0.7.1"
 set -eu
 
 self="$0"

package/src/review/engine.mjs

@@ -33,7 +33,7 @@ import { blockKind, isDocsKind } from '../decide/escalation.mjs';
 import { fallbackRisk } from '../decide/fallback-rules.mjs';
 import { tierFor } from '../proof/tiers.mjs';
 import { assembleJudgePacket, assemblePacket, attachFiles, budgetFor, readFileDiff } from './packet.mjs';
-import { FINDING_SCHEMA, minTokensOut, SMALL_DIFF_ADDED_LINES, validateReview } from './validate-review.mjs';
+import { FINDING_SCHEMA, minTokensOut, validateReview } from './validate-review.mjs';
 import { spawnWithTimeoutRetry } from './session-retry.mjs';
 import { assertRowPath } from '../worker/ticket.mjs';
 
@@ -194,12 +194,11 @@ export async function reviewFile(input, deps) {
   if (diff.diffText.trim().length === 0) return { status: 'no_change', approved: false, ...head, sessions: [] };
   mkdirSync(workDir, { recursive: true, mode: 0o700 });
   const min = minTokensOut(cfg);
-  const smallDiff = diff.plusCount <= SMALL_DIFF_ADDED_LINES;
 
   /** @param {SessionSpec} spec @param {{text: string, hunkHeaders: string[], tokensIn: number, contextMode: string | null}} packet */
   const run = async (spec, packet) => {
     /** @type {Record<string, any>} */
-    let summary = await runOne(spec, packet.text, packet, { deps, workDir, min, smallDiff, cfg });
+    let summary = await runOne(spec, packet.text, packet, { deps, workDir, min, cfg });
     const needs = summary.review?.needs_file;
     if (spec.role === 'reviewer' && summary.status === 'ok' && Array.isArray(needs) && needs.length > 0) {
       const paths = safeNeeds(needs);
@@ -210,7 +209,7 @@ export async function reviewFile(input, deps) {
         extra = null;
       }
       if (extra === null) return { ...summary, status: 'unavailable', reason: 'needs_file-refused', review: null };
-      summary = { ...(await runOne(spec, `${packet.text}${extra}`, packet, { deps, workDir, min, smallDiff, cfg })), needs_file_round: true };
+      summary = { ...(await runOne(spec, `${packet.text}${extra}`, packet, { deps, workDir, min, cfg })), needs_file_round: true };
     }
     return summary;
   };
@@ -234,7 +233,7 @@ export async function reviewFile(input, deps) {
   if (judgeSpec) {
     const bySlot = Object.fromEntries(done.map((s) => [s.slot, s.review]));
     const packet = assembleJudgePacket({ diff, reports: { A: bySlot.A, B: bySlot.B }, cfg });
-    final = await runOne(judgeSpec, packet.text, packet, { deps, workDir, min, smallDiff, cfg });
+    final = await runOne(judgeSpec, packet.text, packet, { deps, workDir, min, cfg });
     sessions.push(publicSummary(final));
     if (final.status !== 'ok') {
       await note(deps, { event: 'review.unavailable', reason: final.reason, lens: 'judge' });
@@ -250,9 +249,9 @@ export async function reviewFile(input, deps) {
  * One session: packet file (0600, removed after), spawn, stub guard.
  * @param {SessionSpec} spec @param {string} text
  * @param {{hunkHeaders: string[], tokensIn: number, contextMode: string | null}} packet
- * @param {{deps: ReviewDeps, workDir: string, min: number, smallDiff?: boolean, cfg: Record<string, any>}} env
+ * @param {{deps: ReviewDeps, workDir: string, min: number, cfg: Record<string, any>}} env
  */
-async function runOne(spec, text, packet, { deps, workDir, min, smallDiff = false }) {
+async function runOne(spec, text, packet, { deps, workDir, min }) {
   const promptPath = path.join(workDir, `${spec.lens}-${randomBytes(6).toString('hex')}.md`);
   const base = { lens: spec.lens, role: spec.role, level: spec.level, slot: spec.slot, context_mode: packet.contextMode, ctx_tokens_in: packet.tokensIn };
   writeFileSync(promptPath, text, { mode: 0o600 });
@@ -285,7 +284,7 @@ async function runOne(spec, text, packet, { deps, workDir, min, smallDiff = fals
   } finally {
     rmSync(promptPath, { force: true });
   }
-  const verdict = validateReview(res, { hunkHeaders: packet.hunkHeaders, minTokensOut: min, smallDiff });
+  const verdict = validateReview(res, { hunkHeaders: packet.hunkHeaders, minTokensOut: min });
   const meta = {
     ...base,
     provider: res?.provider ?? null,

package/src/review/validate-review.mjs

@@ -5,7 +5,7 @@
  *  1. the process exited 0 (not killed at the session timeout);
  *  2. the answer is a JSON object that validates against `finding.schema.json`;
  *  3. `reviewed_hunks` equals the packet's hunk headers EXACTLY and IN ORDER;
- *  4. `tokens_out ≥ review.min_tokens_out` (120).
+ *  4. `tokens_out ≥ review.min_tokens_out` (120), or ≥ 40 for a structured clean pass (B53).
  * Anything else is `unavailable` with one reason — `timeout`, `exit`, `schema`,
  * `hunks_mismatch`, `too_short`, or `budget` (B33: the spawner refused at `budget.usd`) — and is
  * never approval. There is no "approve on missing output":
@@ -20,13 +20,13 @@ export const UNAVAILABLE_REASONS = Object.freeze(['exit', 'schema', 'hunks_misma
 export const DEFAULT_MIN_TOKENS_OUT = 120;
 
 /**
- * A clean pass (`passed: true`, no findings, every hunk acknowledged) on a SMALL diff legitimately
- * needs few words: a 3-line placeholder reviewed by GPT-6 Astra produced 108 tokens and was refused
- * as `too_short`. For such answers the floor drops to this value; any finding keeps the full floor.
+ * A structured clean pass legitimately needs few words, whatever the diff size: GPT-6 Astra clean
+ * passes measured 108-121 output tokens while reviews with findings measured 300-1,400, so the full
+ * floor refused 11 of 19 clean files on one block (issue #6). A clean pass is `passed: true`, no
+ * findings, every hunk acknowledged in order (checked above) and a non-blank `summary`; for it the
+ * floor drops to this value. Any finding, or a blank summary, keeps the full floor (B53).
  */
 export const CLEAN_PASS_MIN_TOKENS_OUT = 40;
-/** A diff with at most this many added lines is "small" for the clean-pass floor. */
-export const SMALL_DIFF_ADDED_LINES = 20;
 
 /** The source answer schema (compiled per provider by the spawner). */
 export const FINDING_SCHEMA = Object.freeze(JSON.parse(readFileSync(new URL('./finding.schema.json', import.meta.url), 'utf8')));
@@ -55,10 +55,10 @@ export function minTokensOut(cfg) {
 
 /**
  * @param {Record<string, any> | null | undefined} session - a `spawnSession` result.
- * @param {{hunkHeaders: ReadonlyArray<string>, minTokensOut?: number, smallDiff?: boolean}} expect - `smallDiff` lowers the floor to `CLEAN_PASS_MIN_TOKENS_OUT` for a clean pass only
+ * @param {{hunkHeaders: ReadonlyArray<string>, minTokensOut?: number}} expect
  * @returns {Verdict}
  */
-export function validateReview(session, { hunkHeaders, minTokensOut: min = DEFAULT_MIN_TOKENS_OUT, smallDiff = false }) {
+export function validateReview(session, { hunkHeaders, minTokensOut: min = DEFAULT_MIN_TOKENS_OUT }) {
   if (!session || typeof session !== 'object') return { ok: false, reason: 'exit', detail: 'no session result' };
   if (session.status === 'timeout') return { ok: false, reason: 'timeout', detail: 'killed at the session timeout' };
   // B33: the spawner refused the session because the run reached `budget.usd` — nothing ran
@@ -77,9 +77,9 @@ export function validateReview(session, { hunkHeaders, minTokensOut: min = DEFAU
     return { ok: false, reason: 'hunks_mismatch', detail: `reviewed_hunks has ${got.length} entries; the packet has ${hunkHeaders.length} hunks` };
   }
   const tokensOut = Number(session.usage?.tokens_out ?? session.row?.tokens_out ?? 0);
-  const review = /** @type {{passed: boolean, findings: unknown[]}} */ (session.answer);
-  const cleanPass = review.passed === true && Array.isArray(review.findings) && review.findings.length === 0;
-  const floor = smallDiff && cleanPass ? Math.min(min, CLEAN_PASS_MIN_TOKENS_OUT) : min;
+  const review = /** @type {{passed: boolean, summary: string, findings: unknown[]}} */ (session.answer);
+  const cleanPass = review.passed === true && Array.isArray(review.findings) && review.findings.length === 0 && review.summary.trim().length > 0;
+  const floor = cleanPass ? Math.min(min, CLEAN_PASS_MIN_TOKENS_OUT) : min;
   if (!(tokensOut >= floor)) return { ok: false, reason: 'too_short', detail: `tokens_out ${tokensOut} < ${floor}` };
   return { ok: true, review: session.answer, tokens_out: tokensOut };
 }