aw-ecc 1.4.21 → 1.4.25

package/.cursor/skills/aw-execute/references/mode-code.md

@@ -0,0 +1,47 @@
+# Mode: Code — TDD Execution
+
+## Iron Law
+
+> **Every [code] task follows TDD. No exceptions. No rationalizations.**
+
+## Red-Green-Refactor Cycle
+
+### 1. RED — Write the test first
+
+- Write a failing test that describes the expected behavior.
+- Run the test. It MUST fail. If it passes, the test is wrong or the behavior already exists.
+- The test defines the contract. Implementation serves the test.
+
+### 2. GREEN — Write minimal code to pass
+
+- Write the simplest implementation that makes the test pass.
+- Do not add features, optimizations, or "nice-to-haves" at this stage.
+- Run the test. It MUST pass.
+
+### 3. REFACTOR — Clean up without changing behavior
+
+- Extract helpers, rename variables, reduce duplication.
+- Run tests after every refactor step. They MUST still pass.
+- Stop refactoring when the code is clean and readable.
+
+## Rules
+
+- **Test file per source file** — `feature.service.ts` gets `feature.service.spec.ts`.
+- **Descriptive test names** — `it('should return empty array when no features exist for locationId')`.
+- **No mocking internals** — Mock boundaries (HTTP, database, external services), not internal functions.
+- **Coverage gate** — 80% minimum. Check with `npm run test:cov` or equivalent.
+- **No skipped tests** — `it.skip` and `xit` are not allowed in committed code.
+- **Platform logger** — Use `@platform-core/logger`, never `console.*`.
+- **DTO validation** — Every `@Body()` parameter has a class-validator DTO.
+- **Error handling** — Every async call has explicit error handling.
+
+## Rationalization Table
+
+| Rationalization | Why It Is Wrong |
+|---|---|
+| "I'll write tests after" | You will not. And the code will be shaped for implementation, not testability. |
+| "This is too simple to test" | Simple code breaks too. The test documents the contract. |
+| "Tests slow me down" | Tests slow you down now. Bugs slow you down forever. |
+| "I'll just test the happy path" | Errors happen on unhappy paths. Test both. |
+| "The integration test covers it" | Integration tests are slow and broad. Unit tests are fast and precise. |
+| "I know this works" | Prove it. Run the test. |

package/.cursor/skills/aw-execute/references/mode-docs.md

@@ -0,0 +1,28 @@
+# Mode: Docs — Write, Review, Commit
+
+## Process
+
+### 1. Write
+
+- Write the documentation in the appropriate location.
+- Follow existing documentation style and format in the repo.
+- Include code examples where they aid understanding.
+- Keep language clear, concise, and direct.
+
+### 2. Self-Review Checklist
+
+Before committing documentation:
+
+- [ ] **Accuracy** — All technical details are correct and verified against the code.
+- [ ] **Completeness** — All public APIs, config options, and workflows are documented.
+- [ ] **Examples** — Code examples compile/run and match current API signatures.
+- [ ] **Links** — All internal links resolve. No broken references.
+- [ ] **Formatting** — Consistent heading levels, code block languages, and list styles.
+- [ ] **No stale content** — Removed or updated references to deprecated features.
+- [ ] **Audience** — Written for the target reader (developer, operator, end user).
+
+### 3. Commit
+
+- Commit documentation changes with `docs:` prefix.
+- If docs accompany code changes, include in the same PR.
+- Update the table of contents or index if one exists.

package/.cursor/skills/aw-execute/references/mode-infra.md

