mandrel 1.94.0 → 2.1.0

package/.agents/skills/core/scope-triage/SKILL.md

@@ -1,189 +1,48 @@
 ---
 name: scope-triage
 description:
-  Judge whether a piece of planned work is epic-sized or story-sized before the
-  planning ceremony is paid for. Emits one of three verdicts —
-  `epic` | `story` | `borderline` — over any planning artifact (a one-pager, an
-  Epic body, or a Story draft). Use from `/plan` Phase 1.5 and any other
-  planning gate that needs the canonical story-vs-epic rubric.
+  Optional split-advisory for `/plan`. Under v2 there is no epic|story routing
+  verdict — `/plan` always authors Stories. Use this skill only when judging
+  whether a draft should stay one Story or legitimately split (near-zero
+  overlap or an architectural seam).
 ---
 
-# scope-triage
+# scope-triage (split advisory)
 
 ## Policy Capsule
 
-- Produce exactly one verdict — `epic` | `story` | `borderline` — for the
-  artifact under judgment. Never auto-route on the verdict; the verdict is
-  **advisory**, and the operator always decides what to do with it.
-- Anchor every sizing judgment to the existing sizing SSOT **by reference**:
-  `DELIVERABLE_GRANULARITY_GUIDANCE` and `DEFAULT_TASK_SIZING` in
+- There is **no** `epic | story | borderline` routing verdict in v2. `/plan`
+  is a single path that emits **one Story by default**.
+- This skill is an optional **split advisory**: should the author keep one
+  Story, or does the seed clear the default-single split policy?
+- Anchor sizing judgment to `DEFAULT_MODEL_CAPACITY` and
+  `DELIVERABLE_GRANULARITY_GUIDANCE` in
   [`ticket-validator-sizing.js`](../../../scripts/lib/orchestration/ticket-validator-sizing.js).
-  **Do not restate the numeric thresholds** — read them from that module so the
-  rubric cannot drift from the validator that enforces them.
-- The verdict is **host-LLM judgment**, not a deterministic score. There is no
-  `--flag`, no scorer, no schema, and no label transition behind this skill —
-  it is read-on-demand library content, evaluated with judgment per
-  [`.agents/instructions.md` § 1.B](../../../instructions.md).
-- Lead with **cohesion**, the same primary heuristic the sizing SSOT leads
-  with: one Story is *one coherent change with one reason to exist*. The file /
-  acceptance ceilings are the backstop, not the first cut.
-- Bias toward `epic` only when the work genuinely spans multiple independent
-  capabilities, crosses subsystems, or carries a real dependency graph. Being
-  wrong in the `epic` direction is cheap — the Phase 8.3 consolidation pass and
-  the sizing validator catch an over-planned Story later. Being wrong in the
-  `story` direction is expensive — a story-sized scope pushed through the full
-  Epic ceremony pays a sectioned-Epic-body (Tech Spec + Acceptance Table) +
-  Story backlog +
-  `epic/<id>` integration-branch tax for a degenerate one-Story output.
-- Keep the rubric prose **artifact-agnostic**. The thing under judgment may be a
-  sharpened one-pager, an existing Epic body, or a draft Story — the rubric
-  reads the same against all three so every consumer reuses it verbatim.
+  Do not restate numeric thresholds.
+- Lead with **cohesion**: one Story is one coherent change with one reason
+  to exist. Coupled work stays one Story and uses `## Slicing` for
+  intra-session checkpoints.
+- Emit an **advisory only** — `keep-single` (the default) or `split` with its
+  seam/overlap rationale. **Never auto-route**: the operator decides, and
+  `--yes` defaults to `keep-single`.
 
-## Verdicts
+## Split policy (when N>1 is allowed)
 
-The skill emits exactly one of three verdicts.
+Split into sibling Stories **only** when:
 
-### `story`
+1. **Near-zero overlap** — genuinely independent capabilities that happen to
+   share a seed idea, or
+2. **Architectural seam** — different deployables, or a migration vs the
+   feature that consumes it.
 
-The work is a single shippable capability. Signals:
+Otherwise keep one Story. Persist refuses coupled splits via
+`assertAcceptancePartition` (identical AC text across Stories).
 
