aw-ecc 1.4.32 → 1.4.48

package/skills/aw-review/SKILL.md

@@ -26,27 +26,71 @@ Do not use as a hidden helper that replaces explicit review intent.
    Start with tests, local validation, E2E, runtime proof, and prior investigation artifacts.
 2. Load the right org-standard playbooks.
    Pull in platform review, design, accessibility, and quality-gate playbooks from the resolved baseline.
-3. Review across the five core axes.
+3. Run BOTH review engines in parallel (DEFAULT, ALWAYS-ON).
+   Both of these must run on every non-trivial review — they are complementary,
+   not alternatives. Launch them concurrently:
+
+   **Engine A — Rules-manifest audit** (`aw-rules-review` + `aw-rules` skills):
+   Load both `aw-rules-review` (worksheet generator) and `aw-rules` (rule
+   definitions, audit criteria, scoring rubric). `aw-rules-review` generates
+   the per-file worksheet; `aw-rules` evaluates each rule as pass/fail.
+   Invocation:
+   - PR: `node ~/.aw/.aw_registry/platform/core/skills/aw-rules-review/scripts/generate-review-template.mjs --pr <number>`
+   - branch diff: `... --diff`
+   - files: `... --files "<csv>"`
+   Output: `.aw_docs/skill-tests/aw-rules-review.md` (worksheet with TODO
+   checkboxes per rule per file). Review the worksheet and mark each rule as
+   `pass | fail | unknown | not_applicable` with notes on failures/unknowns.
+
+   **Engine B — Parallel multi-reviewer** (`/aw:platform-core-full-review`):
+   Runs up to 10 reviewers across 3 conditional waves in parallel:
+   - Wave 1 (always): security, performance, architecture, reliability, maintainability
+   - Wave 2 (if frontend files): i18n, frontend-code, frontend-security
+   - Wave 3 (if UI components): design, architect
+
+   **Merge semantics** — treat Engine A and Engine B findings as independent
+   inputs into step 5 (severity classification):
+   - Engine A failures become blocking rule-manifest findings
+   - Engine B critical findings become blocking reviewer findings
+   - Cross-reference: a finding flagged by BOTH engines is high-confidence
+     and must be treated as blocking
+   - Record both in `state.json` and `verification.md`
+
+   `aw-review` remains the canonical stage contract — both engines feed it;
+   aw-review owns severity, governance, and readiness.
+
+   **Single-reviewer fallback** (rare, must be justified):
+   Only skip parallel mode when ALL of the following hold:
+   - change is < 50 lines AND single file
+   - no auth/payment/schema/public-API surface touched
+   - risk classification is Low
+   - user explicitly requested single-reviewer mode
+   When falling back, use the matching language reviewer agent
+   (`typescript-reviewer`, `python-reviewer`, `java-reviewer`, `kotlin-reviewer`,
+   `go-reviewer`, `rust-reviewer`, `cpp-reviewer`, `flutter-reviewer`)
+   or `code-reviewer`. Record the justification in `state.json`.
+
+4. Review across the five core axes.
    Correctness, readability and simplicity, architecture, security, and performance.
-   When the review covers concrete code changes, prefer the matching reviewer agent when one exists (`typescript-reviewer`, `python-reviewer`, `java-reviewer`, `kotlin-reviewer`, `go-reviewer`, `rust-reviewer`, `cpp-reviewer`, or `flutter-reviewer`).
-   Otherwise use `code-reviewer` and keep `aw-review` as the canonical stage contract for severity, governance, and readiness.
+   Treat the aggregated findings from parallel execution as the input to severity
+   classification (step 5) and governance/readiness (step 7).
    Use `../../references/review-findings-severity.md`.
    For readability and maintainability concerns, load `code-simplification`.
    For public contract or boundary changes, load `api-and-interface-design`.
    For security-sensitive work, load `security-and-hardening` and `../../references/security-checklist.md`.
    For performance-sensitive work, load `performance-optimization` and `../../references/performance-checklist.md`.
    For branch hygiene, save-point quality, or reviewability concerns, load `git-workflow-and-versioning`.
-4. Classify findings explicitly.
+5. Classify findings explicitly.
    Separate blocking findings from advisory notes.
    Name evidence, scope, and required fix.
