mandrel 2.0.0 → 2.2.0

package/.agents/scripts/update-ticket-state.js

@@ -8,15 +8,7 @@
 import { parseArgs } from 'node:util';
 import { resolveConfig } from './lib/config-resolver.js';
 import { Logger } from './lib/Logger.js';
-import {
-  enqueueLabel,
-  outboxPathFor,
-} from './lib/orchestration/bookkeeping-outbox.js';
-import {
-  cascadeCompletion,
-  STATE_LABELS,
-  transitionTicketState,
-} from './lib/orchestration/ticketing.js';
+import { transitionTicketState } from './lib/orchestration/ticketing.js';
 import { createProvider } from './lib/provider-factory.js';
 
 // ── CLI Main Block ────────────────────────────────────────────────────────
@@ -31,8 +23,6 @@ if (
       ticket: { type: 'string' },
       state: { type: 'string' },
       'remove-label': { type: 'string' },
-      buffer: { type: 'boolean' },
-      epic: { type: 'string' },
     },
     strict: false,
   });
@@ -66,50 +56,18 @@ if (
       return;
     }
 
-    // Headless buffering (Epic #4476 M5): buffer an intermediate state flip to
-    // the per-Epic outbox instead of a live GitHub round-trip; finalize's
-    // bookkeeping-reconcile.js drains it once. `agent::blocked` (the HITL gate,
-    // §1.J) and `agent::done` (its cascade must run live) ALWAYS surface
-    // immediately and are never buffered. Requires --epic to locate the outbox.
-    if (
-      values.buffer &&
-      state !== STATE_LABELS.BLOCKED &&
-      state !== STATE_LABELS.DONE
-    ) {
-      const epicId = Number.parseInt(values.epic ?? '', 10);
-      if (!Number.isInteger(epicId) || epicId <= 0) {
-        throw new Error('--buffer requires --epic <id>');
-      }
-      enqueueLabel({
-        outboxPath: outboxPathFor(epicId, config),
-        ticketId,
-        state,
-      });
-      Logger.info(
-        `[State-Sync] Buffered #${ticketId} → ${state} (headless; drained at finalize)`,
-      );
-      return;
-    }
-
     Logger.info(
       `[State-Sync] Transitioning ticket #${ticketId} to ${state}...`,
     );
+    // Story #4545 — no second cascade here. `transitionTicketState` already
+    // fires the upward cascade on every transition (bulk.js registers
+    // `cascadeParentState` as transition.js's cascade runner, and the DONE
+    // branch delegates to `cascadeCompletion`), so the explicit call this
+    // used to make re-walked the same parents and re-spent the same API
+    // calls a second time on every done transition — under a Story-only
+    // model where no orchestration parent exists to find.
     await transitionTicketState(provider, ticketId, state);
 