-- **One capability, one reason to exist.** The artifact describes one coherent
-  change a reviewer would accept as a single PR — the
-  `DELIVERABLE_GRANULARITY_GUIDANCE.definition` notion of a Story.
-- **Acceptance fits one Story.** The acceptance-criteria list reads as the
-  binding contract of one coherent capability rather than spanning many
-  independent outcomes. Acceptance mass is advisory-only (the
-  `softAcceptanceCount` nudge in `DEFAULT_TASK_SIZING` — there is no hard
-  ceiling), so the question is cohesion, not count.
-- **Footprint fits Story sizing.** The plausible file footprint fits the Story
-  width described by `DEFAULT_TASK_SIZING` (the `softFiles` / `hardFiles`
-  knobs); a legitimately broad-but-cohesive change would declare `wide` rather
-  than being two Stories.
-- **No novel architecture, no high-risk trigger.** The work introduces no novel
-  architectural decision and matches none of the `planning.riskHeuristics` in
-  `.agentrc.json` (destructive/irreversible changes, shared auth/security,
-  CI/CD gate changes, monorepo-wide rewrites, destructive migrations).
-- **Decomposition would degenerate.** Running it through `/plan` would
-  plausibly yield exactly **one Feature with one Story** — the shape the Phase
-  8.3 consolidation skill flags only after all the spec authoring is already
-  sunk cost.
+## Advisory output
 
-### `epic`
+Emit one of:
 
-The work is genuinely Epic-sized. Signals (any one is sufficient):
+- `keep-single` — default; fold complexity into `## Spec` / `## Slicing`
+- `split` — list the proposed Stories and the seam/overlap rationale
 