-5. Continue until the requested review scope is covered.
+6. Continue until the requested review scope is covered.
    Do not stop after the first finding or the first review axis if correctness, governance, architecture, security, performance, or readiness checks still remain.
-6. Check governance and readiness.
+7. Check governance and readiness.
    Confirm PR checklist, approvals, status checks, rollback notes, and release recommendation.
    For architecture or public-behavior changes that need durable rationale, load `documentation-and-adrs`.
-7. Request fresh testing when needed.
+8. Request fresh testing when needed.
    If evidence is stale, missing, or too broad, route back to `aw-test` for the smallest targeted rerun.
-8. Persist the result.
+9. Persist the result.
    Write `verification.md` and update `state.json`.
 
 ## Completion Contract
@@ -80,6 +124,10 @@ Every review handoff must make these things obvious:
 - PR governance is implied instead of checked
 - platform review or design playbooks are skipped for applicable work
 - stale test evidence is reused after repairs
+- single-reviewer mode used without meeting ALL fallback criteria
+- parallel `/aw:platform-core-full-review` skipped on a non-trivial change
+- `aw-rules-review` worksheet skipped (rule-manifest audit is mandatory alongside reviewers)
+- only one engine ran when both should have
 
 ## State File
 
@@ -89,6 +137,15 @@ Every review handoff must make these things obvious:
 - `stage: "review"`
 - `mode`
 - `status`
+- `review_mode`: `"parallel"` (default) | `"single"` (must include justification)
+- `single_mode_justification`: required when `review_mode == "single"`
+- `engines_run`: array of engines executed (e.g., `["aw-rules-review", "platform-core-full-review"]`)
+- `rules_review_worksheet`: path to the aw-rules-review output (e.g., `.aw_docs/skill-tests/aw-rules-review.md`)
+- `rules_review_failures`: count of rule-manifest failures
+- `parallel_run_id`: run_id from `/aw:platform-core-full-review` when parallel mode used
+- `reviewers_active`: list of reviewer agent slugs that executed
+- `waves_executed`: array of wave numbers (e.g., `[1]`, `[1, 2]`, `[1, 2, 3]`)
+- `cross_engine_findings`: findings flagged by BOTH engines (high confidence)
 - written artifacts
 - evidence reviewed
 - reviewer agents or reviewer path used
@@ -96,28 +153,50 @@ Every review handoff must make these things obvious:
 - advisory notes
 - governance status
 - readiness outcome
+- `html_companion_artifacts`
 - blockers
 - recommended next commands
 
+## Human HTML Companion
+
+Markdown `verification.md` remains canonical for agents.
+When review writes or materially updates `verification.md`, also create or refresh `.aw_docs/features/<feature_slug>/verification.html`. HTML sidecars are required stage outputs, not advisory metadata.
+
+Delegate to the `aw:echo` subagent with the `pr-one-pager` profile for reviewer-facing summaries and readiness decisions.
+Use `impact-analysis-report` only when the review output is primarily blast radius or customer impact.
+Invoking `/aw:review` in default `dual` mode is explicit authorization to spawn exactly one `aw:echo` subagent for HTML companion generation; do not skip HTML only because no direct command is available.
+Resolve output mode as: explicit user request for Markdown-only -> otherwise `dual`. `.aw_docs/config.json` and `AW_DOCS_OUTPUT_MODE` may request `dual` or `html`, but must not silently suppress required SDLC HTML sidecars.
+
+Pass evidence reviewed, engines run, findings, severity, governance status, readiness outcome, repair path, and next command as the source bundle.
+Record the colocated sidecar in `state.json` `html_companion_artifacts` with `source_path`, `html_path`, profile, status, `run_ref` when available, publish status, and any explicit Markdown-only skip or fallback reason.
+Spawn exactly one `aw:echo` subagent and wait for the colocated `.html` sidecar before the final handoff unless the user explicitly asks not to wait. If the harness still cannot spawn `aw:echo`, create a conservative self-contained fallback HTML sidecar in the same turn using the `aw:echo` safety and design contract, record `generated_fallback` plus the blocker, and keep Markdown canonical.
+
 ## Verification
 
 Before leaving review, confirm:
 
 - [ ] test and runtime evidence were reviewed first
