@brunosps00/dev-workflow 2.2.0 → 2.4.0

package/scaffold/scripts/lib/workflow-contract.mjs

@@ -0,0 +1,101 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
+
+const tools = new Set(['local', 'codex', 'claude', 'copilot']);
+const tiers = new Set(['light', 'standard', 'heavy']);
+
+// A small executable contract for the agent-authored execution-plan.json.
+// This validates assignments, not account access or authorization on its own.
+export function validatePlan(plan) {
+  const issues = [];
+  if (!plan || !['1.0', '1.1'].includes(plan.schema_version)) return ['Unsupported execution plan schema'];
+  if (!Array.isArray(plan.tasks) || !plan.tasks.length) return ['tasks must be a nonempty array'];
+  if (typeof plan.approved !== 'boolean') issues.push('approved must be a boolean');
+  const ids = new Set();
+  for (const task of plan.tasks) {
+    if (!task || typeof task.id !== 'string' || !task.id.trim()) {
+      issues.push('Every task needs a nonempty string id');
+      continue;
+    }
+    if (ids.has(task.id)) issues.push(`Duplicate task ${task.id}`);
+    ids.add(task.id);
+    if (!Array.isArray(task.depends_on) || task.depends_on.some(id => typeof id !== 'string')) issues.push(`${task.id}: depends_on must be a string array`);
+    if (plan.schema_version === '1.1' && !task.execution) issues.push(`${task.id}: missing execution assignment`);
+    if (task.execution) {
+      const e = task.execution;
+      if (typeof e !== 'object' || Array.isArray(e)) { issues.push(`${task.id}: execution must be an object`); continue; }
+      if (!tiers.has(e.complexity)) issues.push(`${task.id}: invalid complexity`);
+      if (typeof e.rationale !== 'string' || !e.rationale.trim()) issues.push(`${task.id}: missing rationale`);
+      if (!Array.isArray(e.agents) || e.agents.some(a => typeof a !== 'string')) issues.push(`${task.id}: agents must be a string array`);
+      for (const assignment of [e, ...(Array.isArray(e.fallbacks) ? e.fallbacks : [])]) {
+        if (!assignment || typeof assignment !== 'object' || Array.isArray(assignment)) { issues.push(`${task.id}: invalid fallback assignment`); continue; }
+        if (!tools.has(assignment.tool)) issues.push(`${task.id}: invalid tool`);
+        if (typeof assignment.model !== 'string' || !assignment.model.trim()) issues.push(`${task.id}: missing model`);
+        if (typeof assignment.effort !== 'string' || !assignment.effort.trim()) issues.push(`${task.id}: missing effort`);
+        if (assignment.tool !== 'local' && [assignment.model, assignment.effort].includes('inherit')) issues.push(`${task.id}: external assignments must resolve model and effort`);
+      }
+      if (e.fallbacks !== undefined && !Array.isArray(e.fallbacks)) issues.push(`${task.id}: fallbacks must be an array`);
+    }
+  }
+  const tasks = new Map(plan.tasks.filter(t => t?.id).map(t => [t.id, t]));
+  const visiting = new Set(), visited = new Set();
+  function visit(id) {
+    if (visiting.has(id)) { issues.push(`Dependency cycle at ${id}`); return; }
+    if (visited.has(id)) return;
+    visiting.add(id);
+    for (const dep of tasks.get(id)?.depends_on || []) {
+      if (!ids.has(dep)) issues.push(`${id}: unknown dependency ${dep}`);
+      else visit(dep);
+    }
+    visiting.delete(id); visited.add(id);
+  }
+  if (!issues.length) for (const id of ids) visit(id);
+  return issues;
+}
+
+export function resolveAssignment(plan, taskId, availableTools) {
+  const issues = validatePlan(plan);
+  if (issues.length) throw new Error(issues.join('; '));
+  if (plan.approved !== true) throw new Error('Execution plan is not approved');
+  const task = plan.tasks.find(t => t.id === taskId);
+  if (!task) throw new Error(`Unknown task ${taskId}`);
+  // Legacy plans never imply permission to start another CLI.
+  const assignment = task.execution || { tool: 'local', model: 'inherit', effort: 'inherit', agents: [] };
+  const candidates = [assignment, ...(assignment.fallbacks || [])];
+  const chosen = candidates.find(c => availableTools.includes(c.tool));
+  if (!chosen) throw new Error(`No approved executor available for ${taskId}`);
+  return { ...chosen, agents: assignment.agents || [], fallback: chosen !== assignment };
+}
+
+export function readyTasks(plan, completedIds) {
+  const issues = validatePlan(plan);
+  if (issues.length) throw new Error(issues.join('; '));
+  const done = new Set(completedIds);
+  return plan.tasks.filter(t => !done.has(t.id) && t.depends_on.every(id => done.has(id))).map(t => t.id);
+}
+
+// Callers fingerprint actual inputs (including relevant untracked files) and
+// environment. Unknown values fail closed. Time/message boundaries are irrelevant.
+export function reusableEvidence(evidence, current) {
+  if (!evidence || evidence.exit_code !== 0 || !current) return false;
+  for (const key of ['command', 'input_fingerprint', 'environment_fingerprint']) {
+    if (typeof current[key] !== 'string' || !current[key] || evidence[key] !== current[key]) return false;
+  }
+  return Array.isArray(current.scope) && current.scope.length > 0 && Array.isArray(evidence.scope)
+    && current.scope.every(item => evidence.scope.includes(item));
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    const [mode, file, taskId, available = 'local'] = process.argv.slice(2);
+    if (!['validate', 'resolve', 'ready'].includes(mode) || !file) throw new Error('Usage: workflow-contract.mjs validate|resolve|ready <plan.json> [task-id|completed-csv] [available-tools-csv]');
+    const plan = JSON.parse(readFileSync(file, 'utf8'));
+    if (mode === 'validate') {
+      const issues = validatePlan(plan);
+      console.log(JSON.stringify({ status: issues.length ? 'BLOCKED' : 'PASS', issues }));
+      if (issues.length) process.exitCode = 1;
+    } else if (mode === 'resolve') console.log(JSON.stringify(resolveAssignment(plan, taskId, available.split(','))));
+    else console.log(JSON.stringify(readyTasks(plan, taskId ? taskId.split(',') : [])));
+  } catch (error) { console.error(error.message); process.exitCode = 1; }
+}

