@givolt/i3-composer-agent 0.0.0-stage → 1.0.0

package/skills/code-simplification/SKILL.md

@@ -0,0 +1,331 @@
+---
+name: code-simplification
+description: Simplifies code for clarity. Use when refactoring code for clarity without changing behavior. Use when code works but is harder to read, maintain, or extend than it should be. Use when reviewing code that has accumulated unnecessary complexity.
+---
+
+# Code Simplification
+
+> Inspired by the [Claude Code Simplifier plugin](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/code-simplifier/agents/code-simplifier.md). Adapted here as a model-agnostic, process-driven skill for any AI coding agent.
+
+## Overview
+
+Simplify code by reducing complexity while preserving exact behavior. The goal is not fewer lines — it's code that is easier to read, understand, modify, and debug. Every simplification must pass a simple test: "Would a new team member understand this faster than the original?"
+
+## When to Use
+
+- After a feature is working and tests pass, but the implementation feels heavier than it needs to be
+- During code review when readability or complexity issues are flagged
+- When you encounter deeply nested logic, long functions, or unclear names
+- When refactoring code written under time pressure
+- When consolidating related logic scattered across files
+- After merging changes that introduced duplication or inconsistency
+
+**When NOT to use:**
+
+- Code is already clean and readable — don't simplify for the sake of it
+- You don't understand what the code does yet — comprehend before you simplify
+- The code is performance-critical and the "simpler" version would be measurably slower
+- You're about to rewrite the module entirely — simplifying throwaway code wastes effort
+
+## The Five Principles
+
+### 1. Preserve Behavior Exactly
+
+Don't change what the code does — only how it expresses it. All inputs, outputs, side effects, error behavior, and edge cases must remain identical. If you're not sure a simplification preserves behavior, don't make it.
+
+```
+ASK BEFORE EVERY CHANGE:
+→ Does this produce the same output for every input?
+→ Does this maintain the same error behavior?
+→ Does this preserve the same side effects and ordering?
+→ Do all existing tests still pass without modification?
+```
+
+### 2. Follow Project Conventions
+
+Simplification means making code more consistent with the codebase, not imposing external preferences. Before simplifying:
+
+```
+1. Read CLAUDE.md / project conventions
+2. Study how neighboring code handles similar patterns
+3. Match the project's style for:
+   - Import ordering and module system
+   - Function declaration style
+   - Naming conventions
+   - Error handling patterns
+   - Type annotation depth
+```
+
+Simplification that breaks project consistency is not simplification — it's churn.
+
+### 3. Prefer Clarity Over Cleverness
+
+Explicit code is better than compact code when the compact version requires a mental pause to parse.
+
+```typescript
+// UNCLEAR: Dense ternary chain
+const label = isNew ? 'New' : isUpdated ? 'Updated' : isArchived ? 'Archived' : 'Active';
+
+// CLEAR: Readable mapping
+function getStatusLabel(item: Item): string {
+  if (item.isNew) return 'New';
+  if (item.isUpdated) return 'Updated';
+  if (item.isArchived) return 'Archived';
+  return 'Active';
+}
+```
+
+```typescript
+// UNCLEAR: Chained reduces with inline logic
+const result = items.reduce((acc, item) => ({
+  ...acc,
+  [item.id]: { ...acc[item.id], count: (acc[item.id]?.count ?? 0) + 1 }
+}), {});
+
+// CLEAR: Named intermediate step
+const countById = new Map<string, number>();
+for (const item of items) {
+  countById.set(item.id, (countById.get(item.id) ?? 0) + 1);
+}
+```
+
+### 4. Maintain Balance
+
+Simplification has a failure mode: over-simplification. Watch for these traps:
+
+- **Inlining too aggressively** — removing a helper that gave a concept a name makes the call site harder to read
+- **Combining unrelated logic** — two simple functions merged into one complex function is not simpler
+- **Removing "unnecessary" abstraction** — some abstractions exist for extensibility or testability, not complexity
+- **Optimizing for line count** — fewer lines is not the goal; easier comprehension is
+
+### 5. Scope to What Changed
+
+Default to simplifying recently modified code. Avoid drive-by refactors of unrelated code unless explicitly asked to broaden scope. Unscoped simplification creates noise in diffs and risks unintended regressions.
+
+## The Simplification Process
+
+### Step 1: Understand Before Touching (Chesterton's Fence)
+
+Before changing or removing anything, understand why it exists. This is Chesterton's Fence: if you see a fence across a road and don't understand why it's there, don't tear it down. First understand the reason, then decide if the reason still applies.
+
+```
+BEFORE SIMPLIFYING, ANSWER:
+- What is this code's responsibility?
+- What calls it? What does it call?
+- What are the edge cases and error paths?
+- Are there tests that define the expected behavior?
+- Why might it have been written this way? (Performance? Platform constraint? Historical reason?)
+- Check git blame: what was the original context for this code?
+```
+
+If you can't answer these, you're not ready to simplify. Read more context first.
+
+### Step 2: Identify Simplification Opportunities
+
+Scan for these patterns — each one is a concrete signal, not a vague smell:
+
+**Structural complexity:**
+
+| Pattern | Signal | Simplification |
+|---------|--------|----------------|
+| Deep nesting (3+ levels) | Hard to follow control flow | Extract conditions into guard clauses or helper functions |
+| Long functions (50+ lines) | Multiple responsibilities | Split into focused functions with descriptive names |
+| Nested ternaries | Requires mental stack to parse | Replace with if/else chains, switch, or lookup objects |
+| Boolean parameter flags | `doThing(true, false, true)` | Replace with options objects or separate functions |
+| Repeated conditionals | Same `if` check in multiple places | Extract to a well-named predicate function |
+
+**Naming and readability:**
+
+| Pattern | Signal | Simplification |
+|---------|--------|----------------|
+| Generic names | `data`, `result`, `temp`, `val`, `item` | Rename to describe the content: `userProfile`, `validationErrors` |
+| Abbreviated names | `usr`, `cfg`, `btn`, `evt` | Use full words unless the abbreviation is universal (`id`, `url`, `api`) |
+| Misleading names | Function named `get` that also mutates state | Rename to reflect actual behavior |
+| Comments explaining "what" | `// increment counter` above `count++` | Delete the comment — the code is clear enough |
+| Comments explaining "why" | `// Retry because the API is flaky under load` | Keep these — they carry intent the code can't express |
+
+**Redundancy:**
+
+| Pattern | Signal | Simplification |
+|---------|--------|----------------|
+| Duplicated logic | Same 5+ lines in multiple places | Extract to a shared function |
+| Dead code | Unreachable branches, unused variables, commented-out blocks | Remove (after confirming it's truly dead) |
+| Unnecessary abstractions | Wrapper that adds no value | Inline the wrapper, call the underlying function directly |
+| Over-engineered patterns | Factory-for-a-factory, strategy-with-one-strategy | Replace with the simple direct approach |
+| Redundant type assertions | Casting to a type that's already inferred | Remove the assertion |
+
+### Step 3: Apply Changes Incrementally
+
+Make one simplification at a time. Run tests after each change. **Submit refactoring changes separately from feature or bug fix changes.** A PR that refactors and adds a feature is two PRs — split them.
+
+```
+FOR EACH SIMPLIFICATION:
+1. Make the change
+2. Run the test suite
+3. If tests pass → commit (or continue to next simplification)
+4. If tests fail → revert and reconsider
+```
+
+Avoid batching multiple simplifications into a single untested change. If something breaks, you need to know which simplification caused it.
+
+**The Rule of 500:** If a refactoring would touch more than 500 lines, invest in automation (codemods, sed scripts, AST transforms) rather than making the changes by hand. Manual edits at that scale are error-prone and exhausting to review.
+
+### Step 4: Verify the Result
+
+After all simplifications, step back and evaluate the whole:
+
+```
+COMPARE BEFORE AND AFTER:
+- Is the simplified version genuinely easier to understand?
+- Did you introduce any new patterns inconsistent with the codebase?
+- Is the diff clean and reviewable?
+- Would a teammate approve this change?
+```
+
+If the "simplified" version is harder to understand or review, revert. Not every simplification attempt succeeds.
+
+## Language-Specific Guidance
+
+### TypeScript / JavaScript
+
+```typescript
+// SIMPLIFY: Unnecessary async wrapper
+// Before
+async function getUser(id: string): Promise<User> {
+  return await userService.findById(id);
+}
+// After
+function getUser(id: string): Promise<User> {
+  return userService.findById(id);
+}
+
+// SIMPLIFY: Verbose conditional assignment
+// Before
+let displayName: string;
+if (user.nickname) {
+  displayName = user.nickname;
+} else {
+  displayName = user.fullName;
+}
+// After
+const displayName = user.nickname || user.fullName;
+
+// SIMPLIFY: Manual array building
+// Before
+const activeUsers: User[] = [];
+for (const user of users) {
+  if (user.isActive) {
+    activeUsers.push(user);
+  }
+}
+// After
+const activeUsers = users.filter((user) => user.isActive);
+
+// SIMPLIFY: Redundant boolean return
+// Before
+function isValid(input: string): boolean {
+  if (input.length > 0 && input.length < 100) {
+    return true;
+  }
+  return false;
+}
+// After
+function isValid(input: string): boolean {
+  return input.length > 0 && input.length < 100;
+}
+```
+
+### Python
+
+```python
+# SIMPLIFY: Verbose dictionary building
+# Before
+result = {}
+for item in items:
+    result[item.id] = item.name
+# After
+result = {item.id: item.name for item in items}
+
+# SIMPLIFY: Nested conditionals with early return
+# Before
+def process(data):
+    if data is not None:
+        if data.is_valid():
+            if data.has_permission():
+                return do_work(data)
+            else:
+                raise PermissionError("No permission")
+        else:
+            raise ValueError("Invalid data")
+    else:
+        raise TypeError("Data is None")
+# After
+def process(data):
+    if data is None:
+        raise TypeError("Data is None")
+    if not data.is_valid():
+        raise ValueError("Invalid data")
+    if not data.has_permission():
+        raise PermissionError("No permission")
+    return do_work(data)
+```
+
+### React / JSX
+
+```tsx
+// SIMPLIFY: Verbose conditional rendering
+// Before
+function UserBadge({ user }: Props) {
+  if (user.isAdmin) {
+    return <Badge variant="admin">Admin</Badge>;
+  } else {
+    return <Badge variant="default">User</Badge>;
+  }
+}
+// After
+function UserBadge({ user }: Props) {
+  const variant = user.isAdmin ? 'admin' : 'default';
+  const label = user.isAdmin ? 'Admin' : 'User';
+  return <Badge variant={variant}>{label}</Badge>;
+}
+
+// SIMPLIFY: Prop drilling through intermediate components
+// Before — consider whether context or composition solves this better.
+// This is a judgment call — flag it, don't auto-refactor.
+```
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "It's working, no need to touch it" | Working code that's hard to read will be hard to fix when it breaks. Simplifying now saves time on every future change. |
+| "Fewer lines is always simpler" | A 1-line nested ternary is not simpler than a 5-line if/else. Simplicity is about comprehension speed, not line count. |
+| "I'll just quickly simplify this unrelated code too" | Unscoped simplification creates noisy diffs and risks regressions in code you didn't intend to change. Stay focused. |
+| "The types make it self-documenting" | Types document structure, not intent. A well-named function explains *why* better than a type signature explains *what*. |
+| "This abstraction might be useful later" | Don't preserve speculative abstractions. If it's not used now, it's complexity without value. Remove it and re-add when needed. |
+| "The original author must have had a reason" | Maybe. Check git blame — apply Chesterton's Fence. But accumulated complexity often has no reason; it's just the residue of iteration under pressure. |
+| "I'll refactor while adding this feature" | Separate refactoring from feature work. Mixed changes are harder to review, revert, and understand in history. |
+
+## Red Flags
+
+- Simplification that requires modifying tests to pass (you likely changed behavior)
+- "Simplified" code that is longer and harder to follow than the original
+- Renaming things to match your preferences rather than project conventions
+- Removing error handling because "it makes the code cleaner"
+- Simplifying code you don't fully understand
+- Batching many simplifications into one large, hard-to-review commit
+- Refactoring code outside the scope of the current task without being asked
+
+## Verification
+
+After completing a simplification pass:
+
+- [ ] All existing tests pass without modification
+- [ ] Build succeeds with no new warnings
+- [ ] Linter/formatter passes (no style regressions)
+- [ ] Each simplification is a reviewable, incremental change
+- [ ] The diff is clean — no unrelated changes mixed in
+- [ ] Simplified code follows project conventions (checked against CLAUDE.md or equivalent)
+- [ ] No error handling was removed or weakened
+- [ ] No dead code was left behind (unused imports, unreachable branches)
+- [ ] A teammate or review agent would approve the change as a net improvement

package/skills/constraint-driven-development/SKILL.md

@@ -0,0 +1,311 @@
+---
+name: constraint-driven-development
+description: Establishes a project's quality bar as a written contract and stops agents quietly lowering it. Interviews the user on which dimensions matter, supplies sane default thresholds when they have no number in mind, records everything in CONSTRAINTS.md, and watches the diff for a weakened bar — new @ts-ignore or eslint-disable suppressions, skipped or deleted tests, assertions stripped out, unimplemented stubs, thresholds edited down. Use when no quality bar is written down, when the user says "set up constraints" or "define our standards", when the user wants dimensions they care about — accessibility, web performance, coverage — set up as enforced constraints, when an agent keeps silencing checks or skipping tests to get to green, when you need a coverage or performance threshold and don't know what number to pick, or when an agent writes more code than anyone will read.
+---
+
+# Constraint-Driven Development
+
+## Overview
+
+Other skills in this pack describe what good looks like. `code-review-and-quality` gives you five axes. `test-driven-development` gives you a cycle. `security-and-hardening` gives you a threat list. All of that lives in prose the agent reads and may or may not follow, and none of it survives the end of the session.
+
+This skill produces something different: a written record of **this project's** bar, with numbers, that outlives the conversation and can be checked mechanically.
+
+The reason matters. When you wrote the code, reading it told you whether it was any good. An agent writes more in an afternoon than you will read that week, so the judgement moves out of your head and into checks that run around the loop. Those checks need to exist, they need numbers you actually chose, and they need to fire close enough to the work that the agent fixes its own output.
+
+Spec-driven development says what to build. Test-driven development proves it works. Constraint-driven development defines what "good enough to ship" means, before anyone argues about it in a pull request.
+
+## When to Use
+
+Apply this skill when:
+
+- Starting a project or a significant feature and no quality bar is written down
+- The user asks to "set up constraints", "add quality gates", "define our standards", or "stop the agent shipping junk"
+- An agent is producing volume nobody is reading line by line
+- CI has checks but nobody can say which ones block a merge and which ones are decoration
+- Coverage, performance, or accessibility numbers get argued about per-PR instead of decided once
+- You're about to run `/build auto` or any autonomous loop, and the only thing standing between it and main is a test suite the agent also wrote
+
+**When NOT to use:**
+
+- The project already has a `CONSTRAINTS.md` and the user isn't changing it — read it and follow it instead
+- One-off scripts, spikes, throwaway prototypes
+- The user wants a code review right now (`code-review-and-quality`) or a CI pipeline built (`ci-cd-and-automation`)
+- Pre-product-market-fit code with a two-week expected lifetime — the floor below is still worth it, the rest isn't
+
+## Loading Constraints
+
+The interview needs a live user. **Don't run it in non-interactive contexts** (CI, `/loop`, autonomous runs). If constraints are missing and you're in one of those, apply the Floor below, note that you did, and flag the rest for a human.
+
+## The Process
+
+### Step 1: Detect before you ask
+
+Never ask what you can read. Before the first question, gather:
+
+| What | Where to look |
+|------|---------------|
+| Language and stack | `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml` |
+| Test runner | dev dependencies, `test` script, existing test files |
+| Existing linters | `eslint.config.*`, `biome.json`, `.ruff.toml` |
+| Coverage today | `coverage/` output, or run the suite once |
+| CI | `.github/workflows/`, `.gitlab-ci.yml` |
+| Agent harness | `.claude/`, `.codex/`, `AGENTS.md` |
+
+Report what you found in two lines, then ask only what's left.
+
+### Step 2: Four questions, each with a default
+
+Follow the one-question-at-a-time discipline from `interview-me`, with one change: every question here has a default, so "I don't know" is a complete answer that still produces a working config.
+
+```
+Q1: Beyond the floor, which of these do you want enforced?
+    (a) Test coverage on new code
+    (b) Security scanning
+    (c) Performance budgets
+    (d) Accessibility
+    (e) Architecture boundaries
+GUESS: (a) and (b) — you have a test runner already and you're handling user input.
+DEFAULT if unsure: (a) and (b).
+Say what each pick costs: (c) and (d) need a running URL, (e) needs a rules file written.
+```
+
+```
+Q2: When a check fails while the agent is mid-task, should it block or warn?
+GUESS: Block. You're running agents unattended and a warning nobody reads is a warning.
+DEFAULT if unsure: Block on the floor, warn on everything else for the first two weeks.
+```
+
+```
+Q3: Do you have target numbers in mind, or should I measure where you are today and hold that line?
+GUESS: Measure. Most teams don't have a number, and an invented one gets ignored.
+DEFAULT if unsure: Measure and hold. See "Ratchets" below.
+```
+
+```
+Q4: What's the slowest check you'll tolerate before the agent hands work back?
+GUESS: About 90 seconds. Longer and you'll stop running it.
+DEFAULT if unsure: 90 seconds at task end, unlimited in CI.
+```
+
+Stop at four. A twelve-question intake produces a config nobody understands and a user who regrets starting.
+
+### Step 3: Write CONSTRAINTS.md
+
+One file at the repo root. Any agent on any harness can read it, and a change to it shows up in review where it belongs.
+
+```markdown
+# Constraints
+
+Last reviewed: 2026-08-08 by @addy
+
+## Floor (always enforced, no setup required)
+
+- No new suppression comments: `@ts-ignore`, `eslint-disable`, `# noqa`, `# type: ignore`
+- No unimplemented stubs: `throw new Error("Not implemented")`, empty `catch {}`
+- No skipped or deleted tests without a reason in the commit message
+- No secrets in source
+- This file does not get weakened to make a change pass
+
+## Enforced with numbers
+
+| Dimension | Rule | Checked by | Runs at |
+|-----------|------|-----------|---------|
+| Types | Zero type errors | `tsc --noEmit` | every edit |
+| Lint | Zero errors from our config | `biome check` | every edit |
+| Secrets | No secrets in source | `gitleaks detect --redact` | every edit |
+| Coverage | Changed lines ≥ 80% covered | `vitest run --coverage` + git diff | task end, CI |
+| Security: code | No high findings | `semgrep scan --config p/default` | CI |
+| Security: deps | Nothing at high or above | `osv-scanner scan source -r .` | CI |
+| Accessibility | Zero critical or serious | `axe $PREVIEW_URL --tags wcag2a,wcag2aa,wcag21aa` | preview deploy |
+| Performance | LCP ≤ 2500ms, CLS ≤ 0.1 | `lighthouse $PREVIEW_URL --output=json` | preview deploy |
+
+Every row names the command that produces the verdict. A dimension with a
+number and no command in this column is an aspiration, not a constraint.
+
+## Measured, not yet enforced
+
+| Metric | Today | Direction |
+|--------|-------|-----------|
+| Project coverage | 62.4% | must not fall |
+| Bundle size (main) | 184 kB | must not grow |
+
+## Exceptions
+
+| ID | Rule | Path | Reason | Owner | Expires |
+|----|------|------|--------|-------|---------|
+| W1 | `no-explicit-any` | `src/legacy/**` | Rewrite tracked in ENG-441 | @addy | 2026-11-01 |
+```
+
+Then add one line to `AGENTS.md` and `CLAUDE.md`: `Read CONSTRAINTS.md before writing code. Do not weaken it to make a change pass.`
+
+### Step 4: Install what each dimension needs
+
+Picking a dimension means installing something. Don't leave the user with a number and no mechanism, and don't invent your own checker when a de facto one exists — these tools are listed because their rule formats and thresholds are what everything else in the ecosystem targets, so the team's existing config keeps working.
+
+| Dimension | Tool | Install | Run | Gate on |
+|-----------|------|---------|-----|---------|
+| Types (TS) | tsc | already there | `tsc --noEmit` | any error |
+| Types (Python) | mypy | `pip install mypy` | `mypy .` | any error |
+| Lint | your existing config | already there | `eslint .` / `biome check` / `ruff check` | any error |
+| Coverage (JS) | your test runner | already there | `vitest run --coverage` (or `jest --coverage`) | coverage of changed lines |
+| Coverage (Python) | pytest-cov | `pip install pytest-cov` | `pytest --cov --cov-report=lcov` | same |
+| Security: code | Semgrep | `pipx install semgrep` | `semgrep scan --config p/default --config p/owasp-top-ten` | any high finding |
+| Security: secrets | gitleaks | `brew install gitleaks` | `gitleaks detect --redact --no-banner` | any finding |
+| Security: dependencies | osv-scanner | `brew install osv-scanner` | `osv-scanner scan source -r .` | high or above |
+| Performance: page | Lighthouse | `npm i -D lighthouse` | `lighthouse $URL --output=json --quiet` | LCP, CLS, performance score |
+| Performance: bundle | size-limit | `npm i -D size-limit` | `size-limit --json` | per-entry byte budget |
+| Accessibility | axe-core | `npm i -D @axe-core/cli` | `axe $URL --tags wcag2a,wcag2aa,wcag21aa` | zero critical or serious |
+| Architecture | dependency-cruiser | `npm i -D dependency-cruiser` | `depcruise --validate src` | any violation |
+| Assertion quality | Stryker | `npm i -D @stryker-mutator/core` | `stryker run --mutate <changed files>` | mutation score |
+
+Five things that will bite you if you skip them:
+
+1. **`--redact` on gitleaks is not optional.** Without it the matched secret lands in the agent's transcript, which is how a leaked key ends up in a log, a summary, or a commit message. Report the rule and the location, never the value.
+2. **Lighthouse and axe need a URL.** They only work against a running app, so they belong in the runtime stage against a preview deploy or a local server you start first. If the project has no URL to hit — a CLI, a library, a desktop app — say so and drop the dimension rather than inventing a check that can't run.
+3. **Scope the expensive ones to the diff.** `stryker run --mutate` on the whole repo takes hours and gets turned off; on the files a change touched it takes under a minute. Same for Semgrep, which takes a path list.
+4. **Coverage needs no second test run.** Read the lcov your suite already writes and intersect it with `git diff`. Running the suite twice to get a number is the fastest way to make people hate this.
+5. **Semgrep's registry rules are free to run; check the licence before redistributing them.** `opengrep` is a drop-in fork with the same rule format and JSON output if that matters to your legal team.
+
+Add each one to the project's own script so it's reproducible without an agent:
+
+```json
+{
+  "scripts": {
+    "check:fast": "tsc --noEmit && eslint . && gitleaks detect --redact --no-banner",
+    "check:task": "npm run check:fast && vitest run --coverage",
+    "check:full": "npm run check:task && semgrep scan --config p/default && osv-scanner scan source -r ."
+  }
+}
+```
+
+That mapping matters more than the tools. `check:fast` is what runs after an edit, `check:task` when the agent thinks it's done, `check:full` in CI.
+
+The commands now live in two places — the `Checked by` column in `CONSTRAINTS.md` and these scripts. `CONSTRAINTS.md` is the canonical source: it carries the reason alongside each command and it shows up in review. The scripts are convenience wrappers that must mirror it, not a second source of truth; if they drift, the file wins.
+
+### Step 5: Wire it to the lifecycle
+
+The single biggest mistake is running everything everywhere. A check that stalls the agent gets switched off, and a gate people switched off is worse than no gate, because the bar still looks like it exists.
+
+| Phase | Command | What runs | Budget |
+|-------|---------|-----------|--------|
+| BUILD | `/build` | Types, lint, secrets, the floor | under 5s, changed file only |
+| VERIFY | `/test` | Related tests, coverage on changed lines | under 90s |
+| REVIEW | `/review` | Everything, plus the guards below | minutes |
+| SHIP | `/ship` | Direction checks, no regressions | CI |
+
+Two rules that keep this tolerable:
+
+1. **Scope to the diff.** Check the lines this change touched, not the whole repo. Coverage of changed lines is a number the agent can move; project coverage is one it inherited.
+2. **Cost decides placement.** Anything over a few seconds moves out of the edit loop. Mutation testing on a whole repo takes hours; on the files a change touched it takes under a minute, which is the difference between a check people run and one they don't.
+
+### Step 6: Guard the bar itself
+
+Someone will point out that if the agent writes the code and the checks, the checks prove nothing. Half right, and worth engineering around.
+
+Agents don't craft clever loopholes. They hit a red check and take the cheapest road to green. Watch for these five moves in the diff, at review time:
+
+1. **The threshold moved.** A budget lowered, a severity dropped, a check removed from the fast stage. Compare `CONSTRAINTS.md` against its state at the branch point.
+2. **A test got easier.** `.skip` added, a test file deleted, assertions pulled out of tests that stayed.
+3. **A checker got silenced.** New `@ts-ignore` or `eslint-disable`. Four suppressions deserve special attention because they switch off a check you're relying on: `istanbul ignore` drops code from coverage instead of testing it, `Stryker disable` hides a surviving mutant, `nosemgrep` and `gitleaks:allow` do it for security findings.
+4. **Work is unfinished.** A stub that throws, an empty `catch` turning a failure into silence, a `TODO` standing where the implementation should be.
+5. **An exception appeared.** A new row in the Exceptions table nobody discussed.
+
+None of this needs tooling beyond `git diff`. Tightening the bar should be silent; loosening it should be loud.
+
+Unlike the numbered dimensions, the floor has no de facto tool of its own, so an agent asked to enforce it tends to write a checker from scratch, and two agents write two different ones. A reference implementation of these five checks ships with this skill in [references/floor-guard.md](references/floor-guard.md) (diff-scoped, exit `0`/`1`/`2`, patterns adaptable per ecosystem). Adapt that rather than reinventing it, for the same reason every dimension names a de facto tool: so the mechanism is the same across runs and stacks.
+
+**Not all checks are equally circular.** Rank them by one question: can the agent make this pass by writing code that doesn't work?
+
+- **External** — axe-core encodes WCAG, `osv-scanner` reads a vulnerability database, Lighthouse measures a real browser. The agent can't argue with these.
+- **Project** — your lint rules, your layer boundaries. A human owns the file.
+- **Suite** — your own tests. Most useful, and the only genuinely circular one.
+
+A bar made entirely of the third kind is worth less than one with an outside opinion in it. Check that at least one external constraint is present.
+
+### Step 7: Ratchets, when you don't have a number
+
+Set 80% coverage on a codebase at 62% and you get a red build forever, then a team that learns to ignore red builds.
+
+The alternative asks for no decision: record where you are, then refuse to get worse. Put it in the "Measured, not yet enforced" table with today's number and a direction. Every check compares against the recorded value, not an aspiration. When a number improves, update it; when it drops, that's the finding.
+
+This also answers a fair objection to training. Models are rewarded for passing tests, which you can evaluate in seconds. Architectural rot shows up over months and never reaches the weights. A ratchet is the missing penalty, written down where the build can see it.
+
+## Sane Defaults
+
+When the user has no opinion, use these. They're chosen to be met by most codebases on day one.
+
+| Constraint | Default | Why this number |
+|------------|---------|-----------------|
+| Coverage of changed lines | ≥ 80% | High enough to force a test, low enough to allow a config line |
+| Project coverage | today's value, must not fall | No argument needed to adopt |
+| Mutation score (if used) | ≥ 60% to start | Typical for a suite never mutated before; 80% is mature |
+| Dependency vulnerabilities | nothing at high or above | Below that is mostly noise |
+| LCP | ≤ 2500 ms | Core Web Vitals "good" threshold |
+| CLS | ≤ 0.1 | Same |
+| Accessibility | zero critical or serious axe violations | Moderate and minor are often debatable |
+| Exception lifetime | 90 days | Long enough to plan the fix, short enough to remember |
+| Ratchet tolerance | 0.5% | Absorbs drift when an unrelated file moves the number |
+
+State the number and the reason together. A threshold without a rationale gets deleted by the next person who hits it.
+
+## Escalation Path
+
+Constraints work at three levels of teeth. Start at the first.
+
+1. **Written only.** `CONSTRAINTS.md` exists and agents read it. Costs nothing, catches the honest mistakes, relies on the agent complying.
+2. **Scripted.** An `npm run check` (or `make check`) that runs the fast checks, wired into your agent's post-edit hook and your CI. Deterministic, no new dependency.
+3. **Tool-backed.** A dedicated runner that handles diff scoping, budgets, ratchets, and the guard checks. Use when the config outgrows a shell script. The floor-guard reference in [references/floor-guard.md](references/floor-guard.md) is the starting point for the guard-checks half of this.
+
+Most projects should stop at 2. Move to 3 when you're maintaining more than about thirty lines of check-running shell.
+
+**A first run can be floor-only.** The floor guard is diff-only and needs no installs, so you can enforce the floor on day one and add numbered dimensions as you install each tool, rather than standing up every checker before the first commit is protected. Security tools that install machine-wide (gitleaks, osv-scanner) can also run CI-only if you'd rather keep laptops clean; declare where each dimension runs in the `Runs at` column.
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "We'll add constraints once the code settles" | Code settles around whatever was allowed while it was moving |
+| "The tests are the constraints" | Tests you wrote prove you agree with yourself; they say nothing about coverage of new code, dependency risk, or bundle growth |
+| "We can't hit 80% coverage" | Then don't set 80%. Set today's number and hold it |
+| "This will slow the agent down" | Only if you put slow checks in the fast loop. That's a placement error, not an argument against constraints |
+| "I'll remember what our standards are" | The agent won't, and it's writing most of the code |
+| "Constraints will block us shipping" | An exception with an owner and a date unblocks you. Deleting the constraint unblocks everyone forever |
+
+## Red Flags
+
+Stop and reconsider if you notice:
+
+- The interview ran past four questions, or produced a config the user can't explain
+- A budget was set that the codebase fails today, with no plan to reach it
+- A dimension was written into CONSTRAINTS.md with a number but no tool behind it
+- A checker was hand-rolled when a de facto one exists, so the team's existing config is ignored
+- Every constraint is checked by the project's own test suite, with no external opinion
+- `CONSTRAINTS.md` changed in the same commit as the feature that was failing
+- An exception has no owner, or an expiry more than a year out
+- The agent proposed relaxing a threshold instead of fixing the code
+- Slow checks landed in the edit loop and someone has started passing `--no-verify`
+- Nobody has opened `CONSTRAINTS.md` since it was written
+
+## Verification
+
+The skill was applied correctly when:
+
+- [ ] `CONSTRAINTS.md` exists, and every number in it has a stated reason
+- [ ] The floor is enforced and passes on the current codebase without changes
+- [ ] Every dimension the user picked has a tool installed and a command that runs today
+- [ ] Each constraint says where it runs, and the fast stage stays under a few seconds
+- [ ] At least one constraint is external (not judged by this project's own tests)
+- [ ] Measured-only metrics record today's value and a direction
+- [ ] Exceptions have an owner and an expiry date
+- [ ] `AGENTS.md` or `CLAUDE.md` points at the file
+- [ ] A trial run on the current branch produces no failures the user disagrees with
+
+## See Also
+
+- `interview-me` — the one-question-at-a-time discipline this skill's intake borrows
+- `code-review-and-quality` — how to review; this skill decides what the review enforces
+- `ci-cd-and-automation` — building the pipeline these constraints run in
+- `test-driven-development` — the suite that coverage and mutation constraints measure
+- `security-and-hardening` — what the security dimension should contain
+- `performance-optimization` — where the performance numbers come from