+- [ ] BOTH engines ran by default: `aw-rules-review` AND `/aw:platform-core-full-review`
+- [ ] rules-manifest worksheet was generated and every rule marked pass/fail/unknown/not_applicable
+- [ ] cross-engine findings (flagged by both) are elevated to blocking
+- [ ] if single-reviewer mode was used, justification meets ALL fallback criteria and is recorded in `state.json`
+- [ ] `engines_run`, `rules_review_worksheet`, `parallel_run_id`, `reviewers_active`, and `waves_executed` are recorded
 - [ ] findings are explicit, evidence-backed, and severity-tagged
 - [ ] reviewer routing is explicit when the scope included concrete code review
 - [ ] governance and readiness checks match the resolved baseline
 - [ ] repairs point back to build or test with clear scope
 - [ ] `verification.md` and `state.json` are updated
+- [ ] the HTML companion file exists, or the user explicitly requested Markdown-only
 
 ## Final Output Shape
 
 Always end with:
 
-- `Mode`
+- `Mode` (include: `review_mode = parallel | single`, `engines_run = [...]`, `reviewers_active = N`, `waves_executed = [...]`, `parallel_run_id`, `rules_review_worksheet` path)
 - `Evidence`
 - `Findings`
 - `Governance`
 - `Readiness`
 - `Outcome`
+- `HTML Companion`
 - `Next`

package/skills/aw-rules-review/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: aw-rules-review
+description: Generate a per-file review worksheet driven by rule-manifest.json. Supports all tracked files, PR diff, branch diff, or explicit file list. Use for isolated manifest-driven rule audits.
+---
+
+# AW Rules Review
+
+Generate a per-file review worksheet that maps source files to applicable platform rules from `rule-manifest.json`. Supports multiple scoping modes — full repo, PR diff, branch diff, or explicit file list.
+
+## Required Co-Skill
+
+**`aw-rules`** must be loaded alongside this skill. `aw-rules-review` generates the per-file worksheet; `aw-rules` provides the rule definitions, audit criteria, and scoring rubric needed to evaluate each rule as pass/fail. Without `aw-rules`, the worksheet has TODO checkboxes but no way to assess compliance.
+
+When invoked from `aw-review` (Engine A), the `aw-rules` skill is loaded automatically.
+
+## What This Skill Does
+
+1. Locates `rule-manifest.json` (workspace `.aw_registry/` → global `~/.aw/.aw_registry/`)
+2. Collects source files based on the chosen mode (PR, diff, file list, or all)
+3. Detects each file's domain(s) and stack(s) from its path
+4. Matches applicable rules by domain + stack overlap
+5. Generates a per-file checklist worksheet with blank status for each rule
+
+## Modes
+
+### All tracked files (default)
+
+```bash
+node scripts/generate-review-template.mjs
+```
+
+### PR diff
+
+Reviews only files changed in a GitHub PR. Requires `gh` CLI.
+
+```bash
+node scripts/generate-review-template.mjs --pr 1234
+```
+
+### Branch diff
+
+Reviews files changed between the current branch and its merge-base with main/master.
+
+```bash
+node scripts/generate-review-template.mjs --diff
+node scripts/generate-review-template.mjs --diff --base origin/develop
+```
+
+### Explicit file list
+
+```bash
+node scripts/generate-review-template.mjs --files "src/foo.ts,src/bar.vue"
+```
+
+### Custom output path
+
+```bash
+node scripts/generate-review-template.mjs --pr 1234 --out review.md
+```
+
+## Manifest Resolution
+
+The script searches for the rule manifest in this order:
+
+1. `$WORKSPACE/.aw_registry/.aw_rules/rule-manifest.json`
+2. `$WORKSPACE/.aw_registry/.aw_rules/manifest.json` (legacy)
+3. `~/.aw/.aw_registry/.aw_rules/rule-manifest.json`
+4. `~/.aw/.aw_registry/.aw_rules/manifest.json` (legacy)
+
+Set `AW_RULES_WORKSPACE_ROOT` to override the workspace root.
+
+## Domain Detection
+
+Files are mapped to domains by path patterns:
+
+| Domain | Matched by |
+|--------|-----------|
+| `infra` | `helm/`, `terraform/`, `Dockerfile`, `Jenkinsfile` |
+| `sdet` | `e2e/`, `playwright/` (E2E tests only — not unit/integration specs) |
+| `mobile` | `*.dart`, `lib/` |
+| `frontend` | `*.vue`, `composables/`, `components/*.ts`, `stores/` |
+| `data` | `*.schema.ts`, `*.migration.*`, `*.repository.ts` |
+| `api-design` | `*.controller.ts`, `dto/`, `*.client.ts` |
+| `backend` | `*.service.ts`, `*.module.ts`, `*.worker.ts`, or any file with "worker" in its name |
+
+**Unit/integration test files** (`__tests__/**/*.spec.ts`) inherit the domain of their parent module, not `sdet`. The `sdet` domain is reserved for E2E/Playwright tests only.
+
+Rules with `domains: ["all"]` apply to every file. Rules with `stacks` (e.g. `nestjs`, `vue`) only match files detected as that stack.
+
+## Review Procedure
+
+1. Run the script with the appropriate mode flag
+2. Open the generated worksheet
+3. Review files in batches
+4. Replace `TODO` with: `pass`, `fail`, `unknown`, or `not_applicable`
+5. Add concise notes only for failures, unknowns, or meaningful exemptions
+
+## Expected Output
+
+Default: `.aw_docs/skill-tests/aw-rules-review.md`
+
+## CLI Reference
+
+```
+Usage: generate-review-template.mjs [options]
+
+Modes (pick one):
+  --pr <number>        Review files changed in a GitHub PR (requires gh CLI)
+  --diff               Review files changed vs the current branch's merge-base
+  --base <ref>         Base ref for --diff mode (default: auto-detected main/master)
+  --files <glob,...>   Review an explicit comma-separated list of files
+  (no flag)            Review all tracked files in the repo
+
+Options:
+  --out, -o <path>     Output worksheet path
+  --help, -h           Show this help
+```
+
+## Important Limits
+
+- The script does not decide pass/fail automatically
+- Semantic rules still need AI or human review
+- Domain detection is path-based — files outside standard paths get only universal rules
+- This skill is intentionally standalone and should not call the existing workspace review command

