@warnyin/sdlc 0.1.0

package/payload/playbook/new.md

@@ -0,0 +1,22 @@
+# /sdlc:new <title> — open a change (Requirements)
+
+1. Triage the tier with `sdlc/harness.md § Tier triage`. Hard-floor surface
+   (security, payments, data-loss, irreversible) forces `deep` — no override
+   without an explicit user instruction (record it in Assumptions).
+2. Create `sdlc/changes/<kebab-id>/change.md` from the tier's template at
+   `sdlc/.playbook/templates/change-{vibe|standard|deep}.md` — copy the
+   structure exactly, respect the cap comment.
+3. Ground the delta: grep `## Purpose` of every `sdlc/specs/*/spec.md`; open the
+   FULL spec only for capabilities this change touches. Name each `## Delta:`
+   after an existing capability, or a new kebab-case capability.
+4. Write Why (≤5 lines, no solutioning) and the Delta requirements
+   (`ADDED/MODIFIED/REMOVED Requirement` + WHEN/THEN scenarios — grammar in the
+   delta-spec-format skill). Then Tasks with `[P]` and `[tier:x]` markers.
+5. Ambiguity policy (AI-driven): make the safest assumption and record it under
+   `## Assumptions` with why it is safe. Use `[NEEDS CLARIFICATION: q]` ONLY for
+   facts you cannot obtain or safely assume — then ask the user those questions
+   now, in one batch, and resolve every marker.
+6. `node sdlc/.hooks/journal.mjs set-active <id>` then
+   `npx @warnyin/sdlc validate <id>` — fix errors. Status stays `new`.
+
+Next: deep tier or risky decision → /sdlc:design; otherwise /sdlc:contract.

package/payload/playbook/next.md

@@ -0,0 +1,12 @@
+# /sdlc:next — where am I, what now (read-only)
+
+1. Run `npx @warnyin/sdlc status`.
+2. For each active change map status → next command:
+   - `new` + markers unresolved → resolve questions (playbook new.md §5)
+   - `new` (clean) → /sdlc:design (deep/signal) or /sdlc:contract
+   - `contracted` → /sdlc:build
+   - `building` → /sdlc:build (finish open tasks)
+   - `verified` → /sdlc:review (if signals) or /sdlc:ship
+3. If nothing is active: suggest /sdlc:new, or /sdlc:observe if archived changes
+   have unread digests.
+4. Answer in ≤5 lines. Create or modify nothing.

package/payload/playbook/observe.md

@@ -0,0 +1,20 @@
+# /sdlc:observe — cost, flow, and drift report
+
+1. Run `npx @warnyin/sdlc observe --json` and render it for the human. Do not
+   recompute anything the CLI already computed.
+2. Report, in this order (skip empty sections):
+   - **Pending digests** — archived changes whose digest the human has not been
+     shown yet (learner proposals awaiting a decision).
+   - **Cost** — tokens/cost per active + recent change; retry waste (tokens spent
+     after the first verify fail).
+   - **Flow** — lead time per shipped change and per-phase breakdown (created →
+     contracted → built → verified → shipped timestamps from the journal);
+     AI-time vs wait-time; first-pass success trend.
+   - **Residency** — always-loaded lines vs the 60 budget.
+   - **Drift flags** — steering never hit by a pointer, rules never triggering a
+     guard event, `compact` events (context overflow = a defect), specs touched
+     by many changes (converge candidates).
+3. For each flag, offer the one-line fix (`/sdlc:steer` demotion, `/sdlc:converge`
+   on a capability, cap adjustment) — recommend, never auto-apply here.
+
+Read-only: this command changes nothing.

package/payload/playbook/principles.md

@@ -0,0 +1,28 @@
+# Principles
+
+## Factory model
+Your output is the system that produces code — specs, contracts, gates, feedback loops,
+guardrails — not the code itself. Give agents success criteria, not step-by-step
+instructions, then let them iterate. Humans set policy once (`/sdlc:init`) and read
+ship digests asynchronously; they are interrupted only by policy-listed exceptions.
+
+## Economics (CapEx / OpEx)
+Configuration (constitution, harness, steering, contracts) is CapEx: paid once, reviewed
+like code. Every resident line of context is OpEx paid in every turn. Therefore:
+- Every mandatory artifact has a stated reason and a line cap (see template comments).
+- No artifact may restate another; deltas are merged mechanically, never re-narrated.
+- Retry loops are the expensive failure mode — contracts up front buy first-pass success.
+
+## Anti-garbage rules
+- Optional artifacts (design section, evals for standard tier) exist only on signal.
+- If a section would be empty, delete the section — never keep placeholder prose.
+- The learner may only ADD an always-loaded rule by displacing an old one (fixed budget).
+- Machine data (journals, state, learning stats) never lives in prose files.
+
+## Verification stance
+Tests verify the deterministic; evals verify trajectory and quality. Both are written
+before code — together they are the contract with the AI. "Seems to work" is not a gate.
+
+## Minimalism
+Prefer: do nothing → stdlib → existing dependency → smallest new code. Never cut:
+trust-boundary validation, data-loss handling, security controls, the contract itself.