@@ -0,0 +1,44 @@
+# Mode: Infra — Dry-Run First
+
+## Core Principle
+
+> **Never apply infrastructure changes directly. Validate first, deploy via Jenkins.**
+
+## Process
+
+### 1. Validate
+
+- Run `helm lint` for Helm chart changes.
+- Run `terraform plan` for Terraform changes.
+- Run `docker build` to verify Dockerfile changes.
+- Review the diff carefully before proceeding.
+
+### 2. Dry-Run
+
+- `terraform plan -out=tfplan` — Review every resource change.
+- `helm template` — Render and inspect the full manifest.
+- `helm diff upgrade` — Compare current state with proposed changes.
+
+### 3. Deploy via Jenkins
+
+- **Never** run `kubectl apply`, `helm install`, or `terraform apply` directly.
+- Use Jenkins shared library functions for all deployments.
+- Trigger deployments via Jenkins pipeline, not CLI.
+
+### 4. Verify
+
+- Check pod status after deployment.
+- Verify health probes are responding.
+- Check logs for startup errors.
+- Confirm the change is reflected in the running system.
+
+## Platform Rules
+
+- **Resource requests** — Set `resources.requests` for every container. Limits auto-calculated for servers.
+- **Health probes** — Configure for every deployment (default path `/` on port 6050).
+- **No CPU limits = requests** — Never set CPU limits equal to CPU requests (causes throttling).
+- **No secrets in Helm** — Use GCP Secret Manager, not Helm values or ConfigMaps.
+- **No KEDA** — KEDA is deprecated. Use `peakLoad.peakLoadMinReplicas` instead.
+- **Pin image tags** — Never use `latest`. Use specific digest or semver.
+- **Graceful shutdown** — `terminationGracePeriodSeconds` >= 30 seconds.
+- **Terraform managed** — All GCP resources via Terraform. No manual console changes.

package/.cursor/skills/aw-execute/references/mode-migration.md

@@ -0,0 +1,58 @@
+# Mode: Migration — Staged Rollout
+
+## Process
+
+### 1. Script
+
+- Write the migration script. It MUST be **idempotent** — running it twice produces the same result.
+- Use `up()` and `down()` functions (or equivalent) for forward and rollback.
+- Include validation checks that confirm the migration was applied correctly.
+- Test the migration against a copy of production data (or realistic test data).
+
+### 2. Rollback
+
+- Every migration MUST have a rollback path.
+- Write the rollback script before applying the migration.
+- Test the rollback independently.
+- Document the rollback procedure in the migration file header.
+
+### 3. Validate
+
+- Run the migration in a test/staging environment first.
+- Verify data integrity after migration.
+- Check that dependent queries still work with the new schema.
+- Confirm indexes are in place before queries execute.
+
+### 4. Commit
+
+- Commit migration files with `migration:` or `feat:` prefix.
+- Include the rollback script in the same commit.
+- Document the migration in the PR description.
+
+## Rules
+
+### Indexes
+
+- **Deploy indexes BEFORE** deploying schema or query changes that use them.
+- Use `background: true` for index creation (or rely on MongoDB 4.2+ default).
+- Add compound indexes for multi-field queries — avoid multiple single-field indexes.
+- Scope all MongoDB queries by `locationId` (compound index required).
+
+### Fields
+
+- New fields MUST have default values or be nullable — never break existing documents.
+- Remove fields in two phases: (1) stop writing, (2) remove after migration window.
+- Never rename fields in a single migration — add new, migrate data, remove old.
+
+### Secrets
+
+- Never store secrets in migration scripts.
+- Use environment variables or GCP Secret Manager for connection strings.
+- Never log sensitive data during migration (PII, credentials, tokens).
+
+### Data Safety
+
+- Back up the collection/table before running destructive migrations.
+- Use transactions where available for multi-document updates.
+- Set reasonable batch sizes for bulk operations — avoid OOM.
+- Log progress for long-running migrations (every N records).

package/.cursor/skills/aw-execute/references/worker-implementer.md

@@ -0,0 +1,26 @@
+# Worker Role: Implementer
+
+## Objective
+
+Own one bounded task unit from the approved AW execution inputs.
+Change only the smallest correct file set for that unit.
+
+## Inputs
+
+- approved feature inputs from `.aw_docs/features/<feature_slug>/`
+- current task-unit bundle
+- repo-local AW execution contract
+
+## Required Behavior
+
+1. confirm the task-unit goal and file scope
+2. capture the RED or failure-first signal when behavior changes
+3. implement the smallest correct GREEN change
+4. record handoff notes for spec and quality review
+5. stop when the task unit is complete or blocked
+
+## Hard Gates
+
+- do not widen the write scope without naming why
+- do not skip runnable tests silently
+- do not mark the task done without concrete notes for the next review roles

package/.cursor/skills/aw-execute/references/worker-parallel-worker.md