package/skills/aw-rules-review/agents/openai.yaml

@@ -0,0 +1,3 @@
+display_name: AW Rules Review
+short_description: Generate a per-file aw-rules review worksheet (full repo, PR diff, branch diff, or file list)
+default_prompt: Generate an aw-rules review worksheet for source files in this workspace. Supports --pr, --diff, --files, or all tracked files.

package/skills/aw-rules-review/scripts/generate-review-template.mjs

@@ -0,0 +1,323 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+const { values: flags } = parseArgs({
+  options: {
+    pr:    { type: 'string',  short: 'p' },
+    diff:  { type: 'boolean', short: 'd', default: false },
+    files: { type: 'string',  short: 'f' },
+    base:  { type: 'string',  short: 'b' },
+    out:   { type: 'string',  short: 'o' },
+    help:  { type: 'boolean', short: 'h', default: false },
+  },
+  strict: false,
+  allowPositionals: true,
+});
+
+if (flags.help) {
+  console.log(`
+Usage: generate-review-template.mjs [options]
+
+Modes (pick one):
+  --pr <number>        Review files changed in a GitHub PR (requires gh CLI)
+  --diff               Review files changed vs the current branch's merge-base
+  --base <ref>         Base ref for --diff mode (default: auto-detected main/master)
+  --files <glob,...>   Review an explicit comma-separated list of files
+  (no flag)            Review all tracked files in the repo
+
+Options:
+  --out, -o <path>     Output worksheet path (default: .aw_docs/skill-tests/aw-rules-review.md)
+  --help, -h           Show this help
+`);
+  process.exit(0);
+}
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+
+const workspaceRoot = process.env.AW_RULES_WORKSPACE_ROOT
+  ? path.resolve(process.env.AW_RULES_WORKSPACE_ROOT)
+  : process.cwd();
+
+const defaultOutputPath = path.join(
+  workspaceRoot, '.aw_docs', 'skill-tests', 'aw-rules-review.md',
+);
+const outputPath = flags.out
+  ? path.resolve(workspaceRoot, flags.out)
+  : defaultOutputPath;
+
+// ---------------------------------------------------------------------------
+// Locate rule-manifest.json (try workspace first, then global ~/.aw)
+// ---------------------------------------------------------------------------
+
+const MANIFEST_CANDIDATES = [
+  path.join(workspaceRoot, '.aw_registry', '.aw_rules', 'rule-manifest.json'),
+  path.join(workspaceRoot, '.aw_registry', '.aw_rules', 'manifest.json'),
+  path.join(process.env.HOME, '.aw', '.aw_registry', '.aw_rules', 'rule-manifest.json'),
+  path.join(process.env.HOME, '.aw', '.aw_registry', '.aw_rules', 'manifest.json'),
+];
+
+function findManifest() {
+  for (const candidate of MANIFEST_CANDIDATES) {
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  console.error(
+    'ERROR: Could not find rule-manifest.json in any of:\n' +
+    MANIFEST_CANDIDATES.map((p) => `  - ${p}`).join('\n'),
+  );
+  process.exit(1);
+}
+
+const manifestPath = findManifest();
+const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+
+console.log(`Manifest: ${manifestPath} (${manifest.rules.length} rules)`);
+
+// ---------------------------------------------------------------------------
+// Domain detection — maps file paths to manifest domains
+// ---------------------------------------------------------------------------
+
+const DOMAIN_PATTERNS = [
+  // infra
+  { test: (f) => /\/(helm|terraform)\//i.test(f) || /Dockerfile|Jenkinsfile/i.test(f), domain: 'infra' },
+  // sdet / e2e only (not unit/integration specs)
+  { test: (f) => /\/(e2e|playwright)\//i.test(f), domain: 'sdet' },
+  // mobile / flutter
+  { test: (f) => /\.dart$/.test(f) || /\/lib\//.test(f), domain: 'mobile' },
+  // frontend
+  { test: (f) => /\.vue$/.test(f) || /composables?\//.test(f) || /\/components\/.*\.ts$/.test(f) || /stores?\//.test(f), domain: 'frontend' },
+  // data
+  { test: (f) => /\.schema\.ts$/.test(f) || /\.migration\./.test(f) || /\.repository\.ts$/.test(f), domain: 'data' },
+  // api-design
+  { test: (f) => /\.controller\.ts$/.test(f) || /\/dto\//.test(f) || /\.client\.ts$/.test(f), domain: 'api-design' },
+  // backend (broad — services, modules, workers, and files with "worker" in the name)
+  { test: (f) => /\.(service|module|worker)\.ts$/.test(f) || /worker/i.test(path.basename(f)), domain: 'backend' },
+];
+
+function isUnitOrIntegrationTest(filePath) {
+  return /__tests__\//.test(filePath) && /\.spec\.ts$/.test(filePath) && !/\/(e2e|playwright)\//.test(filePath);
+}
+
+function detectDomains(filePath) {
+  const domains = new Set();
+
+  // Unit/integration test files inherit the domain of the code they test,
+  // not sdet (which is for E2E/Playwright only). Detect from parent path.
+  if (isUnitOrIntegrationTest(filePath)) {
+    // Strip __tests__/... suffix and re-detect based on the parent module path
+    const parentPath = filePath.replace(/__tests__\/.*$/, '');
+    // Check if parent contains service/schema/controller/worker patterns
+    // but also tag as backend by default since unit tests live in backend modules
+    for (const { test, domain } of DOMAIN_PATTERNS) {
+      if (test(parentPath)) domains.add(domain);
+    }
+    if (domains.size === 0) domains.add('backend');
+    return [...domains];
+  }
+
+  for (const { test, domain } of DOMAIN_PATTERNS) {
+    if (test(filePath)) domains.add(domain);
+  }
+  // Controllers belong to both api-design and backend
+  if (domains.has('api-design')) domains.add('backend');
+  // Schemas belong to both data and backend
+  if (domains.has('data')) domains.add('backend');
+  // If nothing matched, tag as general (universal rules still apply)
+  if (domains.size === 0) domains.add('_general');
+  return [...domains];
+}
+
+// ---------------------------------------------------------------------------
+// Stack detection
+// ---------------------------------------------------------------------------
+
+function detectStacks(filePath) {
+  const stacks = new Set();
+  if (/\.vue$/.test(filePath) || /composables?\//.test(filePath)) stacks.add('vue');
+  if (/\/nuxt\.config|\.nuxt\/|\/server\/api\//.test(filePath)) stacks.add('nuxt');
+  if (/\.module\.ts$/.test(filePath) || /\.controller\.ts$/.test(filePath) || /\/dto\//.test(filePath)) stacks.add('nestjs');
+  if (/\.go$/.test(filePath)) stacks.add('go-connect');
+  return [...stacks];
+}
+
+// ---------------------------------------------------------------------------
+// Rule matching
+// ---------------------------------------------------------------------------
+
+function applicableRules(filePath) {
+  const fileDomains = detectDomains(filePath);
+  const fileStacks = detectStacks(filePath);
+
+  return manifest.rules.filter((rule) => {
+    // Domain match: rule applies to "all" or overlaps with file domains
+    const domainMatch = rule.domains.includes('all') ||
+      rule.domains.some((d) => fileDomains.includes(d));
+    if (!domainMatch) return false;
+
+    // Stack match: if rule specifies stacks, file must match at least one
+    if (rule.stacks && rule.stacks.length > 0) {
+      return rule.stacks.some((s) => fileStacks.includes(s));
+    }
+    return true;
+  });
+}
+
+// ---------------------------------------------------------------------------
+// File collection — depends on mode
+// ---------------------------------------------------------------------------
+
+function sh(cmd) {
+  return execSync(cmd, { cwd: workspaceRoot, encoding: 'utf8' }).trim();
+}
+
+function getFilesFromPR(prNumber) {
+  const json = sh(`gh api "repos/{owner}/{repo}/pulls/${prNumber}/files?per_page=100"`);
+  const files = JSON.parse(json);
+  return files.map((f) => f.filename).filter(Boolean);
+}
+
+function getFilesFromDiff(baseRef) {
+  const base = baseRef || detectBaseRef();
+  const mergeBase = sh(`git merge-base ${base} HEAD`);
+  return sh(`git diff --name-only ${mergeBase}`)
+    .split('\n')
+    .filter(Boolean);
+}
+
+function detectBaseRef() {
+  // Detect the default branch from the remote HEAD
+  try {
+    const symRef = sh('git symbolic-ref refs/remotes/origin/HEAD');
+    return symRef.replace('refs/remotes/', '');
+  } catch { /* ignore */ }
+  // Fallback: try common names
+  for (const ref of ['origin/main', 'origin/master', 'main', 'master']) {
+    try { sh(`git rev-parse --verify ${ref}`); return ref; } catch { /* ignore */ }
+  }
+  return 'master';
+}
+
+function getFilesFromList(csv) {
+  return csv.split(',').map((f) => f.trim()).filter(Boolean);
+}
+
+function getAllTrackedFiles() {
+  return sh('git ls-files')
+    .split('\n')
+    .filter(Boolean);
+}
+
+function collectFiles() {
+  if (flags.pr) {
+    console.log(`Mode: PR #${flags.pr}`);
+    return getFilesFromPR(flags.pr);
+  }
+  if (flags.diff) {
+    const base = flags.base || detectBaseRef();
+    console.log(`Mode: diff vs ${base}`);
+    return getFilesFromDiff(base);
+  }
+  if (flags.files) {
+    console.log(`Mode: explicit file list`);
+    return getFilesFromList(flags.files);
+  }
+  console.log('Mode: all tracked files');
+  return getAllTrackedFiles();
+}
+
+// Filter to source files only (skip assets, configs, lockfiles, etc.)
+const SOURCE_EXTENSIONS = new Set([
+  '.ts', '.tsx', '.js', '.jsx', '.vue', '.dart', '.go', '.yaml', '.yml',
+  '.tf', '.hcl', '.md', '.json', '.mjs', '.cjs',
+]);
+
+function isSourceFile(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  if (SOURCE_EXTENSIONS.has(ext)) return true;
+  // Dockerfile, Jenkinsfile (no extension)
+  const base = path.basename(filePath);
+  return /^(Dockerfile|Jenkinsfile)/i.test(base);
+}
+
+// ---------------------------------------------------------------------------
+// Generate worksheet
+// ---------------------------------------------------------------------------
+
+const files = collectFiles().filter(isSourceFile);
+console.log(`Files to review: ${files.length}`);
+
+if (files.length === 0) {
+  console.log('No source files found for the selected mode. Nothing to generate.');
+  process.exit(0);
+}
+
+const modeLabel = flags.pr
+  ? `PR #${flags.pr}`
+  : flags.diff
+    ? `diff vs ${flags.base || 'auto-detected base'}`
+    : flags.files
+      ? 'explicit file list'
+      : 'all tracked files';
+
+const sections = files.map((filePath) => {
+  const rules = applicableRules(filePath);
+  const domains = detectDomains(filePath);
+  const stacks = detectStacks(filePath);
+
+  const ruleLines = rules.length === 0
+    ? ['- No applicable manifest rules']
+    : rules.map((rule) => {
+        return `- [ ] \`${rule.id}\` | severity: \`${rule.severity}\` | status: \`TODO\` | ${rule.description}`;
+      });
+
+  const domainTag = domains.join(', ');
+  const stackTag = stacks.length > 0 ? ` | stacks: \`${stacks.join(', ')}\`` : '';
+
+  return `## \`${filePath}\`
+
+- Domains: \`${domainTag}\`${stackTag}
+- Applicable rules: \`${rules.length}\`
+
+${ruleLines.join('\n')}
+`;
+});
+
+const output = `# AW Rules Review Worksheet
+
+- Mode: **${modeLabel}**
+- Workspace: \`${workspaceRoot}\`
+- Manifest: \`${manifestPath}\`
+- Total rules: \`${manifest.rules.length}\`
+- Files in worksheet: \`${files.length}\`
+- Generated: \`${new Date().toISOString()}\`
+
+## Status legend
+
+| Status | Meaning |
+|--------|---------|
+| \`pass\` | Rule satisfied |
+| \`fail\` | Rule violated — add note |
+| \`unknown\` | Cannot determine — add note |
+| \`not_applicable\` | Rule does not apply to this file context |
+
+---
+
+${sections.join('\n')}
+`;
+
+fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+fs.writeFileSync(outputPath, output);
+console.log(`Worksheet written to: ${outputPath}`);

package/skills/aw-ship/SKILL.md

@@ -92,15 +92,30 @@ Every shipping handoff must make these things obvious:
 - rollout plan
 - rollback path
 - evidence captured
+- `html_companion_artifacts`
 - blockers
 - recommended next commands
 
+## Human HTML Companion
+
+Markdown `release.md` remains canonical for agents.
+When ship writes or materially updates `release.md`, also create or refresh `.aw_docs/features/<feature_slug>/release.html`. HTML sidecars are required stage outputs, not advisory metadata.
+
+Delegate to the `aw:echo` subagent with the `release-report` profile.
+Invoking `/aw:ship` in default `dual` mode is explicit authorization to spawn exactly one `aw:echo` subagent for HTML companion generation; do not skip HTML only because no direct command is available.
+Resolve output mode as: explicit user request for Markdown-only -> otherwise `dual`. `.aw_docs/config.json` and `AW_DOCS_OUTPUT_MODE` may request `dual` or `html`, but must not silently suppress required SDLC HTML sidecars.
+
+Pass launch readiness, rollout plan, rollback posture, monitoring or smoke evidence, blockers, ownership, and next command as the source bundle.
+Record the colocated sidecar in `state.json` `html_companion_artifacts` with `source_path`, `html_path`, profile, status, `run_ref` when available, publish status, and any explicit Markdown-only skip or fallback reason.
+Spawn exactly one `aw:echo` subagent and wait for the colocated `.html` sidecar before the final handoff unless the user explicitly asks not to wait. If the harness still cannot spawn `aw:echo`, create a conservative self-contained fallback HTML sidecar in the same turn using the `aw:echo` safety and design contract, record `generated_fallback` plus the blocker, and keep Markdown canonical.
+
 ## Verification
 
 - [ ] launch checklist or blocker is explicit
 - [ ] rollback readiness is documented
 - [ ] monitoring and smoke expectations are named
 - [ ] `release.md` and `state.json` are updated with closeout evidence
+- [ ] the HTML companion file exists, or the user explicitly requested Markdown-only
 
 ## Final Output Shape
 
@@ -112,4 +127,5 @@ Always end with:
 - `Rollback Path`
 - `Evidence`
 - `Outcome`
+- `HTML Companion`
 - `Next`