package/scaffold/skill-registry.json

@@ -9,7 +9,7 @@
       "trigger": "API QA, endpoint testing, HTTP recipe generation",
       "expected_output": "A selected API testing recipe and evidence path for the active stack.",
       "load_policy": "lazy-references",
-      "context_limit": 12000,
+      "context_limit": 8000,
       "invocation": "explicit",
       "exportable": true,
       "bundled": true
@@ -22,20 +22,32 @@
       "trigger": "Docker Compose service selection or local infrastructure setup",
       "expected_output": "A selected service recipe and composition guidance.",
       "load_policy": "lazy-references",
-      "context_limit": 12000,
+      "context_limit": 8000,
       "invocation": "explicit",
       "exportable": true,
       "bundled": true
     },
+    {
+      "name": "dw-chaos-engineering",
+      "kind": "protocol",
+      "tier": "specialty",
+      "owner": "manual,dw-qa,dw-review",
+      "trigger": "Explicit request to adversarially test or stress an implemented change",
+      "expected_output": "Chaos report with per-attack classification, minimal repros, and the routing of each finding.",
+      "load_policy": "lazy-references",
+      "context_limit": 8000,
+      "invocation": "explicit",
+      "bundled": true
+    },
     {
       "name": "dw-cli-run",
       "kind": "protocol",
       "tier": "core",
       "owner": "dw-codex-run,dw-claude-run,dw-copilot-run",
-      "trigger": "Fire an AI CLI (Codex/Claude/Copilot) in a dedicated git worktree to implement a prepared prompt; resumable per-task session; STOP for the gate",
-      "expected_output": "Audit-logged run with a 0-10 dual evaluation, a resumable session-id sidecar, and a STOP-for-gate Structured Return.",
+      "trigger": "Execute an approved task through a supported external CLI adapter",
+      "expected_output": "Reviewed task handoff with durable session, acceptance evidence and next task or blocker.",
       "load_policy": "lazy-references",
-      "context_limit": 20500,
+      "context_limit": 8000,
       "bundled": true
     },
     {
@@ -46,7 +58,7 @@
       "trigger": "Codebase indexing or codebase intelligence query",
       "expected_output": ".dw/intel index files or a cited answer from the index.",
       "load_policy": "lazy-references",
-      "context_limit": 12000,
+      "context_limit": 8000,
       "bundled": true
     },
     {
@@ -57,7 +69,7 @@
       "trigger": "Council mode or high-impact architectural debate",
       "expected_output": "Advisor positions, tension synthesis, and decision recommendation.",
       "load_policy": "lazy-references",
-      "context_limit": 12000,
+      "context_limit": 8000,
       "bundled": true
     },
     {
@@ -68,7 +80,7 @@
       "trigger": "Native Grill domain vocabulary: challenge fuzzy/overloaded terms, cross-check against code, persist a canonical glossary to .dw/domain",
       "expected_output": "Canonical terms with discouraged synonyms persisted lazily to .dw/domain (single or multi-context), or fuzzy-term findings.",
       "load_policy": "lazy-references",
-      "context_limit": 12000,
+      "context_limit": 8000,
       "exportable": false,
       "bundled": true
     },