-- **Multiple independent capabilities.** The artifact bundles two or more
-  capabilities that each stand alone as a unit of work.
-- **Cross-subsystem blast radius.** The change reaches across subsystems that
-  do not share one cohesive reason to exist.
-- **A real dependency graph.** The work has internal ordering — slices that
-  must land before others — rather than one atomic change.
-
-### `borderline`
-
-The work is genuinely on the line — it could reasonably be one ambitious Story
-or a small Epic, and neither call is clearly right. **Present the choice rather
-than deciding for the operator.** Do not force a verdict to avoid the third
-option; a borderline scope surfaced as borderline is the correct output.
-
-## Change-Request Triage Rubric
-
-A **change request** — "fix this", "tweak that", "extend the existing X" —
-is the common case this rubric routes cheaply: a delta against a surface the
-project already shipped, not a from-scratch capability. Route it to `story`
-by default when all three delta signals hold; treat any one signal's absence
-as a prompt to re-check, not an automatic `epic` bump.
-
-### Delta signals
-
-- **Delta to an already-delivered surface.** The request references a
-  concrete existing capability (a module, workflow, script, or shipped
-  feature) rather than proposing a new one. "Fix the flaky retry in
-  `evidence-gate.js`" is a delta; "add a retry framework" is not.
-- **Existing corpus covers the touched area.** The project's docs digest
-  and/or an already-closed or in-flight Epic's Tech Spec section already
-  describe the surface being changed — the standalone-Story path can draft
-  against that inherited context (`corpusContext` in the `/plan --idea`
-  envelope) instead of re-deriving architecture from a blank slate. When no
-  corpus hit exists for the touched area, that is a signal the request may
-  be reaching into genuinely new territory — re-check the `epic` signals
-  below before defaulting to `story`.
-- **Footprint fits Story sizing.** The plausible file footprint and
-  acceptance-criteria count still fit the Story width in
-  `DEFAULT_TASK_SIZING` (per the `story` verdict signals above) — a change
-  request that fans out across independent subsystems is sized like an Epic
-  regardless of how small the originating request sounded.
-
-### Story-verdict rationale template
-
-Use this template to record the verdict — it names which delta signal
-carried the call, so a reviewer can sanity-check the routing decision without
-re-deriving it:
-
-```text
-Verdict: story
-Delta: <the existing surface this change targets>
-Corpus hit: <docs digest section / Epic # and Tech Spec excerpt that covers
-  this area, or "none — re-checked epic signals, still story-sized">
-Footprint: <rough file/AC count vs DEFAULT_TASK_SIZING>
-```
-
-### Worked example
-
-> Request: "The `/plan` standalone-Story path always drafts from a blank
-> slate even when a change request is a small delta against something we
-> already shipped — thread the existing docs digest and matching Epic
-> Tech Spec sections into the draft context."
->
-> ```text
-> Verdict: story
-> Delta: story-plan.js's --emit-context envelope and the plan-story.md
->   Phase 2 drafting instructions — both already exist and ship today.
-> Corpus hit: Epic #4429's own Tech Spec section (this rubric's parent
->   Epic) already describes the docs-digest reuse pattern from
->   orchestration/docs-digest.js.
-> Footprint: one new lib module (planning-corpus.js), one envelope field,
->   one helper-doc instruction — comfortably inside DEFAULT_TASK_SIZING's
->   softFiles/softAcceptanceCount band.
-> ```
-
-## Handoff & no-re-triage rule
-
-A workflow entered via a scope-triage **handoff** MUST NOT re-triage. A handoff
-*is* a triage decision already made — re-running this gate on the receiving side
-would re-litigate a settled call and risk a ping-pong between two planning
-workflows. Handoff invocations identify themselves as such (e.g. `/plan`
-entered via a `/plan` scope-triage escalation, or `/plan` entered
-via an `/plan` Phase 1.5 handoff), and the receiving workflow skips its own
-scope-triage gate when it detects the handoff marker.
-
-## When to use
-
-- **`/plan` Phase 1.5** (ideation path only) — judge the sharpened
-  one-pager Phase 1 produced before the Epic ceremony is paid for. The verdict
-  folds into the existing Phase 1 HITL stop; on a `story` / `borderline`
-  verdict the operator may hand off to
-  [`/plan --from-notes`](../../../workflows/helpers/plan-story.md).
-- Any other planning gate that needs the canonical story-vs-epic rubric. Keep
-  the rubric here as the SSOT; consumers reference this file rather than
-  forking the prose.
-
-## Output
-
-A single verdict (`epic` | `story` | `borderline`) plus a one-paragraph
-rationale grounded in the signals above. The rationale names the deciding
-signal (cohesion, capability count, blast radius, dependency graph, or sizing
-fit) so the operator can sanity-check the call before acting on it.
-
-## Anti-patterns to avoid
-
-- **Restating the sizing numbers.** Reference `DEFAULT_TASK_SIZING` /
-  `DELIVERABLE_GRANULARITY_GUIDANCE`; never copy the thresholds into this file
-  (they would drift from the validator).
-- **Auto-routing on the verdict.** The verdict is advisory; the operator
-  decides. Never silently fork a workflow on a `story` verdict.
-- **Forcing a binary call.** When the work is genuinely on the line, emit
-  `borderline` and present the choice. Do not collapse it to `epic` or `story`
-  to look decisive.
-- **Re-triaging after a handoff.** A handoff is a settled decision. Skip the
-  gate when the invocation identifies itself as a scope-triage handoff.
+Never auto-route. The operator (or `--yes` default = `keep-single`) decides.

package/.agents/skills/core/security-and-hardening/SKILL.md

@@ -31,370 +31,25 @@ patterns and process guidance; read the rule for the **what**. When the rule
 and this skill diverge, the rule wins — open a PR against the rule rather
 than working around it here.
 
-## When to Use
-
-- Building anything that accepts user input
-- Implementing authentication or authorization
-- Storing or transmitting sensitive data
-- Integrating with external APIs or services
-- Adding file uploads, webhooks, or callbacks
-- Handling payment or PII data
-
-## Security Surfacing, Not Runtime Pause
-
-Some changes are not unsafe by themselves but expand the security surface
-enough that the change must be **explicitly documented** in the PR
-description and on the originating ticket so a reviewer can sign off in
-band. Documenting them is the gate — they do **not** pause execution:
-
-- Adding new authentication flows or changing auth logic
-- Storing new categories of sensitive data (PII, payment info)
-- Adding new external service integrations
-- Changing CORS configuration
-- Adding file upload handlers
-- Modifying rate limiting or throttling
-- Granting elevated permissions or roles
-
-For each item that applies, call it out under a "Security surface" section
-in the PR body and on the parent ticket, label the change `risk::high`,
-and link the relevant `security-baseline.md` MUST. Reviewers gate the
-merge; the agent keeps moving.
-
-`agent::blocked` remains the **only** runtime pause label. Use it for
-unrecoverable blockers (missing prerequisite, ambiguous spec a sub-agent
-cannot resolve), not for "this change is sensitive." Sensitive changes
-ship through the documentation path above.
-
-## OWASP Top 10 Prevention Patterns
-
-The patterns below show **how** to satisfy the MUSTs in
-[`security-baseline.md`](../../../rules/security-baseline.md). The MUSTs
-themselves (parameterize queries, hash passwords, encode output, verify
-ownership, set headers, restrict CORS, exclude sensitive fields) are listed
-in the rule.
-
-### 1. Injection (SQL, NoSQL, OS Command)
-
-See [security-baseline § Output & Rendering](../../../rules/security-baseline.md#output--rendering).
-
-```typescript
-// BAD: SQL injection via string concatenation
-const query = `SELECT * FROM users WHERE id = '${userId}'`;
-
-// GOOD: Parameterized query
-const user = await db.query('SELECT * FROM users WHERE id = $1', [userId]);
-
-// GOOD: ORM with parameterized input
-const user = await prisma.user.findUnique({ where: { id: userId } });
-```
-
-### 2. Broken Authentication
-
-See [security-baseline § Authentication](../../../rules/security-baseline.md#authentication).
-
-```typescript
-import { hash, compare } from 'bcrypt';
-
-const SALT_ROUNDS = 12;
-const hashedPassword = await hash(plaintext, SALT_ROUNDS);
-const isValid = await compare(plaintext, hashedPassword);
-
-// Session management
-app.use(
-  session({
-    secret: process.env.SESSION_SECRET, // From environment, not code
-    resave: false,
-    saveUninitialized: false,
-    cookie: {
-      httpOnly: true,
-      secure: true,
-      sameSite: 'lax',
-      maxAge: 24 * 60 * 60 * 1000,
-    },
-  }),
-);
-```
-
-### 3. Cross-Site Scripting (XSS)
-
-See [security-baseline § Output & Rendering](../../../rules/security-baseline.md#output--rendering).
-
-```typescript
-// BAD: Rendering user input as HTML
-element.innerHTML = userInput;
-
-// GOOD: Use framework auto-escaping (React does this by default)
-return <div>{userInput}</div>;
-
-// If you MUST render HTML, sanitize first
-import DOMPurify from 'dompurify';
-const clean = DOMPurify.sanitize(userInput);
-```
-
-### 4. Broken Access Control
-
-See [security-baseline § Authorization](../../../rules/security-baseline.md#authorization).
-
-```typescript
-app.patch('/api/tasks/:id', authenticate, async (req, res) => {
-  const task = await taskService.findById(req.params.id);
-
-  if (task.ownerId !== req.user.id) {
-    return res.status(403).json({
-      error: {
-        code: 'FORBIDDEN',
-        message: 'Not authorized to modify this task',
-      },
-    });
-  }
-
-  const updated = await taskService.update(req.params.id, req.body);
-  return res.json(updated);
-});
-```
-
-### 5. Security Misconfiguration
-
-See [security-baseline § Transport & Headers](../../../rules/security-baseline.md#transport--headers).
-
-```typescript
-import helmet from 'helmet';
-app.use(helmet());
-
-app.use(
-  helmet.contentSecurityPolicy({
-    directives: {
-      defaultSrc: ["'self'"],
-      scriptSrc: ["'self'"],
-      styleSrc: ["'self'", "'unsafe-inline'"],
-      imgSrc: ["'self'", 'data:', 'https:'],
-      connectSrc: ["'self'"],
-    },
-  }),
-);
-
-app.use(
-  cors({
-    origin: process.env.ALLOWED_ORIGINS?.split(',') || 'http://localhost:3000',
-    credentials: true,
-  }),
-);
-```
-
-### 6. Sensitive Data Exposure
-
-See [security-baseline § Output & Rendering](../../../rules/security-baseline.md#output--rendering)
-and [§ Secrets Management](../../../rules/security-baseline.md#secrets-management).
-
-```typescript
-function sanitizeUser(user: UserRecord): PublicUser {
-  const { passwordHash, resetToken, ...publicFields } = user;
-  return publicFields;
-}
-
-const API_KEY = process.env.STRIPE_API_KEY;
-if (!API_KEY) throw new Error('STRIPE_API_KEY not configured');
-```
-
-## Input Validation Patterns
-
-See [security-baseline § Input Validation](../../../rules/security-baseline.md#input-validation).
-
-### Schema Validation at Boundaries
-
-```typescript
-import { z } from 'zod';
-
-const CreateTaskSchema = z.object({
-  title: z.string().min(1).max(200).trim(),
-  description: z.string().max(2000).optional(),
-  priority: z.enum(['low', 'medium', 'high']).default('medium'),
-  dueDate: z.string().datetime().optional(),
-});
-
-app.post('/api/tasks', async (req, res) => {
-  const result = CreateTaskSchema.safeParse(req.body);
-  if (!result.success) {
-    return res.status(422).json({
-      error: {
-        code: 'VALIDATION_ERROR',
-        message: 'Invalid input',
-        details: result.error.flatten(),
-      },
-    });
-  }
-  const task = await taskService.create(result.data);
-  return res.status(201).json(task);
-});
-```
-
-### File Upload Safety
-
-```typescript
-const ALLOWED_TYPES = ['image/jpeg', 'image/png', 'image/webp'];
-const MAX_SIZE = 5 * 1024 * 1024; // 5MB
-
-function validateUpload(file: UploadedFile) {
-  if (!ALLOWED_TYPES.includes(file.mimetype)) {
-    throw new ValidationError('File type not allowed');
-  }
-  if (file.size > MAX_SIZE) {
-    throw new ValidationError('File too large (max 5MB)');
-  }
-  // Don't trust the file extension — check magic bytes if critical
-}
-```
-
-## Triaging npm audit Results
-
-The MUST is in [security-baseline § Dependency Hygiene](../../../rules/security-baseline.md#dependency-hygiene).
-This decision tree shows how to prioritize:
-
-```text
-npm audit reports a vulnerability
-├── Severity: critical or high
-│   ├── Is the vulnerable code reachable in your app?
-│   │   ├── YES --> Fix immediately (update, patch, or replace the dependency)
-│   │   └── NO (dev-only dep, unused code path) --> Fix soon, but not a blocker
-│   └── Is a fix available?
-│       ├── YES --> Update to the patched version
-│       └── NO --> Check for workarounds, consider replacing the dependency, or add to allowlist with a review date
-├── Severity: moderate
-│   ├── Reachable in production? --> Fix in the next release cycle
-│   └── Dev-only? --> Fix when convenient, track in backlog
-└── Severity: low
-    └── Track and fix during regular dependency updates
-```
-
-**Key questions:**
-
-- Is the vulnerable function actually called in your code path?
-- Is the dependency a runtime dependency or dev-only?
-- Is the vulnerability exploitable given your deployment context (e.g., a
-  server-side vulnerability in a client-only app)?
-
-When you defer a fix, document the reason and set a review date.
-
-## Rate Limiting
-
-```typescript
-import rateLimit from 'express-rate-limit';
-
-// General API rate limit
-app.use(
-  '/api/',
-  rateLimit({
-    windowMs: 15 * 60 * 1000,
-    max: 100,
-    standardHeaders: true,
-    legacyHeaders: false,
-  }),
-);
-
-// Stricter limit for auth endpoints (the rule MUSTs rate-limiting on auth)
-app.use(
-  '/api/auth/',
-  rateLimit({
-    windowMs: 15 * 60 * 1000,
-    max: 10,
-  }),
-);
-```
-
-## Secrets Management Layout
-
-See [security-baseline § Secrets Management](../../../rules/security-baseline.md#secrets-management).
-
-```text
-.env files:
-  ├── .env.example  → Committed (template with placeholder values)
-  ├── .env          → NOT committed (contains real secrets)
-  └── .env.local    → NOT committed (local overrides)
-
-.gitignore must include:
-  .env
-  .env.local
-  .env.*.local
-  *.pem
-  *.key
-```
-
-**Always check before committing:**
-
-```bash
-# Check for accidentally staged secrets
-git diff --cached | grep -i "password\|secret\|api_key\|token"
-```
-
-## Security Review Checklist
-
-Use this when reviewing your own change before requesting human review. Each
-item maps to a section in
-[`security-baseline.md`](../../../rules/security-baseline.md).
-
-```markdown
-### Authentication
-
-- [ ] Passwords hashed with bcrypt/scrypt/argon2 (salt rounds ≥ 12)
-- [ ] Session tokens are httpOnly, secure, sameSite
-- [ ] Login has rate limiting
-- [ ] Password reset tokens expire
-
-### Authorization
-
-- [ ] Every endpoint checks user permissions
-- [ ] Users can only access their own resources
-- [ ] Admin actions require admin role verification
-
-### Input
-
-- [ ] All user input validated at the boundary
-- [ ] SQL queries are parameterized
-- [ ] HTML output is encoded/escaped
-
-### Data
-
-- [ ] No secrets in code or version control
-- [ ] Sensitive fields excluded from API responses
-- [ ] PII encrypted at rest (if applicable)
-
-### Infrastructure
-
-- [ ] Security headers configured (CSP, HSTS, etc.)
-- [ ] CORS restricted to known origins
-- [ ] Dependencies audited for vulnerabilities
-- [ ] Error messages don't expose internals
-```
-
-## Common Rationalizations
-
-| Rationalization                                     | Reality                                                                         |
-| --------------------------------------------------- | ------------------------------------------------------------------------------- |
-| "This is an internal tool, security doesn't matter" | Internal tools get compromised. Attackers target the weakest link.              |
-| "We'll add security later"                          | Security retrofitting is 10x harder than building it in. Add it now.            |
-| "No one would try to exploit this"                  | Automated scanners will find it. Security by obscurity is not security.         |
-| "The framework handles security"                    | Frameworks provide tools, not guarantees. You still need to use them correctly. |
-| "It's just a prototype"                             | Prototypes become production. Security habits from day one.                     |
-
-## Red Flags
-
-- User input passed directly to database queries, shell commands, or HTML
-  rendering
-- Secrets in source code or commit history
-- API endpoints without authentication or authorization checks
-- Missing CORS configuration or wildcard (`*`) origins
-- No rate limiting on authentication endpoints
-- Stack traces or internal errors exposed to users
-- Dependencies with known critical vulnerabilities
-
-## Verification
-
-After implementing security-relevant code, confirm against the rule:
-
-- [ ] `npm audit` shows no critical or high vulnerabilities
-- [ ] No secrets in source code or git history
-- [ ] All user input validated at system boundaries
-- [ ] Authentication and authorization checked on every protected endpoint
-- [ ] Security headers present in response (check with browser DevTools)
-- [ ] Error responses don't expose internal details
-- [ ] Rate limiting active on auth endpoints
+## 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.
+
+- [When to Use](reference.md#when-to-use)
+- [Security Surfacing, Not Runtime Pause](reference.md#security-surfacing-not-runtime-pause)
+- [OWASP Top 10 Prevention Patterns](reference.md#owasp-top-10-prevention-patterns)
+- [Input Validation Patterns](reference.md#input-validation-patterns)
+- [Triaging npm audit Results](reference.md#triaging-npm-audit-results)
+- [Rate Limiting](reference.md#rate-limiting)
+- [Secrets Management Layout](reference.md#secrets-management-layout)
+- [Security Review Checklist](reference.md#security-review-checklist)
+- [Common Rationalizations](reference.md#common-rationalizations)
+- [Red Flags](reference.md#red-flags)
+- [Verification](reference.md#verification)