-    if (state === STATE_LABELS.DONE) {
-      Logger.info(`[State-Sync] Cascading completion from #${ticketId}...`);
-      const cascade = await cascadeCompletion(provider, ticketId);
-      // Hoisted out of the `for...of` initializer because typhonjs-escomplex
-      // mis-parses optional chaining there (it would zero out this file's
-      // maintainability score).
-      const cascadeFailures = cascade?.failed ?? [];
-      for (const { parentId, error } of cascadeFailures) {
-        Logger.warn(
-          `[State-Sync] ⚠️  Cascade partial-failure on parent #${parentId}: ${error}`,
-        );
-      }
-    }
-
     // Optional secondary label removal alongside the state transition
     // (e.g. clear `status::blocked` when transitioning back to ready).
     if (removeLabel) {

package/.agents/skills/core/code-review-and-quality/SKILL.md

@@ -25,453 +25,31 @@ description:
 - **Refactoring is post-green and behaviour-preserving.** Run the refactor pass only when the suite is already green and gates pass; inputs, outputs, side effects, error semantics, and ordering MUST be identical before and after, and existing tests MUST keep passing **without modification** (if a test had to change, behaviour changed — revert).
 - **Lower CRAP by lowering complexity, and remove duplication at the root.** Target the highest-CRAP well-covered functions and the largest verbatim duplications by measurement (`check-baselines.js`), not by smell; extract one well-named helper rather than leaving near-copies. CRAP must not rise and maintainability must not fall on any touched file, and no gate, floor, or threshold may be retuned to make the pass "succeed".
 
-## Overview
-
-Multi-dimensional code review with quality gates. Every change gets reviewed
-before merge — no exceptions. Review covers five axes: correctness, readability,
-architecture, security, and performance.
-
-**The approval standard:** Approve a change when it definitely improves overall
-code health, even if it isn't perfect. Perfect code doesn't exist — the goal is
-continuous improvement. Don't block a change because it isn't exactly how you
-would have written it. If it improves the codebase and follows the project's
-conventions, approve it.
-
-## When to Use
-
-- Before merging any PR or change
-- After completing a feature implementation
-- When another agent or model produced code you need to evaluate
-- When refactoring existing code
-- After any bug fix (review both the fix and the regression test)
-
-## The Five-Axis Review
-
-Every review evaluates code across these dimensions:
-
-### 1. Correctness
-
-Does the code do what it claims to do?
-
-- Does it match the spec or task requirements?
-- Are edge cases handled (null, empty, boundary values)?
-- Are error paths handled (not just the happy path)?
-- Does it pass all tests? Are the tests actually testing the right things?
-- Are there off-by-one errors, race conditions, or state inconsistencies?
-
-### 2. Readability & Simplicity
-
-Can another engineer (or agent) understand this code without the author
-explaining it?
-
-- Are names descriptive and consistent with project conventions? (No `temp`,
-  `data`, `result` without context)
-- Is the control flow straightforward (avoid nested ternaries, deep callbacks)?
-- Is the code organized logically (related code grouped, clear module
-  boundaries)?
-- Are there any "clever" tricks that should be simplified?
-- **Could this be done in fewer lines?** (1000 lines where 100 suffice is a
-  failure)
-- **Are abstractions earning their complexity?** (Don't generalize until the
-  third use case)
-- Would comments help clarify non-obvious intent? (But don't comment obvious
-  code.)
-- Are there dead code artifacts: no-op variables (`_unused`), backwards-compat
-  shims, or `// removed` comments?
-
-### 3. Architecture
-
-Does the change fit the system's design?
-
-- Does it follow existing patterns or introduce a new one? If new, is it
-  justified?
-- Does it maintain clean module boundaries?
-- Is there code duplication that should be shared?
-- Are dependencies flowing in the right direction (no circular dependencies)?
-- Is the abstraction level appropriate (not over-engineered, not too coupled)?
-
-### 4. Security
-
-For detailed security guidance, see `security-and-hardening`. Does the change
-introduce vulnerabilities?
-
-- Is user input validated and sanitized?
-- Are secrets kept out of code, logs, and version control?
-- Is authentication/authorization checked where needed?
-- Are SQL queries parameterized (no string concatenation)?
-- Are outputs encoded to prevent XSS?
-- Are dependencies from trusted sources with no known vulnerabilities?
-- Is data from external sources (APIs, logs, user content, config files) treated
-  as untrusted?
-- Are external data flows validated at system boundaries before use in logic or
-  rendering?
-
-### 5. Performance
-
-Measure before optimizing, and only on the hot path. Does the change introduce
-performance problems?
-
-- Any N+1 query patterns?
-- Any unbounded loops or unconstrained data fetching?
-- Any synchronous operations that should be async?
-- Any unnecessary re-renders in UI components?
-- Any missing pagination on list endpoints?
-- Any large objects created in hot paths?
-
-## Change Sizing
-
-Small, focused changes are easier to review, faster to merge, and safer to
-deploy. Target these sizes:
-
-```text
-~100 lines changed   → Good. Reviewable in one sitting.
-~300 lines changed   → Acceptable if it's a single logical change.
-~1000 lines changed  → Too large. Split it.
-```
-
-**What counts as "one change":** A single self-contained modification that
-addresses one thing, includes related tests, and keeps the system functional
-after submission. One part of a feature — not the whole feature.
-
-**Splitting strategies when a change is too large:**
-
-| Strategy          | How                                                     | When                    |
-| ----------------- | ------------------------------------------------------- | ----------------------- |
-| **Stack**         | Submit a small change, start the next one based on it   | Sequential dependencies |
-| **By file group** | Separate changes for groups needing different reviewers | Cross-cutting concerns  |
-| **Horizontal**    | Create shared code/stubs first, then consumers          | Layered architecture    |
-| **Vertical**      | Break into smaller full-stack slices of the feature     | Feature work            |
-
-**When large changes are acceptable:** Complete file deletions and automated
-refactoring where the reviewer only needs to verify intent, not every line.
-
-**Separate refactoring from feature work.** A change that refactors existing
-code and adds new behavior is two changes — submit them separately. Small
-cleanups (variable renaming) can be included at reviewer discretion.
-
-## Change Descriptions
-
-Every change needs a description that stands alone in version control history.
-
-**First line:** Short, imperative, standalone. "Delete the FizzBuzz RPC" not
-"Deleting the FizzBuzz RPC." Must be informative enough that someone searching
-history can understand the change without reading the diff.
-
-**Body:** What is changing and why. Include context, decisions, and reasoning
-not visible in the code itself. Link to bug numbers, benchmark results, or
-design docs where relevant. Acknowledge approach shortcomings when they exist.
-
-**Anti-patterns:** "Fix bug," "Fix build," "Add patch," "Moving code from A to
-B," "Phase 1," "Add convenience functions."
-
-## Review Process
-
-### Step 1: Understand the Context
-
-Before looking at code, understand the intent:
-
-```text
-- What is this change trying to accomplish?
-- What spec or task does it implement?
-- What is the expected behavior change?
-```
-
-### Step 2: Review the Tests First
-
-Tests reveal intent and coverage:
-
-```text
-- Do tests exist for the change?
-- Do they test behavior (not implementation details)?
-- Are edge cases covered?
-- Do tests have descriptive names?
-- Would the tests catch a regression if the code changed?
-```
-
-### Step 3: Review the Implementation
-
-Walk through the code with the five axes in mind:
-
-```text
-For each file changed:
-1. Correctness: Does this code do what the test says it should?
-2. Readability: Can I understand this without help?
-3. Architecture: Does this fit the system?
-4. Security: Any vulnerabilities?
-5. Performance: Any bottlenecks?
-```
-
-### Step 4: Categorize Findings
-
-Label every comment with its severity so the author knows what's required vs
-optional:
-
-| Prefix                        | Meaning            | Author Action                                           |
-| ----------------------------- | ------------------ | ------------------------------------------------------- |
-| _(no prefix)_                 | Required change    | Must address before merge                               |
-| **Critical:**                 | Blocks merge       | Security vulnerability, data loss, broken functionality |
-| **Nit:**                      | Minor, optional    | Author may ignore — formatting, style preferences       |
-| **Optional:** / **Consider:** | Suggestion         | Worth considering but not required                      |
-| **FYI**                       | Informational only | No action needed — context for future reference         |
-
-This prevents authors from treating all feedback as mandatory and wasting time
-on optional suggestions.
-
-### Step 5: Verify the Verification
-
-Check the author's verification story:
-
-```text
-- What tests were run?
-- Did the build pass?
-- Was the change tested manually?
-- Are there screenshots for UI changes?
-- Is there a before/after comparison?
-```
-
-## Multi-Model Review Pattern
-
-Use different models for different review perspectives:
-
-```text
-Model A writes the code
-    │
-    ▼
-Model B reviews for correctness and architecture
-    │
-    ▼
-Model A addresses the feedback
-    │
-    ▼
-Human makes the final call
-```
-
-This catches issues that a single model might miss — different models have
-different blind spots.
-
-**Example prompt for a review agent:**
-
-```text
-Review this code change for correctness, security, and adherence to
-our project conventions. The spec says [X]. The change should [Y].
-Flag any issues as Critical, Important, or Suggestion.
-```
-
-## Dead Code Hygiene
-
-After any refactoring or implementation change, check for orphaned code:
-
-1. Identify code that is now unreachable or unused
-2. List it explicitly
-3. **Ask before deleting:** "Should I remove these now-unused elements: [list]?"
-
-Don't leave dead code lying around — it confuses future readers and agents. But
-don't silently delete things you're not sure about. When in doubt, ask.
-
-```text
-DEAD CODE IDENTIFIED:
-- formatLegacyDate() in src/utils/date.ts — replaced by formatDate()
-- OldTaskCard component in src/components/ — replaced by TaskCard
-- LEGACY_API_URL constant in src/config.ts — no remaining references
-→ Safe to remove these?
-```
-
-## Review Speed
-
-Slow reviews block entire teams. The cost of context-switching to review is less
-than the waiting cost imposed on others.
-
-- **Respond within one business day** — this is the maximum, not the target
-- **Ideal cadence:** Respond shortly after a review request arrives, unless deep
-  in focused coding. A typical change should complete multiple review rounds in
-  a single day
-- **Prioritize fast individual responses** over quick final approval. Quick
-  feedback reduces frustration even if multiple rounds are needed
-- **Large changes:** Ask the author to split them rather than reviewing one
-  massive changeset
-
-## Handling Disagreements
-
-When resolving review disputes, apply this hierarchy:
-
-1. **Technical facts and data** override opinions and preferences
-2. **Style guides** are the absolute authority on style matters
-3. **Software design** must be evaluated on engineering principles, not personal
-   preference
-4. **Codebase consistency** is acceptable if it doesn't degrade overall health
-
-**Don't accept "I'll clean it up later."** Experience shows deferred cleanup
-rarely happens. Require cleanup before submission unless it's a genuine
-emergency. If surrounding issues can't be addressed in this change, require
-filing a bug with self-assignment.
-
-## Honesty in Review
-
-When reviewing code — whether written by you, another agent, or a human:
-
-- **Don't rubber-stamp.** "LGTM" without evidence of review helps no one.
-- **Don't soften real issues.** "This might be a minor concern" when it's a bug
-  that will hit production is dishonest.
-- **Quantify problems when possible.** "This N+1 query will add ~50ms per item
-  in the list" is better than "this could be slow."
-- **Push back on approaches with clear problems.** Sycophancy is a failure mode
-  in reviews. If the implementation has issues, say so directly and propose
-  alternatives.
-- **Accept override gracefully.** If the author has full context and disagrees,
-  defer to their judgment. Comment on code, not people — reframe personal
-  critiques to focus on the code itself.
-
-## Dependency Discipline
-
-Part of code review is dependency review:
-
-**Before adding any dependency:**
-
-1. Does the existing stack solve this? (Often it does.)
-2. How large is the dependency? (Check bundle impact.)
-3. Is it actively maintained? (Check last commit, open issues.)
-4. Does it have known vulnerabilities? (`npm audit`)
-5. What's the license? (Must be compatible with the project.)
-
-**Rule:** Prefer standard library and existing utilities over new dependencies.
-Every dependency is a liability.
-
-## The Review Checklist
-
-```markdown
-## Review: [PR/Change title]
-
-### Context
-
-- [ ] I understand what this change does and why
-
-### Correctness
-
-- [ ] Change matches spec/task requirements
-- [ ] Edge cases handled
-- [ ] Error paths handled
-- [ ] Tests cover the change adequately
-
-### Readability
-
-- [ ] Names are clear and consistent
-- [ ] Logic is straightforward
-- [ ] No unnecessary complexity
-
-### Architecture
-
-- [ ] Follows existing patterns
-- [ ] No unnecessary coupling or dependencies
-- [ ] Appropriate abstraction level
-
-### Security
-
-- [ ] No secrets in code
-- [ ] Input validated at boundaries
-- [ ] No injection vulnerabilities
-- [ ] Auth checks in place
-- [ ] External data sources treated as untrusted
-
-### Performance
-
-- [ ] No N+1 patterns
-- [ ] No unbounded operations
-- [ ] Pagination on list endpoints
-
-### Verification
-
-- [ ] Tests pass
-- [ ] Build succeeds
-- [ ] Manual verification done (if applicable)
-
-### Verdict
-
-- [ ] **Approve** — Ready to merge
-- [ ] **Request changes** — Issues must be addressed
-```
-
-## Common Rationalizations
-
-| Rationalization                      | Reality                                                                                                                   |
-| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
-| "It works, that's good enough"       | Working code that's unreadable, insecure, or architecturally wrong creates debt that compounds.                           |
-| "I wrote it, so I know it's correct" | Authors are blind to their own assumptions. Every change benefits from another set of eyes.                               |
-| "We'll clean it up later"            | Later never comes. The review is the quality gate — use it. Require cleanup before merge, not after.                      |
-| "AI-generated code is probably fine" | AI code needs more scrutiny, not less. It's confident and plausible, even when wrong.                                     |
-| "The tests pass, so it's good"       | Tests are necessary but not sufficient. They don't catch architecture problems, security issues, or readability concerns. |
-
-## Red Flags
-
-- PRs merged without any review
-- Review that only checks if tests pass (ignoring other axes)
-- "LGTM" without evidence of actual review
-- Security-sensitive changes without security-focused review
-- Large PRs that are "too big to review properly" (split them)
-- No regression tests with bug fix PRs
-- Review comments without severity labels — makes it unclear what's required vs
-  optional
-- Accepting "I'll fix it later" — it never happens
-
-## Post-Green Refactor Pass
-
-Review's sibling discipline is the **behaviour-preserving refactor** that drives
-CRAP (Change Risk Anti-Patterns) and duplication down _after_ the code is green
-— the pass wired in as the opt-in `delivery.refactorStage` checkpoint. It
-optimises for the measured CRAP and duplication axes the baselines ratchet, not
-for subjective readability, and it never runs from red.
-
-**When to run:** a baseline report flags a high-CRAP function that is already
-well-covered (so the lever is complexity, not coverage); the same logic is
-duplicated across two or more files and the copies are drifting; or the
-`delivery.refactorStage` checkpoint fires after gates pass and before a Story
-closes. **When NOT to:** before tests are green (write/fix tests first), or when
-a function's CRAP is high because it is _uncovered_ — that is a missing-test
-problem, so drive it with the TDD cycle in
-[`.agents/rules/testing-standards.md`](../../../rules/testing-standards.md).
-
-```text
-Confirm green + baseline  →  pick highest-CRAP / largest dup
-        ▲                                  │
-        │                                  ▼
-  re-run gates, confirm   ◄──  refactor   ◄──  comprehend the target
-  CRAP↓ / maint↑, tests pass   (one change)    (call sites + tests)
-```
-
-1. **Baseline.** Confirm green and capture current CRAP and maintainability
-   (`node .agents/scripts/check-baselines.js`) — your do-no-harm reference.
-2. **Target by measurement.** Pick the highest-CRAP well-covered function, or
-   the largest verbatim duplication. Work worst-first.
-3. **Comprehend before you touch (Chesterton's Fence).** Read the call sites and
-   the tests that pin the behaviour first; an "unnecessary" abstraction may
-   exist for testability or extensibility.
-4. **Refactor one step.** Extract a focused function, flatten nesting into guard
-   clauses, replace a nested ternary / boolean-flag param, or extract a single
-   shared helper for the duplication (dedup the _behaviour_, not just the text —
-   look-alike blocks that encode different responsibilities stay separate).
-5. **Verify.** Re-run the affected tests (unmodified) and the baselines. CRAP
-   must not rise, maintainability must not fall, tests must pass. If a test
-   needed editing, revert — behaviour changed.
-
-Keep each refactor an isolated, reviewable commit separate from feature or fix
-work, refactor only the targeted functions/duplications (no drive-by rewrites),
-and leave no dead code behind (unused imports, orphaned helpers).
-
-## Verification
-
-After review is complete:
-
-- [ ] All Critical issues are resolved
-- [ ] All Important issues are resolved or explicitly deferred with
-      justification
-- [ ] Tests pass
-- [ ] Build succeeds
-- [ ] The verification story is documented (what changed, how it was verified)
-
-After a post-green refactor pass:
-
-- [ ] The suite was green before and after, with **no test modifications**
-- [ ] CRAP did not rise and maintainability did not fall on any touched file
-      (baselines re-run and compared)
-- [ ] No gate, floor, or coverage threshold was loosened
-- [ ] Duplication was removed at the root (one helper), not just locally patched
-- [ ] Each refactor is an isolated commit, separate from feature or fix work
+## Long-form reference — read on demand
+
+The capsule above is the contract and the whole always-read surface of this
+skill. The long-form material behind it — patterns, worked examples,
+checklists, and rationalizations — lives in the on-demand sibling
+[`reference.md`](reference.md), matching the split the always-on rules already
+use ([`rules/git-conventions.md`](../../../rules/git-conventions.md) ⇄
+[`git-conventions-reference.md`](../../../rules/git-conventions-reference.md)).
+Activating this skill costs the capsule; open a section below only when the
+task actually engages it.
+
+- [Overview](reference.md#overview)
+- [When to Use](reference.md#when-to-use)
+- [The Five-Axis Review](reference.md#the-five-axis-review)
+- [Change Sizing](reference.md#change-sizing)
+- [Change Descriptions](reference.md#change-descriptions)
+- [Review Process](reference.md#review-process)
+- [Multi-Model Review Pattern](reference.md#multi-model-review-pattern)
+- [Dead Code Hygiene](reference.md#dead-code-hygiene)
+- [Review Speed](reference.md#review-speed)
+- [Handling Disagreements](reference.md#handling-disagreements)
+- [Honesty in Review](reference.md#honesty-in-review)
+- [Dependency Discipline](reference.md#dependency-discipline)
+- [The Review Checklist](reference.md#the-review-checklist)
+- [Common Rationalizations](reference.md#common-rationalizations)
+- [Red Flags](reference.md#red-flags)
+- [Post-Green Refactor Pass](reference.md#post-green-refactor-pass)
+- [Verification](reference.md#verification)