package/payload/playbook/review.md

@@ -0,0 +1,17 @@
+# /sdlc:review <id> — agent panel (signal-triggered)
+
+Run when: tier deep, OR the diff touches auth/payments/data handling, OR >10
+files changed. Otherwise skip silently — a ceremonial review is garbage.
+
+1. Fan out in parallel, all read-only, each with the diff + change.md only:
+   - `sdlc-architect` (deepest): design integrity, coupling, contract drift.
+   - `sdlc-security` (balanced): injection, authz, secrets, unsafe deps.
+   - `sdlc-quality` (cheap): contract coverage gaps, edge cases, dead code.
+   - `sdlc-ops` (cheap): config, migrations, rollback, observability impact.
+2. Merge findings in the main loop. Classify: blocker | improvement | note.
+3. Blockers → append as fix tasks and route back to /sdlc:build (counts toward
+   the same 3-round budget as verify). Improvements: apply if ≤5 min each,
+   otherwise record one line in the change for the digest.
+4. `node sdlc/.hooks/journal.mjs note review blockers=<n>`.
+
+Pass condition: zero open blockers. Next: /sdlc:ship.

package/payload/playbook/routing.md

@@ -0,0 +1,19 @@
+# Model routing
+
+Generic tiers only — the harness adapter maps them to real models
+(Claude Code agents: cheap→haiku, balanced→sonnet, deepest→opus).
+
+| Task kind | Tier | Why |
+|---|---|---|
+| requirements shaping, architecture, deep design | deepest | judgment-heavy, small volume |
+| standard implementation (sdlc-builder) | balanced | quality/cost sweet spot |
+| test generation (sdlc-contractor) | cheap | mechanical from the contract table |
+| eval judging (sdlc-evaluator) | cheap | rubric scoring, high volume |
+| review panel passes | cheap–balanced | parallel, bounded scope |
+| learning distillation (sdlc-learner) | cheap | summarization over journals |
+
+Rules:
+- Task lines in change.md may carry `[tier:cheap|balanced|deepest]`; default = balanced.
+- Never send a mechanical task to deepest "to be safe" — that is the waste the
+  routing table exists to prevent.
+- Escalate one tier only after a concrete failure at the current tier (journal it).

package/payload/playbook/rules-card.md

@@ -0,0 +1,16 @@
+# sdlc rules card
+<!-- ≤40 lines · embedded verbatim in non-Claude tool adapters; Claude gets the same rules enforced by hooks. -->
+
+- Work flows through `sdlc/changes/<id>/change.md`: new → [design] → contract → build → verify → [review] → ship.
+- NEVER edit `sdlc/specs/**` or `sdlc/changes/archive/**` by hand. Living specs change only
+  via a change's `## Delta:` section, merged by `npx @warnyin/sdlc archive <id>` at ship.
+- NEVER hand-edit `journal.ndjson` or `sdlc/.state/**` — they are machine-owned.
+- Write tests + evals (`contract/`) BEFORE code. No implementation while status is `new`.
+- Ambiguity: make the safest assumption and record it under `## Assumptions`; use
+  `[NEEDS CLARIFICATION: q]` only for facts you cannot obtain — resolve all before contract.
+- Respect line caps written in each template comment; run `npx @warnyin/sdlc validate <id>`
+  before claiming any gate passed — a red validator means the gate did NOT pass.
+- Constitution edits go through /sdlc:steer only; always-loaded context ≤ 60 lines total.
+- Verify = real test run + eval rubric. Max 3 fix rounds, then escalate to the human.
+- Hard-floor (security, payments, data-loss, irreversible): tier = deep, human approves ship.
+- Before editing an area, read any steering file whose `pathMatch` covers it.

package/payload/playbook/ship.md