@@ -0,0 +1,23 @@
+# Worker Role: Parallel Worker
+
+## Objective
+
+Execute one task unit that has already been marked `parallel_candidate` with a disjoint write scope.
+The orchestrator should keep active parallel workers within the configured cap, which defaults to `3`.
+
+## Inputs
+
+- current task-unit bundle
+- declared disjoint write scope
+- repo-local AW execution contract
+
+## Required Behavior
+
+1. stay inside the declared write scope
+2. keep notes concise so the merge-back step can reconcile outputs cleanly
+3. stop immediately if the work crosses into another worker's files
+
+## Hard Gates
+
+- do not edit shared files outside the declared scope
+- do not claim a task unit is parallel-safe if overlap was discovered during execution

package/.cursor/skills/aw-execute/references/worker-quality-reviewer.md

@@ -0,0 +1,23 @@
+# Worker Role: Quality Reviewer
+
+## Objective
+
+Check maintainability, reliability, and stage readiness for one completed task unit.
+
+## Inputs
+
+- implementer handoff notes
+- spec review outcome
+- current task-unit bundle
+
+## Required Behavior
+
+1. inspect the changed files and local validation notes
+2. flag maintainability or reliability issues that would block handoff
+3. state `pass`, `pass_with_notes`, or `fail`
+4. hand back the smallest concrete repair scope when failing
+
+## Hard Gates
+
+- do not reopen planning
+- do not wave through unresolved reliability or validation gaps

package/.cursor/skills/aw-execute/references/worker-spec-reviewer.md

@@ -0,0 +1,23 @@
+# Worker Role: Spec Reviewer
+
+## Objective
+
+Check one completed task unit against the approved AW inputs before the stage can move forward.
+
+## Inputs
+
+- approved feature inputs from `.aw_docs/features/<feature_slug>/`
+- implementer handoff notes
+- current task-unit bundle
+
+## Required Behavior
+
+1. compare the implementation against the approved task-unit goal
+2. flag scope drift or missed acceptance criteria
+3. state `pass`, `pass_with_notes`, or `fail`
+4. hand back the smallest concrete repair scope when failing
+
+## Hard Gates
+
+- do not invent new product scope
+- do not approve a task unit that skipped a required acceptance point