@@ -80,7 +92,7 @@
       "trigger": "Native Grill decision-tree interview: sharpen a plan/PRD to shared understanding, exactly one decision per turn with a recommended answer",
       "expected_output": "A dependency-ordered decision tree, resolved decisions with recommendations, and an explicit shared-understanding gate.",
       "load_policy": "lazy-references",
-      "context_limit": 12000,
+      "context_limit": 8000,
       "exportable": false,
       "bundled": true
     },
@@ -92,7 +104,7 @@
       "trigger": "Bugfix, QA fix loop, or non-reproducible failure",
       "expected_output": "Six-step triage, root cause, guard, and verification path.",
       "load_policy": "lazy-references",
-      "context_limit": 12000,
+      "context_limit": 8000,
       "bundled": true
     },
     {
@@ -103,7 +115,7 @@
       "trigger": "Task execution, plan-checking, waves, checkpoint recovery",
       "expected_output": "Plan-check verdict, wave execution report, or checkpoint summary.",
       "load_policy": "lazy-references",
-      "context_limit": 12000,
+      "context_limit": 8000,
       "bundled": true
     },
     {
@@ -114,7 +126,7 @@
       "trigger": "Commit creation, branch hygiene, PR generation",
       "expected_output": "Atomic commit plan and git hygiene checks.",
       "load_policy": "lazy-references",
-      "context_limit": 12000,
+      "context_limit": 8000,
       "bundled": true
     },
     {
@@ -125,7 +137,7 @@
       "trigger": "Production critical bug, outage, incident, SEV workflow",
       "expected_output": "Incident triage, communication, resolution, and postmortem artifacts.",
       "load_policy": "lazy-references",
-      "context_limit": 12000,
+      "context_limit": 8000,
       "bundled": true
     },
     {
@@ -136,7 +148,7 @@
       "trigger": "AI, LLM, RAG, classifier, agent, or tool-use feature",
       "expected_output": "Eval strategy, oracle choice, dataset requirements, and result checks.",
       "load_policy": "lazy-references",
-      "context_limit": 12000,
+      "context_limit": 8000,
       "bundled": true
     },
     {
@@ -147,7 +159,7 @@
       "trigger": "Task execution memory, checkpointing, compaction",
       "expected_output": "Updated workflow memory and task-local memory guidance.",
       "load_policy": "lazy-references",
-      "context_limit": 12000,
+      "context_limit": 8000,
       "bundled": true
     },
     {
@@ -171,7 +183,7 @@
       "trigger": "Code review, implementation review, or review consolidation",
       "expected_output": "Deduplicated findings ordered by defensible severity.",
       "load_policy": "always-small",
-      "context_limit": 12000,
+      "context_limit": 8000,
       "bundled": true
     },
     {
@@ -205,7 +217,7 @@
       "trigger": "Refactor analysis, code smells, complexity, or behavior-preserving simplification",
       "expected_output": "Simplification target, risk, behavior-preserving checks, and recommendation.",
       "load_policy": "lazy-references",
-      "context_limit": 12000,
+      "context_limit": 8000,
       "exportable": true,
       "bundled": true
     },