@@ -0,0 +1,24 @@
+# /sdlc:ship <id> — merge, archive, learn, digest
+
+Precondition: `status: verified` (+ review passed when it ran).
+
+1. **Policy check** (`sdlc/harness.md § Autonomy policy`): if this change is NOT
+   auto-shippable (deep/hard-floor), show the human a 5-line summary (why, delta
+   heads, verify result, cost so far) and wait for approval. Otherwise proceed.
+2. Open the gate and archive mechanically:
+   `node sdlc/.hooks/journal.mjs open-ship <id>`
+   `npx @warnyin/sdlc archive <id>`
+   (validates --strict, merges every Delta into `sdlc/specs/`, promotes evals,
+   stamps `status: shipped`, moves the folder to `changes/archive/<date>-<id>/`).
+3. **Learn** — delegate to `sdlc-learner` (cheap) with the archived change.md +
+   its journal.ndjson. It proposes ≤3 items: add-rule (with evidence pointer) /
+   expire-or-demote (rule or steering that never fired) / harness tweak.
+   Apply reductions and demotions immediately (they always save tokens).
+   Additions to always-loaded context are NOT applied — list them in the digest.
+4. **Digest** — write `sdlc/changes/archive/<date>-<id>/digest.md` (≤15 lines):
+   what shipped, spec deltas merged, assumptions made, verify rounds, tokens/cost
+   (from journal `session` events), learner proposals awaiting the human.
+5. Close the gate: `node sdlc/.hooks/journal.mjs close`. Tell the user in one
+   line: shipped + where the digest is.
+
+The digest is the async human touchpoint — reviewable and revertible later.

package/payload/playbook/steer.md

@@ -0,0 +1,21 @@
+# /sdlc:steer — manage the static/dynamic boundary
+
+The ONLY sanctioned way to edit always-loaded context.
+
+1. `node sdlc/.hooks/journal.mjs open-steer`
+2. Apply the requested edits:
+   - New knowledge → a steering file with the LEAST resident inclusion mode that
+     works: `agent` > `manual` > `paths` > `always` (always needs justification).
+   - Constitution edits: SHALL/SHALL NOT lines only. If the always-budget
+     (60 lines) would overflow, something must be demoted or deleted first —
+     name the displaced line explicitly.
+3. Hygiene pass (do it every time, it is 30 seconds):
+   - `/sdlc:observe` data — steering never pointer-hit across the last N changes
+     → propose demote (`paths`→`manual`) or delete.
+   - Rules with no guard/journal evidence of ever mattering → propose expiry.
+   - Apply what the user agrees to (reductions may be applied without asking).
+4. `npx @warnyin/sdlc validate` — the always-budget check must be green.
+5. `node sdlc/.hooks/journal.mjs close`
+
+Learning direction is one-way by design: content flows from always → paths →
+manual → deleted as evidence accumulates. Getting leaner is the success metric.

package/payload/playbook/verify.md

@@ -0,0 +1,24 @@
+# /sdlc:verify <id> — the feedback loop
+
+Two halves, both must pass. Verification is against the CONTRACT, not vibes.
+
+1. **Tests (deterministic)**: run the full test command from `sdlc/harness.md`.
+   Every row of `contract/tests.md` must be covered by a passing test.
+2. **Evals (non-deterministic)** — when `contract/evals.md` exists: delegate to
+   the `sdlc-evaluator` agent (cheap) with the rubric + the diff + the task log;
+   it returns a score per rubric line. Pass bar is written in the file.
+
+On failure:
+- Cluster failures by root cause (one line each) and append the cluster note to
+  the change's `## Tasks` area as unchecked fix tasks.
+- `node sdlc/.hooks/journal.mjs note verify result=fail round=<n>`
+- Route back to /sdlc:build. Maximum 3 rounds total; on the 4th failure STOP and
+  escalate to the human with the cluster history (Autonomy policy condition).
+- Never lower the bar: do not edit tests/evals to pass unless the contract
+  itself was wrong — changing the contract reopens the adversarial check.
+
+On pass: set `status: verified`,
+`node sdlc/.hooks/journal.mjs note verify result=pass round=<n>`.
+
+Next: review signals present (deep tier, security-touching diff, >10 files)
+→ /sdlc:review; otherwise → /sdlc:ship.

package/payload/templates/change-deep.md