package/.cursor/skills/aw-execute/scripts/build-worker-bundle.js

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function usage() {
+  console.error(
+    'Usage: node skills/aw-execute/scripts/build-worker-bundle.js --feature <slug> --tasks-file <path> [--output <path>] [--allow-parallel] [--max-parallel-workers <n>]'
+  );
+}
+
+function parseArgs(argv) {
+  const args = {
+    allowParallel: false,
+    maxParallelWorkers: 3,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const current = argv[index];
+    if (current === '--allow-parallel') {
+      args.allowParallel = true;
+      continue;
+    }
+
+    if (!current.startsWith('--')) {
+      throw new Error(`Unexpected argument: ${current}`);
+    }
+
+    const next = argv[index + 1];
+    if (!next || next.startsWith('--')) {
+      throw new Error(`Missing value for ${current}`);
+    }
+
+    if (current === '--feature') {
+      args.featureSlug = next;
+    } else if (current === '--tasks-file') {
+      args.tasksFile = next;
+    } else if (current === '--output') {
+      args.output = next;
+    } else if (current === '--max-parallel-workers') {
+      const parsedValue = Number(next);
+      if (!Number.isInteger(parsedValue) || parsedValue < 1) {
+        throw new Error('--max-parallel-workers must be a positive integer');
+      }
+      args.maxParallelWorkers = parsedValue;
+    } else {
+      throw new Error(`Unknown argument: ${current}`);
+    }
+
+    index += 1;
+  }
+
+  if (!args.featureSlug || !args.tasksFile) {
+    usage();
+    throw new Error('--feature and --tasks-file are required');
+  }
+
+  return args;
+}
+
+function toPosixPath(value) {
+  return value.split(path.sep).join('/');
+}
+
+function parseTaskUnits(content) {
+  const units = [];
+
+  for (const line of content.split(/\r?\n/)) {
+    const match = line.match(/^\s*(?:- \[[ xX]\]|-|\*|\d+\.)\s+(.+?)\s*$/);
+    if (!match) {
+      continue;
+    }
+
+    const title = match[1].trim();
+    if (!title) {
+      continue;
+    }
+
+    units.push(title);
+  }
+
+  if (units.length === 0) {
+    throw new Error('No task units found in tasks file');
+  }
+
+  return units;
+}
+
+function buildRolePrompt({ roleGuide, featureSlug, taskUnitTitle, tasksFilePath, roleName }) {
+  return [
+    `Load role guide: ${roleGuide}`,
+    `Feature slug: ${featureSlug}`,
+    `Task unit: ${taskUnitTitle}`,
+    `Approved task source: ${tasksFilePath}`,
+    `Role: ${roleName}`,
+    'Stay within the repo-local AW execute contract and keep the scope bounded.',
+  ].join('\n');
+}
+
+function buildBundle({ featureSlug, tasksFilePath, allowParallel, maxParallelWorkers, repoRoot }) {
+  const taskUnits = parseTaskUnits(fs.readFileSync(tasksFilePath, 'utf8'));
+  const referencePaths = {
+    implementer: 'skills/aw-execute/references/worker-implementer.md',
+    spec_reviewer: 'skills/aw-execute/references/worker-spec-reviewer.md',
+    quality_reviewer: 'skills/aw-execute/references/worker-quality-reviewer.md',
+    parallel_worker: 'skills/aw-execute/references/worker-parallel-worker.md',
+  };
+
+  const relativeTasksFile = toPosixPath(path.relative(repoRoot, tasksFilePath) || path.basename(tasksFilePath));
+  const bundle = {
+    schema_version: 'aw.execute.worker-bundle.v1',
+    feature_slug: featureSlug,
+    generated_at: new Date().toISOString(),
+    source_tasks_file: relativeTasksFile,
+    role_reference_paths: referencePaths,
+    task_units: taskUnits.map((title, index) => {
+      const taskUnitId = `task-${index + 1}`;
+      const parallelCandidate = allowParallel && taskUnits.length > 1;
+
+      const taskUnit = {
+        id: taskUnitId,
+        title,
+        parallel_candidate: parallelCandidate,
+        roles: {
+          implementer: {
+            reference_path: referencePaths.implementer,
+            prompt: buildRolePrompt({
+              roleGuide: referencePaths.implementer,
+              featureSlug,
+              taskUnitTitle: title,
+              tasksFilePath: relativeTasksFile,
+              roleName: 'implementer',
+            }),
+          },
+          spec_reviewer: {
+            reference_path: referencePaths.spec_reviewer,
+            prompt: buildRolePrompt({
+              roleGuide: referencePaths.spec_reviewer,
+              featureSlug,
+              taskUnitTitle: title,
+              tasksFilePath: relativeTasksFile,
+              roleName: 'spec_reviewer',
+            }),
+          },
+          quality_reviewer: {
+            reference_path: referencePaths.quality_reviewer,
+            prompt: buildRolePrompt({
+              roleGuide: referencePaths.quality_reviewer,
+              featureSlug,
+              taskUnitTitle: title,
+              tasksFilePath: relativeTasksFile,
+              roleName: 'quality_reviewer',
+            }),
+          },
+        },
+      };
+
+      if (parallelCandidate) {
+        taskUnit.roles.parallel_worker = {
+          reference_path: referencePaths.parallel_worker,
+          prompt: buildRolePrompt({
+            roleGuide: referencePaths.parallel_worker,
+            featureSlug,
+            taskUnitTitle: title,
+            tasksFilePath: relativeTasksFile,
+            roleName: 'parallel_worker',
+          }),
+        };
+      }
+
+      return taskUnit;
+    }),
+    orchestration_plan: allowParallel
+      ? {
+          sessionName: `aw-execute-${featureSlug}`,
+          repoRoot,
+          baseRef: 'HEAD',
+          max_parallel_workers: maxParallelWorkers,
+          seedPaths: [
+            'skills/aw-execute/scripts/build-worker-bundle.js',
+            ...Object.values(referencePaths),
+          ],
+          launcherCommand: 'codex exec --skip-git-repo-check "$(cat {task_file_sh})"',
+          workers: taskUnits.map((title, index) => ({
+            name: `implementer-task-${index + 1}`,
+            task: buildRolePrompt({
+              roleGuide: referencePaths.parallel_worker,
+              featureSlug,
+              taskUnitTitle: title,
+              tasksFilePath: relativeTasksFile,
+              roleName: 'parallel_worker',
+            }),
+          })),
+        }
+      : null,
+  };
+
+  return bundle;
+}
+
+function main() {
+  try {
+    const args = parseArgs(process.argv.slice(2));
+    const repoRoot = process.cwd();
+    const tasksFilePath = path.resolve(repoRoot, args.tasksFile);
+    const outputPath = args.output ? path.resolve(repoRoot, args.output) : null;
+    const bundle = buildBundle({
+      featureSlug: args.featureSlug,
+      tasksFilePath,
+      allowParallel: args.allowParallel,
+      maxParallelWorkers: args.maxParallelWorkers,
+      repoRoot,
+    });
+
+    const payload = `${JSON.stringify(bundle, null, 2)}\n`;
+    if (outputPath) {
+      fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+      fs.writeFileSync(outputPath, payload, 'utf8');
+    } else {
+      process.stdout.write(payload);
+    }
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+}
+
+main();

package/.cursor/skills/aw-finish/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: aw-finish
+description: Internal compatibility helper for completing a verified development branch with explicit merge, PR, keep, or discard choices and safe worktree cleanup.
+trigger: Internal only. Invoked when verified branch work is done and the next step is a branch-completion decision rather than a staging deployment.
+---
+
+# AW Finish
+
+`aw-finish` is a legacy compatibility skill.
+The canonical public release stage remains `/aw:deploy`, but this helper still owns the branch-completion decision flow when that workflow is needed internally.
+
+## Hard Gate
+
+`aw-test` and `aw-review` must have passed before this skill runs, or the compatibility umbrella must have recorded an equivalent verified outcome.
+If verification failed, route back to `aw-build`, `aw-test`, or `aw-review` instead of finishing.
+
+## Purpose
+
+Use this skill to close out verified branch work safely:
+
+- verify tests before offering completion choices
+- present explicit branch-completion options
+- execute the selected path
+- clean up the worktree only when appropriate
+
+If `.aw_docs/features/<feature_slug>/workspace.json` exists, use it as the source of truth for:
+
+- the active branch and worktree path
+- cleanup policy
+- orchestration coordination directory
+- the recommended `node scripts/orchestration-status.js ...` status command
+
+Staging or production deployment requests should stay on `aw-deploy`.
+
+## Deprecation Timeline
+
+This skill is still active internally even though `/aw:finish` is deprecated as a public entrypoint.
+Keep `aw-finish` available until `/aw:deploy` fully absorbs branch-completion choices, workspace metadata reuse, and cleanup behavior.
+Public deprecation must not be interpreted as immediate removal of the internal helper.
+
+## Completion Flow
+
+1. verify tests and validation signals still pass
+2. determine the base branch
+3. present exactly these choices:
+   - merge locally
+   - push and create PR
+   - keep as branch
+   - discard
+4. execute the selected path
+5. clean up the worktree when the selected path requires cleanup
+6. update or clear `workspace.json` to reflect the final cleanup decision
+
+## Required Options
+
+### Option 1: Merge Locally
+
+- switch to base branch
+- update from remote when appropriate
+- merge the verified branch
+- rerun the minimum correct verification
+- remove the branch or worktree when safe
+- clear `workspace.json` when cleanup completed successfully
+
+### Option 2: Push and Create PR
+
+- push the branch
+- create or update the PR with concise summary and test plan
+- keep the worktree if the branch remains active
+- preserve `workspace.json` for the active branch lifecycle
+
+### Option 3: Keep As-Is
+
+- keep the branch and worktree intact
+- report the branch name and next expected action
+- keep `workspace.json` intact for follow-up work
+
+### Option 4: Discard
+
+- require explicit confirmation
+- delete the branch or worktree only after confirmation
+- remove `workspace.json` only after cleanup succeeds
+
+## Worktree Cleanup Rule
+
+Only clean up the worktree automatically for:
+
+- merge-complete paths
+- confirmed discard paths
+
+Do not clean up the worktree for:
+
+- keep-as-branch
+- PR-open workflows where the branch is still in active use
+
+## Hard Gates
+
+- do not offer completion choices until tests are rechecked
+- do not discard work without explicit confirmation
+- do not turn branch completion into deployment orchestration
+- do not clean up an active PR worktree by accident
+
+## Final Output Shape
+
+Always end with:
+
+- `Verification Check`
+- `Base Branch`
+- `Completion Options`
+- `Selected Path`
+- `Cleanup Decision`