@@ -217,7 +229,7 @@
       "trigger": "Library/framework/API decision, technical research, dependency audit",
       "expected_output": "Cited source-grounded decision with version and retrieval date.",
       "load_policy": "lazy-references",
-      "context_limit": 12000,
+      "context_limit": 8000,
       "bundled": true
     },
     {
@@ -228,7 +240,7 @@
       "trigger": "Writing, reviewing, or debugging tests",
       "expected_output": "Test placement, invariant, anti-pattern checks, and verification guidance.",
       "load_policy": "lazy-references",
-      "context_limit": 12000,
+      "context_limit": 8000,
       "bundled": true
     },
     {
@@ -239,7 +251,7 @@
       "trigger": "UI design, redesign, visual QA, accessibility, or frontend polish",
       "expected_output": "Grounding answers, state matrix, accessibility checks, and visual risks.",
       "load_policy": "lazy-references",
-      "context_limit": 12000,
+      "context_limit": 8000,
       "bundled": true
     },
     {
@@ -250,7 +262,7 @@
       "trigger": "Completion claim, commit, PR generation, or fixed bug status",
       "expected_output": "Fresh verification report with cited command evidence.",
       "load_policy": "always-small",
-      "context_limit": 12000,
+      "context_limit": 8000,
       "exportable": true,
       "bundled": true
     },
@@ -288,7 +300,7 @@
       "trigger": "Security review, sensitive code, OWASP checks, auth/payment/input surfaces",
       "expected_output": "High-confidence security findings or explicit pass.",
       "load_policy": "lazy-references",
-      "context_limit": 14000,
+      "context_limit": 8000,
       "exportable": true,
       "bundled": true
     },
@@ -300,7 +312,7 @@
       "trigger": "React/Next.js performance, hydration, data fetching, bundle or render issues",
       "expected_output": "Selected performance rule references and metric-driven recommendations.",
       "load_policy": "lazy-references",
-      "context_limit": 12000,
+      "context_limit": 8000,
       "invocation": "explicit",
       "exportable": true,
       "bundled": true