@@ -0,0 +1,29 @@
+---
+id: <kebab-id>
+tier: deep
+status: new
+---
+# Change: <title>
+<!-- cap:150 · deep tier: hard-floor surface (security/payments/data-loss/irreversible) or new/multi-capability delta. Human gates apply per Autonomy policy. -->
+
+## Why (≤5 lines)
+<problem + outcome. No solutioning.>
+
+## Assumptions
+- <assumption made instead of asking, with the reason it is safe>
+
+## Delta: <capability>
+
+### ADDED Requirement: <name>
+The system SHALL <behavior>.
+
+#### Scenario: <name>
+- WHEN <condition>
+- THEN <observable outcome>
+
+## Design
+<!-- decisions & trade-offs only — never restate the delta. Escalate irreversible decisions per Autonomy policy. -->
+- decision: <what> · alternatives: <a/b> · because: <why>
+
+## Tasks
+- [ ] T1 <task> [P] [tier:balanced]

package/payload/templates/change-standard.md

@@ -0,0 +1,28 @@
+---
+id: <kebab-id>
+tier: standard
+status: new
+---
+# Change: <title>
+<!-- cap:100 · standard tier. Delta sections ARE the spec change — merged mechanically at ship, never re-narrated. -->
+
+## Why (≤5 lines)
+<problem + outcome. No solutioning.>
+
+## Assumptions
+- <assumption made instead of asking, with the reason it is safe — delete section if none>
+<!-- unresolved ambiguity the agent cannot assume → [NEEDS CLARIFICATION: question] inline where it bites -->
+
+## Delta: <capability>
+
+### ADDED Requirement: <name>
+The system SHALL <behavior>.
+
+#### Scenario: <name>
+- WHEN <condition>
+- THEN <observable outcome>
+
+## Tasks
+<!-- [P] = parallelizable wave · [tier:cheap|balanced|deepest] per the routing table in harness.md -->
+- [ ] T1 <task> [P] [tier:balanced]
+- [ ] T2 <task> [tier:cheap]

package/payload/templates/change-vibe.md

@@ -0,0 +1,19 @@
+---
+id: <kebab-id>
+tier: vibe
+status: new
+---
+# Change: <title>
+<!-- cap:40 · vibe tier = one file, no contract. Reversible, no behavior-contract change, ≤2 files. -->
+
+## Why (≤3 lines)
+<problem + outcome>
+
+## Assumptions
+- <assumption the agent made instead of asking — delete section if none>
+
+## Tasks
+- [ ] T1 <task>
+
+## Receipt (filled at ship)
+- files touched: · test result: · cost:

package/payload/templates/config.yaml

@@ -0,0 +1,8 @@
+# @warnyin/sdlc project config — machine-read; keep minimal.
+language: en
+tools: []            # filled by `warnyin-sdlc init`
+# Optional price table for cost reporting (USD per 1M tokens).
+# prices:
+#   claude-sonnet-5: { input: 3, output: 15, cacheRead: 0.3 }
+# Optional per-artifact cap overrides (see lib/caps.mjs for defaults).
+# caps: {}

package/payload/templates/constitution.md

@@ -0,0 +1,14 @@
+# Constitution — <project>
+<!-- cap:30 · ALWAYS LOADED: every line here costs tokens in EVERY turn. Prove residency or move it to steering. -->
+
+## Stack (facts only, max 3 lines)
+- <runtime / framework / db — one line each>
+
+## Hard rules (SHALL / SHALL NOT only — no advice)
+- The agent SHALL NOT edit `sdlc/specs/**` or `sdlc/changes/archive/**` outside `/sdlc:ship`.
+- The agent SHALL record every assumption in the change's `## Assumptions` before acting on it.
+- <add a rule each time the agent misbehaves; each new rule must displace an old one once the always-budget (60 lines) is full>
+
+## Workflow
+- Changes flow: new → [design] → contract → build → verify → [review] → ship.
+- Tier by stakes: vibe | standard | deep — triage table lives in `sdlc/harness.md`.

package/payload/templates/contract-evals.md

@@ -0,0 +1,9 @@
+# Eval contract — <change-id>
+<!-- cap:40 · verifies the non-deterministic half: trajectory + quality. Scored by sdlc-evaluator (cheap tier). -->
+
+## Rubric (score 1–5 each)
+- Trajectory: did the agent read the contract before writing code? run tests before claiming done?
+- Quality: <change-specific bars>
+
+## Pass bar
+- all scores ≥ 4 · failures route back to `/sdlc:build` with a cluster note

package/payload/templates/contract-tests.md

