cclaw-cli 0.5.13 → 0.5.15

package/dist/artifact-linter.js

@@ -199,6 +199,7 @@ function validateSectionBody(sectionBody, rule) {
                     details: `Rule expects exactly one selected token (${tokens.join(", ")}); found ${selected.size}.`
                 };
             }
+            return { ok: true, details: "Exactly one token selected as expected." };
         }
     }
     if (/Status:\s*pending\s+until/iu.test(rule)) {
@@ -419,9 +420,34 @@ export async function validateReviewArmy(projectRoot) {
         if (!Array.isArray(rec.conflicts)) {
             errors.push("reconciliation.conflicts must be an array.");
         }
+        else {
+            rec.conflicts.forEach((c, ci) => {
+                if (c === null || typeof c !== "object" || Array.isArray(c)) {
+                    errors.push(`reconciliation.conflicts[${ci}] must be an object.`);
+                    return;
+                }
+                const co = c;
+                if (!isNonEmptyString(co.findingId)) {
+                    errors.push(`reconciliation.conflicts[${ci}].findingId must be a non-empty string.`);
+                }
+                else if (!findingIds.has(co.findingId)) {
+                    errors.push(`reconciliation.conflicts[${ci}].findingId references unknown finding "${co.findingId}".`);
+                }
+                if (!isNonEmptyString(co.description)) {
+                    errors.push(`reconciliation.conflicts[${ci}].description must be a non-empty string.`);
+                }
+            });
+        }
         if (!isStringArray(rec.multiSpecialistConfirmed)) {
             errors.push("reconciliation.multiSpecialistConfirmed must be an array of finding ids.");
         }
+        else {
+            for (const msId of rec.multiSpecialistConfirmed) {
+                if (!findingIds.has(msId)) {
+                    errors.push(`reconciliation.multiSpecialistConfirmed references unknown finding id "${msId}".`);
+                }
+            }
+        }
         if (!isStringArray(rec.shipBlockers)) {
             errors.push("reconciliation.shipBlockers must be an array of finding ids.");
         }

package/dist/content/contracts.js

@@ -11,6 +11,12 @@ export function commandContract(stage) {
     const gateIds = schema.requiredGates
         .map((g) => `\`${g.id}\``)
         .join(", ");
+    const writes = schema.crossStageTrace.writesTo;
+    const writesLine = writes.map((w) => `\`${w}\``).join(", ");
+    const primaryArtifact = `.cclaw/artifacts/${schema.artifactFile}`;
+    const writeStepPaths = writes.length > 1
+        ? writes.map((w) => `\`${w}\``).join(" and ")
+        : `\`${primaryArtifact}\``;
     return `# /cc-${stage}
 
 Load and follow **${skillPath}** — it contains the full checklist, examples, interaction protocol, and verification discipline.
@@ -20,7 +26,7 @@ ${schema.hardGate}
 
 ## In / Out
 - **Reads:** ${readsLine}
-- **Writes:** \`.cclaw/artifacts/${schema.artifactFile}\`
+- **Writes:** ${writesLine}
 - **Next:** \`/cc-next\` (updates flow-state and loads the next stage)
 
 ## Context Hydration (mandatory before stage work)
@@ -29,7 +35,7 @@ ${schema.hardGate}
 3. Load required upstream artifacts for this stage:
 ${hydrationLines}
 4. Load \`.cclaw/knowledge.md\` and apply relevant entries.
-5. Write stage output to \`.cclaw/artifacts/${schema.artifactFile}\`.
+5. Write stage output to ${writeStepPaths}.
 6. Do NOT copy artifacts into \`.cclaw/runs/\`; archival is handled only by \`cclaw archive\`.
 
 ## Gates

package/dist/content/examples.js

@@ -360,61 +360,77 @@ Execution rule: complete and verify each wave before starting the next wave.
 
 - Plan task IDs: T-1, T-2, T-3
 - Spec criterion IDs: AC-1, AC-2, AC-3`,
-    review: `### Layer 1 — Spec compliance (per-criterion)
+    review: `### Layer 1 Verdict
 
-| Criterion | Status | Evidence |
+| Criterion | Verdict | Evidence |
 | --- | --- | --- |
-| Delivery within 5s without reload | PASS | \`notification-feed.e2e.ts:44-88\` asserts SSE-to-UI timing under mock clock |
-| Dedupe: one visible item per key | PARTIAL | Unit tests cover publisher dedupe; UI merge path lacks test for race reordering (\`feedStore.test.ts\` missing case) |
-| Degraded mode + REST snapshot | PASS | \`NotificationsPanel.tsx:112-140\` renders banner + calls snapshot endpoint |
+| AC-1: Delivery within 5s without reload | PASS | \`notification-feed.e2e.ts:44-88\` asserts SSE-to-UI timing under mock clock |
+| AC-2: Dedupe — one visible item per key | PARTIAL | Unit tests cover publisher dedupe; UI merge path lacks test for race reordering (\`feedStore.test.ts\` missing case) |
+| AC-3: Degraded mode + REST snapshot | PASS | \`NotificationsPanel.tsx:112-140\` renders banner + calls snapshot endpoint |
 
-### Layer 2 — Engineering finding (sample)
+### Layer 2 Findings
 
-- **Severity:** Major
-- **Description:** Snapshot endpoint returns newest N rows but does not guarantee consistency with stream cursor, so users can miss items that arrived between snapshot and subscribe.
-- **File:line:** \`server/routes/notifications.ts:208\`
-- **Recommendation:** Return a monotonic cursor with snapshot and initialize SSE from that cursor; add contract tests for gapless delivery.
-- **Resolution options:**
-  1. Add cursor field + server-side reconciliation on subscribe (preferred).
-  2. Client-side “fetch since last seen id” merge pass (more complex, easier to get wrong).
-  3. Temporary mitigation: widen polling window when SSE is unhealthy (acceptable only as a short-term bridge).
+| ID | Severity | Category | Description | Status |
+| --- | --- | --- | --- | --- |
+| R-1 | Critical | correctness | Snapshot endpoint returns newest N rows but does not guarantee consistency with stream cursor — users can miss items between snapshot and subscribe. | open |
+| R-2 | Important | performance | \`feedStore.merge()\` does full-array scan on every SSE event; O(n) per event where n is feed length. | open |
+| R-3 | Suggestion | architecture | SSE reconnect logic duplicated across \`useNotifications\` and \`usePresence\`; extract shared hook. | open |
+
+### Review Army Contract
+
+- See \`07-review-army.json\`
+- Reconciliation summary: 1 duplicate collapsed (R-1 reported by spec-reviewer and code-reviewer), 0 conflicts
+
+### Review Readiness Dashboard
+
+- Layer 1 complete: yes (3/3 criteria)
+- Layer 2 complete: yes (5 sections reviewed)
+- Review army schema valid: yes
+- Open critical blockers: 1 (R-1)
+- Ship recommendation: BLOCKED until R-1 resolved
 
-### Layer 0 — hygiene checks (sample)
+### Severity Summary
 
-- **Dependency freshness:** no critical CVEs in direct server dependencies (scanner report linked in PR).
-- **Secrets:** no new env vars committed; rotation playbook unchanged.
+- Critical: 1
+- Important: 1
+- Suggestion: 1
 
-### Exit criteria (sample)
+### Final Verdict
 
-- All **Major** findings resolved or explicitly accepted with a time-bounded follow-up ticket.
-- **PARTIAL** spec compliance items have a named owner and a test plan before ship.`,
-    ship: `### Preflight checklist (sample)
+- BLOCKED`,
+    ship: `### Preflight Results
 
-- tests ✅ (\`pnpm test\` green on main)
-- build ✅ (\`pnpm build\` succeeds)
-- lint ✅ (\`pnpm lint\` clean)
-- type-check ✅ (\`pnpm typecheck\` clean)
+- Review verdict: APPROVED_WITH_CONCERNS (R-1 resolved, R-2 accepted as known debt)
+- Build: pass (\`pnpm build\` succeeds)
+- Tests: pass (\`pnpm vitest run && pnpm playwright test\` — 47 passed, 0 failed)
+- Lint: pass (\`pnpm lint\` clean)
+- Type-check: pass (\`pnpm typecheck\` clean)
+- Working tree clean: yes (\`git status\` shows no uncommitted changes)
 
-### Release notes (sample)
+### Release Notes
 
-- **Added:** In-app notification feed with SSE updates and REST fallback snapshotting.
-- **Changed:** Notification payloads now include a stable dedupe key for idempotent rendering.
+- **Added:** In-app notification feed with SSE updates and REST fallback snapshotting (AC-1, AC-3).
+- **Changed:** Notification payloads now include a stable dedupe key for idempotent rendering (AC-2).
 - **Fixed:** Panel no longer drops the newest item when reconnecting after sleep/resume.
+- **Breaking changes:** None.
 
-### Rollback plan (sample)
+### Rollback Plan
 
-1. Revert release tag \`v1.14.0\` to \`v1.13.2\` and redeploy the previous container image from the registry.
-2. If database migrations shipped, run the documented down migration \`2026_04_12_notifications_cursor_down.sql\` before serving traffic again.
+- Trigger conditions: error rate on \`/notifications/stream\` exceeds 5% for >5 minutes, or p95 publish-to-visible lag exceeds 10s.
+- Rollback steps: \`git revert <merge-sha> && git push origin main\` then redeploy; if DB migrations shipped, run \`2026_04_12_notifications_cursor_down.sql\` before traffic.
+- Verification steps: confirm error rate returns to pre-release baseline within 10 minutes; smoke-test feed panel manually.
 
-### Post-release monitoring (sample)
+### Monitoring
 
-- Watch error rate on \`/notifications/stream\` and snapshot endpoint separately for 24 hours.
-- Track p95 “publish → visible” lag via existing metrics dashboard; alert if SLO regresses.
+- Metrics/logs to watch: error rate on \`/notifications/stream\` and snapshot endpoint for 24h; p95 publish-to-visible lag via metrics dashboard.
+- Risk note (if no monitoring): N/A — monitoring is in place.
 
-### Communications (sample)
+### Finalization
 
-- Post a short internal changelog entry linking to release notes and rollback doc location.
-- If user-visible behavior changes, prepare a one-paragraph support macro explaining the new feed + fallback behavior.`,
+- Selected enum: FINALIZE_OPEN_PR
+- Selected label: B
+- Execution result: PR #42 created via \`gh pr create\`; CI passed; squash-merged to main.
+- PR URL: https://github.com/example/repo/pull/42`,
 };
 export function stageExamples(stage) {
     const examples = STAGE_EXAMPLES[stage];

package/dist/content/stage-schema.js

@@ -1016,7 +1016,8 @@ const TDD = {
         { claim: "One broad integration test is enough.", reality: "Slice-level RED tests are required for precise failure signal." },
         { claim: "Refactor can be skipped for speed.", reality: "Skipping refactor accumulates debt and weakens maintainability." },
         { claim: "Only changed tests need to pass.", reality: "Full-suite checks are needed to detect regressions." },
-        { claim: "Traceability is implied by commit diff.", reality: "Explicit mapping avoids ambiguity in review and rollback." }
+        { claim: "Traceability is implied by commit diff.", reality: "Explicit mapping avoids ambiguity in review and rollback." },
+        { claim: "Tests written after implementation achieve the same goals.", reality: "Post-hoc tests confirm assumptions, not behavior. They test what you built, not what you should have built. TDD forces you to think about behavior before you have an implementation to be anchored by." }
     ],
     redFlags: [
         "No failing test output (RED missing)",
@@ -1035,7 +1036,8 @@ const TDD = {
         { name: "Minimal Viable Change", description: "The best implementation is the smallest one that passes all RED tests. Every extra line is risk. Resist the urge to 'improve while you are here.'" },
         { name: "Regression Paranoia", description: "Assume every change breaks something until the full suite proves otherwise. Partial test runs are lies of omission." },
         { name: "Refactor-as-Hygiene", description: "Refactoring is not optional cleanup — it is the third leg of TDD. GREEN without REFACTOR accumulates mess. REFACTOR without GREEN breaks things." },
-        { name: "Evidence Over Anecdote", description: "Every claim about test state must be backed by captured output. 'It passed' without terminal evidence is not evidence. 'I saw it fail' without the failure output is not RED. Capture commands, outputs, and results — not summaries from memory." }
+        { name: "Evidence Over Anecdote", description: "Every claim about test state must be backed by captured output. 'It passed' without terminal evidence is not evidence. 'I saw it fail' without the failure output is not RED. Capture commands, outputs, and results — not summaries from memory." },
+        { name: "Characterization First", description: "Before changing existing behavior, write characterization tests that capture current behavior as-is. These tests document what the system does today — even if that behavior is wrong. Only after the characterization suite is green do you add the new RED test for the desired change. This prevents accidental behavior destruction during refactoring." }
     ],
     reviewSections: [
         {
@@ -1144,7 +1146,8 @@ const REVIEW = {
         { id: "review_layer2_performance", description: "Performance review completed." },
         { id: "review_layer2_architecture", description: "Architecture fit review completed." },
         { id: "review_severity_classified", description: "All findings are severity-tagged." },
-        { id: "review_criticals_resolved", description: "No unresolved critical blockers remain." }
+        { id: "review_criticals_resolved", description: "No unresolved critical blockers remain." },
+        { id: "review_army_json_valid", description: "07-review-army.json passes schema validation (validateReviewArmy)." }
     ],
     requiredEvidence: [
         "Artifact written to `.cclaw/artifacts/07-review.md`.",
@@ -1179,7 +1182,9 @@ const REVIEW = {
         { claim: "Passing tests mean spec compliance by default.", reality: "Tests can miss requirement mismatches; explicit spec review is mandatory." },
         { claim: "Severity labels are unnecessary.", reality: "Without severity, release decisions become inconsistent." },
         { claim: "Critical issues can be fixed after ship.", reality: "Critical blockers must be resolved before release handoff." },
-        { claim: "Security review is not needed for internal tools.", reality: "Internal tools become external surface area. Security is always in scope." }
+        { claim: "Security review is not needed for internal tools.", reality: "Internal tools become external surface area. Security is always in scope." },
+        { claim: "A quick skim is sufficient for small diffs.", reality: "Small diffs hide high-impact changes. A 3-line auth bypass is still critical. Every diff gets layered review regardless of size." },
+        { claim: "The author already reviewed their own code.", reality: "Self-review misses blind spots by definition. Independent review exists precisely because authors cannot objectively evaluate their own assumptions." }
     ],
     redFlags: [
         "No separate Layer 1/Layer 2 outcomes",
@@ -1276,7 +1281,7 @@ const REVIEW = {
     completionStatus: ["APPROVED", "APPROVED_WITH_CONCERNS", "BLOCKED"],
     crossStageTrace: {
         readsFrom: [".cclaw/artifacts/06-tdd.md", ".cclaw/artifacts/04-spec.md", ".cclaw/artifacts/05-plan.md"],
-        writesTo: [".cclaw/artifacts/07-review.md"],
+        writesTo: [".cclaw/artifacts/07-review.md", ".cclaw/artifacts/07-review-army.json"],
         traceabilityRule: "Review verdict must reference specific spec criteria and TDD evidence. Downstream ship stage must reference review verdict."
     },
     artifactValidation: [
@@ -1284,7 +1289,7 @@ const REVIEW = {
         { section: "Layer 2 Findings", required: true, validationRule: "Each finding has severity, description, and resolution status." },
         { section: "Review Army Contract", required: true, validationRule: "Structured findings include id/severity/confidence/fingerprint/reportedBy/status with dedup reconciliation summary." },
         { section: "Review Readiness Dashboard", required: true, validationRule: "At least 4 readiness checklist lines including blocker and recommendation status." },
-        { section: "Severity Summary", required: true, validationRule: "Counts: N critical, N important, N suggestion." },
+        { section: "Severity Summary", required: true, validationRule: "Per-severity count lines for critical, important, and suggestion buckets." },
         { section: "Final Verdict", required: true, validationRule: "Exactly one of: APPROVED, APPROVED_WITH_CONCERNS, BLOCKED." }
     ],
     namedAntiPattern: {
@@ -1345,7 +1350,8 @@ const SHIP = {
         { id: "ship_release_notes_written", description: "Release notes are complete and accurate." },
         { id: "ship_rollback_plan_ready", description: "Rollback trigger, steps, and verification are documented." },
         { id: "ship_finalization_mode_selected", description: "Exactly one finalization action is selected." },
-        { id: "ship_finalization_executed", description: "Selected finalization action was executed and verified." }
+        { id: "ship_finalization_executed", description: "Selected finalization action was executed and verified." },
+        { id: "ship_post_merge_tests", description: "Full test suite re-run on the merged result (not just the branch). Post-merge failures caught before release." }
     ],
     requiredEvidence: [
         "Artifact written to `.cclaw/artifacts/08-ship.md`.",
@@ -1378,7 +1384,10 @@ const SHIP = {
     rationalizations: [
         { claim: "Rollback details can be written after release.", reality: "Rollback is part of release readiness, not post-release cleanup." },
         { claim: "Finalization choice is obvious from context.", reality: "Explicit branch action prevents accidental release state." },
-        { claim: "Urgent fixes can skip preflight.", reality: "Urgency increases risk; preflight discipline matters more, not less." }
+        { claim: "Urgent fixes can skip preflight.", reality: "Urgency increases risk; preflight discipline matters more, not less." },
+        { claim: "Monitoring can be set up after deploy.", reality: "If you cannot observe the release, you cannot detect failure. Monitoring is a ship prerequisite, not a follow-up task." },
+        { claim: "A small merge does not need post-merge testing.", reality: "Small merges on diverged bases cause silent conflicts. Post-merge suite runs catch what branch-only CI misses." },
+        { claim: "Release notes are internal documentation, not a ship gate.", reality: "Release notes are the rollback decision input. Without them, the team cannot assess what changed or why a rollback is needed." }
     ],
     redFlags: [
         "No rollback trigger/steps",
@@ -1403,7 +1412,8 @@ const SHIP = {
         { name: "Rollback-First Thinking", description: "Before shipping, answer: what tells me this is broken? How do I undo it? How do I verify the undo worked? If you cannot answer all three, you are not ready." },
         { name: "Explicit Over Implicit Finalization", description: "Merge, PR, keep, discard — each has different consequences. Pick one. Say it out loud. Write it down. Never let finalization be 'whatever the default is.'" },
         { name: "Post-Merge Paranoia", description: "The merge itself can introduce failures even when both branches pass independently. Always run the full suite AFTER merge, not just before." },
-        { name: "Observability Before Ship", description: "If you cannot monitor the change in production, you cannot know if it is broken. Monitoring/logging is a ship prerequisite, not a follow-up." }
+        { name: "Observability Before Ship", description: "If you cannot monitor the change in production, you cannot know if it is broken. Monitoring/logging is a ship prerequisite, not a follow-up." },
+        { name: "Release Blast Radius", description: "Before shipping, map the blast radius: how many users are affected if this breaks? Is it one endpoint or the entire app? Scale rollback urgency and monitoring to the blast radius, not the diff size. A 3-line auth change can have infinite blast radius." }
     ],
     reviewSections: [
         {
@@ -1430,17 +1440,22 @@ const SHIP = {
     ],
     completionStatus: ["SHIPPED", "SHIPPED_WITH_EXCEPTIONS", "BLOCKED"],
     crossStageTrace: {
-        readsFrom: [".cclaw/artifacts/07-review.md", ".cclaw/artifacts/06-tdd.md"],
+        readsFrom: [".cclaw/artifacts/07-review.md", ".cclaw/artifacts/06-tdd.md", ".cclaw/artifacts/05-plan.md", ".cclaw/artifacts/04-spec.md"],
         writesTo: [".cclaw/artifacts/08-ship.md"],
-        traceabilityRule: "Ship artifact must reference review verdict and resolution status. Rollback plan must reference specific changes that could fail."
+        traceabilityRule: "Ship artifact must reference review verdict and resolution status. Release notes must reference spec criteria. Rollback plan must reference specific changes that could fail."
     },
     artifactValidation: [
         { section: "Preflight Results", required: true, validationRule: "Build, test, lint, type-check results captured with fresh output. Exceptions documented if any." },
         { section: "Release Notes", required: true, validationRule: "What changed, why, impact. References spec criteria. Breaking changes flagged." },
         { section: "Rollback Plan", required: true, validationRule: "Trigger conditions, rollback steps (exact commands), verification steps." },
         { section: "Monitoring", required: false, validationRule: "If applicable: what metrics/logs to watch post-deploy. Risk note if no monitoring." },
-        { section: "Finalization", required: true, validationRule: "Exactly one finalization enum token selected. Execution result documented. Worktree cleaned if applicable." }
-    ]
+        { section: "Finalization", required: true, validationRule: "Exactly one finalization enum token selected. Execution result documented. Worktree cleaned if applicable." },
+        { section: "Completion Status", required: false, validationRule: "If present: exactly one of SHIPPED, SHIPPED_WITH_EXCEPTIONS, BLOCKED. Exceptions documented when applicable." }
+    ],
+    namedAntiPattern: {
+        title: "Green CI Means Safe to Merge",
+        description: "CI passing on a feature branch does not prove the merged result is safe. Post-merge test failures are common when the base branch has diverged. Re-run the full suite on the merge result, not just the branch. A green branch badge is a necessary condition, not a sufficient one."
+    }
 };
 // ---------------------------------------------------------------------------
 // Stage map and accessors

package/dist/content/templates.js

@@ -375,8 +375,7 @@ Execution rule: complete and verify each wave before starting the next wave.
       "confidence": 7,
       "category": "correctness",
       "location": {
-        "file": "",
-        "line": 0
+        "file": ""
       },
       "fingerprint": "",
       "reportedBy": [],
@@ -423,6 +422,10 @@ Execution rule: complete and verify each wave before starting the next wave.
 - Selected label (A/B/C/D):
 - Execution result:
 - PR URL / merge commit / kept branch / discard confirmation:
+
+## Completion Status
+- SHIPPED | SHIPPED_WITH_EXCEPTIONS | BLOCKED
+- Exceptions (if any):
 `
 };
 export const RULEBOOK_MARKDOWN = `# Cclaw Rulebook

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cclaw-cli",
-  "version": "0.5.13",
+  "version": "0.5.15",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {