mandrel 2.7.0 → 2.8.0

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

@@ -3,17 +3,11 @@
 **Read this when** a task engages one of the sections below and the Policy
 Capsule in [`SKILL.md`](SKILL.md) does not settle it on its own. The capsule
 is the contract; this file is the reference material behind it. Nothing here
-relaxes a capsule MUST, and nothing here is required reading merely because
-the skill is active.
-
-## 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
+relaxes a capsule MUST, and the generic *how* of each MUST (parameterize
+queries, hash passwords, encode output, verify ownership, set headers,
+restrict CORS, validate at the boundary) is stated once in the SSOT rule,
+[`security-baseline.md`](../../../rules/security-baseline.md) — not duplicated
+here.
 
 ## Security Surfacing, Not Runtime Pause
 
@@ -40,185 +34,17 @@ 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).
+## Validation-Error Responses
 
-```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
-}
-```
+The status code and response envelope for a failed input validation are owned
+by the wire-format SSOT, not by this skill: validation failures MUST return
+**400 Bad Request** with `error.code = "VALIDATION_ERROR"` in the canonical
+envelope. See
+[`api-conventions.md` § Validation Status](../../../rules/api-conventions.md#validation-status)
+and [§ Response Envelope](../../../rules/api-conventions.md#response-envelope).
+Do not hand-roll a divergent status (e.g. 422) or envelope shape in
+security-relevant handlers — cite the rule and reuse its shape, keeping the
+security skill and the api skill in agreement.
 
 ## Triaging npm audit Results
 
@@ -250,57 +76,6 @@ npm audit reports a vulnerability
 
 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
@@ -340,36 +115,3 @@ item maps to a section in
 - [ ] 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

package/.agents/skills/skills.index.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-07-16T20:44:41.281Z",
+  "generatedAt": "2026-07-21T13:53:23.232Z",
   "generator": "generate-skills-index.js@1",
   "skills": [
     {
@@ -78,7 +78,7 @@
       "category": "core",
       "path": ".agents/skills/core/git-workflow-and-versioning/SKILL.md",
       "description": "Structures git workflow practices. Use when making any code change. Use when committing, branching, resolving conflicts, or when you need to organize work across multiple parallel streams.",
-      "policyCapsuleBullets": 10,
+      "policyCapsuleBullets": 6,
       "allowedTools": null,
       "vendor": null
     },
@@ -117,8 +117,8 @@
       "tier": "core",
       "category": "core",
       "path": ".agents/skills/core/security-and-hardening/SKILL.md",
-      "description": "Hardens code against vulnerabilities. Use when handling user input, authentication, data storage, or external integrations. The non-negotiable security MUSTs live in `.agents/rules/security-baseline.md`; this skill shows how to apply them with code patterns, decision trees, and review checklists.",
-      "policyCapsuleBullets": 11,
+      "description": "Hardens code against vulnerabilities. Use when handling user input, authentication, data storage, or external integrations. The non-negotiable security MUSTs live in `.agents/rules/security-baseline.md`; this skill shows how to apply them with process guidance, an audit-triage tree, and a review checklist.",
+      "policyCapsuleBullets": 6,
       "allowedTools": null,
       "vendor": null
     },
@@ -168,7 +168,7 @@
       "category": "qa",
       "path": ".agents/skills/stack/qa/qa-harness/SKILL.md",
       "description": "Conventions for the agent-driven QA harness that drives Gherkin scenarios through a real browser. Use when executing `/qa-run` or instrumenting a live surface — covers navigation-first execution, per-surface console and network capture, design-token visual checks, and the framework-generic heuristic cards for turning signal into findings. The harness procedure lives in `.agents/workflows/qa-run.md`; this skill is the conventions reference it leans on.",
-      "policyCapsuleBullets": 8,
+      "policyCapsuleBullets": 7,
       "allowedTools": null,
       "vendor": null
     },

package/.agents/skills/stack/qa/gherkin-authoring/SKILL.md

@@ -21,234 +21,28 @@ description:
 - Author one scenario per PRD acceptance criterion; for bounded matrices, use a Scenario Outline with ≤12 Examples rows.
 - Use third-person present-tense, role-qualified actors (`the billing-admin`), never first person.
 
-Guidance for authoring `.feature` files that stay business-readable, translate
-cleanly from PRD acceptance criteria, and reuse a shared step-definition
-library. The enforcement rules — tag taxonomy, forbidden patterns, Outline
-conventions, selector discipline, step reuse — live in
+The enforcement rules — tag taxonomy, forbidden patterns, Outline conventions,
+selector discipline, step reuse — live in
 [`.agents/rules/gherkin-standards.md`](../../../../rules/gherkin-standards.md),
 which is the SSOT. This skill shows authors **how** to apply those rules; read
-the rule file for the **what**. Runtime wiring for Playwright consumers is
-covered by [`playwright-bdd`](../playwright-bdd/SKILL.md); test-layer scope is
-covered by
-[`testing-standards.md`](../../../../rules/testing-standards.md).
+the rule for the **what**.
 
-## 1. Canonical Given / When / Then Phrasing
+## Long-form reference — read on demand
 
-`.feature` prose is written for a product-minded reader, not a test harness.
-Each clause has exactly one job:
+The worked authoring material — canonical Given/When/Then phrasing, the
+one-AC-to-one-scenario translation walkthrough, Background-vs-Given and
+Outline-vs-multi-scenario decisions, the step-definition library layout and
+reuse/deprecation workflow, and the pre-PR authoring checklist — lives in the
+on-demand sibling [`reference.md`](reference.md). Open a section only when the
+task engages it.
 
-- **Given** — a precondition that is *already true* when the scenario starts.
-  Stative, past or present tense. No actions.
-  - Good: `Given a signed-in account-owner with an unpaid invoice`.
-  - Bad: `Given the user clicks the login button` (that's a When).
-- **When** — the single business action under test. One verb, one actor, one
-  event. Splitting a When into multiple clauses is almost always wrong — move
-  the extra clauses into Given.
-  - Good: `When they issue the invoice`.
-  - Bad: `When they log in and issue the invoice and download the PDF`.
-- **Then** — an observable, user-visible outcome. Assert what the *user* sees
-  or what the *business* records, not what the system emits internally.
-  - Good: `Then the invoice appears in the issued invoices list`.
-  - Bad: `Then a 201 is returned` (forbidden; see
-    [gherkin-standards § Forbidden Patterns](../../../../rules/gherkin-standards.md#forbidden-patterns)).
-- **And / But** — continuation clauses. They inherit the mood of the most
-  recent Given/When/Then. Never start a scenario with And/But.
+- [Canonical Given / When / Then Phrasing](reference.md#canonical-given--when--then-phrasing)
+- [Translating PRD Acceptance Criteria to Scenarios](reference.md#translating-prd-acceptance-criteria-to-scenarios)
+- [Background vs. Given, Outline vs. Multi-Scenario](reference.md#background-vs-given-outline-vs-multi-scenario)
+- [Step-Definition Library Structure](reference.md#step-definition-library-structure)
+- [Authoring Checklist](reference.md#authoring-checklist)
 
-Voice and tense:
-
-- Third-person, present tense. `the user`, `an admin`, `a billing-admin`
-  (role-qualified nouns, not "I" or "we").
-- One clause, one fact. Comma-chained facts hide compound assertions.
-- Numbers and identifiers go in `Examples` tables or fixtures, not inline
-  prose. Prose should read the same whether the underlying fixture has 1 or
-  10,000 rows.
-
-## 2. Translating PRD Acceptance Criteria to Scenarios
-
-PRD ACs are the raw material. The authoring move is **one AC → one scenario**
-unless the AC encodes a matrix (in which case it becomes a Scenario Outline —
-see §3).
-
-Walkthrough — a PRD AC from a billing feature:
-
-> **AC-3:** When a billing-admin issues an invoice for a customer with a
-> negative balance, the system rejects the issue and shows an error naming the
-> outstanding amount.
-
-Translation steps:
-
-1. **Identify the domain.** Billing → tag the scenario `@domain-billing`.
-2. **Identify the actor and precondition.** "billing-admin", "customer with a
-   negative balance" → two Givens.
-3. **Identify the single action.** "issues an invoice" → one When.
-4. **Identify the observable outcome.** "rejects the issue and shows an error
-   naming the outstanding amount" → two Thens. The first asserts the business
-   outcome (rejection); the second asserts the user-visible detail (error
-   names the amount).
-5. **Pick the risk tag.** If the originating ticket was `risk::high`, add
-   `@risk-high`. Smoke tag only if this is a critical path on every PR.
-
-Resulting scenario:
-
-```gherkin
-@domain-billing @risk-high
-Scenario: Issuing an invoice is rejected when the customer has a negative balance
-  Given a signed-in billing-admin
-  And a customer with a negative account balance
-  When the billing-admin issues an invoice for that customer
-  Then the issue is rejected
-  And the rejection message names the outstanding amount
-```
-
-Heuristics:
-
-- If a single AC needs more than **one When**, it is really two ACs. Split
-  before you write.
-- If a Then starts with "and the database has…" or "and the API returned…",
-  you have crossed into step-definition or contract-test territory. Rewrite
-  it as user-visible language or move the assertion to a contract test (see
-  [testing-standards](../../../../rules/testing-standards.md)).
-- If an AC says "the system logs X", that's an engineering non-functional
-  requirement — not a BDD scenario. Cover it with a focused unit or
-  integration test, not a `.feature` file.
-- When a PRD AC is phrased negatively ("non-admins cannot export"), prefer a
-  Scenario Outline if there are multiple negative roles; write a plain
-  Scenario if there is exactly one.
-
-## 3. Background vs. Given — and Outline vs. Multi-Scenario
-
-Two authoring decisions that authors routinely get wrong.
-
-### 3.1 Background vs. Given
-
-`Background` runs before **every** scenario in the file. Use it only when:
-
-- Every scenario in the file genuinely shares the precondition, **and**
-- The precondition has no per-scenario variation (no `<placeholders>`,
-  no per-scenario data).
-
-Prefer a per-scenario Given when:
-
-- Only some scenarios need the precondition. A Background that applies to
-  four out of five scenarios is a Background for none of them; move it.
-- The precondition varies by role, plan tier, or fixture shape. Variation
-  belongs in a Scenario Outline's Examples, not in Background.
-- Readers cannot understand the scenario without scrolling up to read
-  Background. Background is a shortcut; if it hurts readability, inline it.
-
-Rule of thumb: if you find yourself writing *"except in the admin scenario,
-where the Background step is actually…"*, delete the Background.
-
-### 3.2 Scenario Outline vs. multiple Scenarios
-
-Use `Scenario Outline` when the **same behavior** is exercised across a
-**bounded matrix** (roles, plan tiers, locales). The shape of the scenario —
-Givens, When, Thens — is identical; only the data varies.
-
-Use multiple `Scenario` blocks when:
-
-- The Givens differ structurally (not just in value).
-- The When verb differs.
-- The Then outcomes differ in kind, not just in value. "Delivered vs.
-  denied" is one outcome column (see Outline skeleton in
-  [gherkin-standards § Scenario Outline Conventions](../../../../rules/gherkin-standards.md#scenario-outline-conventions)).
-  "Email is sent vs. invoice is issued vs. account is suspended" are three
-  different scenarios.
-
-Scale guardrails (also in gherkin-standards):
-
-- Keep `Examples` tables under ~12 rows. Larger tables hide distinct
-  behaviors behind a shared skeleton.
-- Split `Examples` by tag when rows need different tags (e.g. `@risk-high`
-  on admin rows only).
-
-## 4. Step-Definition Library Structure
-
-Authoring scenarios and maintaining steps are the same job split across two
-files. The library layout below keeps that coupling visible.
-
-### 4.1 Layout
-
-```text
-tests/
-  steps/
-    _common/          # actor, auth, navigation — reused across every domain
-      auth.steps.ts
-      navigation.steps.ts
-    billing/          # one directory per @domain-* tag
-      invoices.steps.ts
-      subscriptions.steps.ts
-    auth/
-      signin.steps.ts
-    _deprecated/      # steps pending migration; see §4.4
-```
-
-- One directory per `@domain-*` tag. `_common/` holds cross-cutting steps
-  (sign-in, navigation, generic waits handled at the fixture layer).
-- Files are named by the noun the steps act on
-  (`invoices.steps.ts`, not `billing-steps-1.ts`). A new noun is a new file.
-- Avoid deep nesting. Two levels (`steps/<domain>/<noun>.steps.ts`) is the
-  ceiling for most projects.
-
-### 4.2 Naming
-
-Step text follows the scenario text verbatim — if the scenario reads `the
-invoice appears in the issued invoices list`, the step regex matches exactly
-that phrase. Divergence between scenario prose and step text is a bug.
-
-- Parameterize only over values that vary across scenarios. A step that
-  accepts `{string}` for a literal that is always the same value is over-
-  parameterized; bake the constant in and rename the step.
-- Role-qualified actors (`{actor}`) read better than generic `{string}`.
-  Define a custom parameter type that resolves `account-owner`, `billing-admin`,
-  `viewer` to fixtures.
-- Keep step implementations ≤20 lines. Longer implementations indicate a
-  missing helper (domain fixture, page object, API client).
-
-### 4.3 Reuse Before Authoring
-
-The non-negotiable workflow is in
-[gherkin-standards § Step Reuse](../../../../rules/gherkin-standards.md#step-reuse--grep-before-you-write):
-grep the step tree for the verb stem before writing anything new. In practice:
-
-1. Search for the verb: `rg -n "issues? an invoice" tests/steps`.
-2. If the phrase exists, **change your scenario** to use that phrase. Do not
-   fork a near-duplicate step.
-3. If a near-match exists, extend the existing step (add a parameter, widen
-   the regex) and update every call site in the same PR.
-4. Only when no reasonable match exists, add a new step in the correct
-   domain directory.
-
-### 4.4 Deprecation
-
-When a step is superseded:
-
-1. Move the old definition into `steps/_deprecated/` and annotate it with a
-   one-line comment naming the replacement.
-2. Migrate every call site to the replacement in the same PR.
-3. Delete the `_deprecated/` entry when the migration lands.
-
-Never leave two live step definitions that mean the same thing. Parallel
-vocabularies rot the suite faster than any other source of maintenance cost.
-
-## 5. Authoring Checklist
-
-Before opening a PR that adds or edits a `.feature` file:
-
-- [ ] Every Scenario/Outline carries exactly one `@domain-*` tag.
-- [ ] No forbidden patterns (SQL, status codes, selectors, URLs, payloads,
-      framework names, explicit waits) appear in prose.
-- [ ] Each scenario has exactly one `When`.
-- [ ] `Then` clauses assert user-visible outcomes, not implementation.
-- [ ] `Background` is justified (applies to every scenario in the file).
-- [ ] If a Scenario Outline is used, the matrix is bounded (≤12 rows) and the
-      shape is truly identical across rows.
-- [ ] Every step phrase grep-matches an existing step definition **or** is
-      accompanied by a new step definition in the right domain directory.
-- [ ] Reads standalone — a product reader who has never seen the codebase can
-      understand the intent without opening a step file.
-
-## 6. Cross-References
+## Cross-References
 
 - SSOT rules: [`.agents/rules/gherkin-standards.md`](../../../../rules/gherkin-standards.md).
 - Runtime wiring: [`playwright-bdd`](../playwright-bdd/SKILL.md).