@@ -0,0 +1,9 @@
+# Test contract — <change-id>
+<!-- cap:60 · written BEFORE code. This is the deterministic half of the contract with the AI; failing tests are generated from this table. -->
+
+| # | Given / When / Then | Kind (unit/int/e2e) | Maps to requirement |
+|---|---|---|---|
+| 1 | <g/w/t> | unit | <requirement name> |
+
+## Out of scope (explicitly untested + why)
+- <item — reason>

package/payload/templates/harness.md

@@ -0,0 +1,33 @@
+# Harness — <project>
+<!-- cap:60 · CONFIGURE-phase output; reviewed like code. Registry + tables only — doctrine lives in sdlc/.playbook/. -->
+
+## Tools & MCP (what the agent may call)
+| Tool/MCP | Scope | Notes |
+|---|---|---|
+| <tool> | <what it may touch> | <when to use> |
+
+## Sandbox & execution
+- test command: `<cmd>`
+- sandbox notes: <where code runs, what it cannot reach>
+
+## Guardrails (mirror of installed hooks — deterministic, the agent cannot skip them)
+- `sdlc/specs/**` and archive are write-locked outside ship.
+- Artifact line caps validated on every write.
+- Session token/cost journaled per change.
+
+## Model routing (generic tiers — the harness adapter maps them to real models)
+| Task kind | Tier |
+|---|---|
+| requirements, architecture, deep design | deepest |
+| standard implementation | balanced |
+| test generation, review passes, mechanical/scaffold, eval judging, learning | cheap |
+
+## Tier triage (stakes → tier)
+- vibe: reversible, no behavior-contract change, ≤2 files.
+- deep: security / payments / data-loss / irreversible surface, new capability, or multi-capability delta.
+- otherwise: standard.
+
+## Autonomy policy
+- auto-ship: vibe, standard.
+- escalate to human: hard-floor (security, payments, data-loss, irreversible), verify failed > 3 rounds,
+  token budget exceeded, information the agent cannot obtain or safely assume.

package/payload/templates/spec.md

@@ -0,0 +1,14 @@
+# Spec: <capability>
+<!-- cap:150 (soft) · living spec — observable behavior only, no implementation detail. Split the capability beyond the cap. -->
+
+## Purpose
+<!-- one or two lines; commands grep this header first (progressive disclosure) -->
+
+## Requirements
+
+### Requirement: <name>
+The system SHALL <behavior>.
+
+#### Scenario: <name>
+- WHEN <condition>
+- THEN <observable outcome>

package/payload/templates/steering.md

@@ -0,0 +1,9 @@
+---
+name: <topic>
+inclusion: paths            # always | paths | manual | agent
+pathMatch: ["src/<area>/**"]
+---
+# Steering: <topic>
+<!-- cap:40 · loaded only when pathMatch hits or explicitly requested. Dense, scoped conventions — no generalities. -->
+
+<conventions, gotchas, and reference patterns for this scope>

package/scripts/validate.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+// Thin CLI wrapper — validator core lives in lib/validate.mjs so that
+// installed hooks (sdlc/.hooks/lib/) can share the exact same logic.
+// Exit codes: 0 = clean, 1 = errors, 2 = usage/setup error.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { validateAll, formatIssues } from '../lib/validate.mjs';
+
+export * from '../lib/validate.mjs';
+
+function main() {
+  const args = process.argv.slice(2);
+  const strict = args.includes('--strict');
+  const rootIdx = args.indexOf('--root');
+  const projectRoot = rootIdx !== -1 ? args[rootIdx + 1] : process.cwd();
+  const positional = args.filter((a, i) => !a.startsWith('--') && args[i - 1] !== '--root');
+  const changeId = positional[0] && positional[0] !== '--all' ? positional[0] : null;
+
+  const sdlcRoot = path.join(projectRoot, 'sdlc');
+  if (!fs.existsSync(sdlcRoot)) {
+    console.error(`No sdlc/ directory at ${projectRoot} — run \`npx @warnyin/sdlc init\` first.`);
+    process.exit(2);
+  }
+
+  const issues = validateAll(sdlcRoot, { strict, changeId });
+  if (issues.length) console.log(formatIssues(issues));
+  const errors = issues.filter((i) => i.level === 'error').length;
+  const warns = issues.length - errors;
+  console.log(`validate: ${errors} error(s), ${warns} warning(s)${strict ? ' [strict]' : ''}`);
+  process.exit(errors > 0 ? 1 : 0);
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main();
+}