package/scaffold/skills/dw-chaos-engineering/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: dw-chaos-engineering
+description: Use to adversarially test a change you just implemented. Maps the attack surface, writes tests that try to break it, classifies each KILLED/SURVIVED/INCONCLUSIVE. Local only, writes tests only, 3 rounds max. Ask for it by name.
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Grep
+  - Glob
+---
+
+# Chaos Engineering
+
+> Adapted from the chaos-engineering skill in [`samsantosb/ship-it`](https://github.com/samsantosb/ship-it)
+> (MIT © Samuel Santos). The vector catalogue and the KILLED/SURVIVED/INCONCLUSIVE vocabulary come from
+> there; target resolution, criticality anchoring and finding routing are rewritten for `.dw/`.
+
+Where the rest of the pipeline builds, this tries to break. It takes a change that is already implemented
+and writes tests whose only purpose is to prove it fails.
+
+**An attack that SURVIVED is also a result.** The goal is not bugs at any cost — it is mapping where the
+code holds and where it gives, and leaving the tests that matter as regression inheritance.
+
+## When to use
+
+Invoked by name, never automatically — it writes files, runs the suite and costs real time. Ask for it
+after an implementation is complete and its normal tests pass: post-`/dw-run`, post-`/dw-bugfix`, or on an
+open PR before merge.
+
+Do not use it to find a known bug (that is `/dw-bugfix`), to review code (`/dw-review`), or on a change
+that has no tests yet — chaos measures resilience, it does not substitute for coverage.
+
+## Step 0 — Baseline gate
+
+**The target's existing tests must pass before any attack.** Run the project's configured suite scoped to
+the touched files.
+
+A red baseline stops the run. With a broken environment you cannot tell a finding from noise, and every
+subsequent classification is worthless. Report the failing baseline and stop — that is a `BLOCKED` outcome
+under `.dw/references/automode.md`, not a failed run.
+
+## Step 1 — Resolve the target
+
+First that exists: the PR diff · the local diff against the base branch · the files named in
+`.dw/spec/<prd>/tasks/` or `.dw/bugfixes/<slug>/TASK.md`. Only what changed is in scope — the rest of the
+repository is not the target.
+
+Read the acceptance criteria if the target has them. Every promise is attackable by negation.
+
+## Step 2 — Attack plan
+
+Cross the diff with `references/vector-catalog.md` and select the vectors that actually apply. Not every
+vector fits every diff; prioritize by impact × probability.
+
+**Criticality is anchored, not assumed.** `.dw/rules/concerns.md` (the Concerns Map) and
+`.dw/constitution.md` define what is critical *in this project*. Without them severity is opinion; with
+them, a finding against the thing the project protects is critical by definition.
+
+Show the plan before building: target, surface, selected vectors as hypotheses, and the vectors left out
+with one line each on why.
+
+## Step 3 — Build the arsenal
+
+Follow the project's test conventions and the `dw-testing-discipline` skill — it owns *how* a test is
+written (the anti-pattern catalogue, the agent guardrails, flaky discipline). This skill owns only the
+attack protocol.
+
+- One group per vector, one case per attack, named for the hypothesis rather than the implementation.
+- **Simulate hostility with mocks and fixtures.** The test describes a hostile world; it never depends on
+  a real one.
+- **Each attack asserts the CORRECT behaviour** — what the system should do under chaos — never the bug.
+  So a failing attack is a real finding, and the same test becomes a free regression once it is fixed.
+
+## Step 4 — Run and classify
+
+- **KILLED** — the attack broke it. Produce the minimal reproduction: the smallest hostile input that
+  still kills.
+- **SURVIVED** — the code held. A result, not a wasted test.
+- **INCONCLUSIVE** — the *test* is wrong (bad mock, flake, environment limit). Fix and rerun, at most
+  twice; still inconclusive after that, record it as such and drop it. Never inflate the report.
+
+**Round cap: 3.** The initial plan plus at most two deepening rounds on what killed or nearly did. The
+INCONCLUSIVE retry cap is independent — never burn a round chasing a verdict on a broken test.
+
+## Step 5 — Triage
+
+Severity comes from the criticality anchor, not from how alarming the input looked.
+
+Before sealing each finding, apply the **defense-lawyer test**: is there a reading where this behaviour is
+intentional — an ADR, a project rule, an adjacent comment? If yes, mark it `contestable` and record the
+doubt. The report separates fact from interpretation, the same way `dw-review-rigor` separates a finding
+from an unresolved lead.
+
+## Step 6 — Report and routing
+
+Report to `<target>/QA/chaos-report.md`, following the target convention `/dw-qa` already uses.
+
+Where each result goes:
+
+| Result | Destination |
+|---|---|
+| SURVIVED covering a real gap no existing test covered | Promote as a permanent regression |
+| KILLED on an open PR | Test ships **unskipped** — it blocks the merge on purpose, and `/dw-review` rejects |
+| KILLED on already-merged code | Open `.dw/bugfixes/NNN-slug/` via `/dw-bugfix`; never reopen the landed work |
+| SURVIVED but redundant, or INCONCLUSIVE | Discard. The arsenal is not an accumulation |
+
+## Hard limits
+
+- **Local only.** Never fire a request at staging, production or a partner API. A hostile world is
+  simulated, without exception.
+- **Tests only.** Production code is read-only here. Finding and fixing are separate roles by design.
+- **Three rounds.** Infinite chaos is procrastination with extra steps.
+- **No theatrical chaos**: no scenarios impossible by construction to pad the report, no asserting the
+  current buggy behaviour, and no calling KILLED when what broke was the mock or the clock.
+- Never leave a red test ownerless. A KILLED on an open PR blocks merge on purpose — that is the signal
+  working. A red suite with no report and no owner is sabotage.
+
+## Structured Return
+
+- **Status:** `PASS` when the run completed with no unfixed KILLED, `FINDINGS` when attacks killed, `BLOCKED` when the baseline is red or the target cannot be resolved, `NOT_APPLICABLE` when no implemented change is in scope.
+- **Scope:** target resolved, files attacked, vectors selected and vectors deliberately skipped.
+- **Evidence:** per-attack classification with the minimal reproduction for each kill, and the baseline result.
+- **Artifacts:** chaos report path, test files written, and where each shipped.
+- **Decisions:** vector selection, severity anchoring, and every `contestable` downgrade with its reading.
+- **Risks:** inconclusive attacks, vectors out of scope, and coverage the rounds did not reach.
+- **Next Step:** the fix route for each kill (`/dw-bugfix` or the PR's own branch), or merge-clean.

package/scaffold/skills/dw-chaos-engineering/references/vector-catalog.md

@@ -0,0 +1,43 @@
+# Vector catalogue
+
+Cross the diff with this list and pick what applies. Selecting every vector for every diff is how a chaos
+run turns into theatre — the skipped vectors, each with one line on why, are part of the plan.
+
+## Boundaries
+Zero · negative · `MAX_SAFE_INTEGER` and the language's numeric ceiling · empty, one, and N+1 · the
+off-by-one at a page or batch edge · leap day · a timezone that is not the author's · DST transition.
+
+## Nulls and absence
+An optional field omitted entirely (not sent as null) · `null` versus `undefined` where the code treats
+them alike · empty object versus missing object · a field the external API stopped returning.
+
+## Broken money
+Rounding at the cent · installments that do not sum to the total · negative amounts · a discount above
+100% · float arithmetic where decimal is required · currency mismatch · a refund larger than the payment.
+
+## Hostile dependencies
+The external API returns 500 · 429 with and without `Retry-After` · a timeout with no response at all ·
+truncated JSON · valid JSON with the wrong shape · the cache is down · a database deadlock · a job dies
+mid-flight leaving its work half-applied.
+
+## Concurrency and idempotency
+The same request submitted twice · a duplicated webhook · a job reprocessed after a retry · a cron racing
+a live request · two writers on the same row · a read between a check and its use.
+
+## Hostile payloads
+Emoji and combining characters · mixed encodings · a 10k-character string in a field sized for 50 ·
+injection strings that must remain inert · HTML inside free text · a number arriving as a string · deeply
+nested structures.
+
+## Impossible state
+An enum value outside the domain · an orphaned foreign key · an expired session presented as valid · a
+status transition the state machine does not define · a record referencing a deleted parent.
+
+## Contract violation
+An external type that flipped between deploys · an unknown enum member · an extra unexpected field · page
+2 of a paginated response arriving empty · a schema version the code does not know.
+
+---
+
+Each attack asserts what the system **should** do under that condition. An attack written to assert the
+current broken behaviour is not an attack — it is a regression test for the bug.