@metasession.co/devaudit-cli 0.1.58 → 0.1.59

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metasession.co/devaudit-cli",
-  "version": "0.1.58",
+  "version": "0.1.59",
   "description": "DevAudit CLI — installs, syncs, and operates the Metasession SDLC across consumer projects.",
   "type": "module",
   "bin": {
@@ -33,7 +33,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^0.8.2",
-    "@metasession.co/devaudit-plugin-sdk": "^0.1.58",
+    "@metasession.co/devaudit-plugin-sdk": "^0.1.59",
     "ajv": "^8.20.0",
     "commander": "^12.1.0",
     "consola": "^3.2.3",

package/scripts/upload-evidence.sh

@@ -231,6 +231,8 @@ TOTAL_SIZE=0
 UPLOAD_URL="${DEVAUDIT_BASE_URL}/api/evidence/upload"
 MAX_ATTEMPTS=${UPLOAD_MAX_ATTEMPTS:-5}
 INITIAL_BACKOFF_SECONDS=${UPLOAD_INITIAL_BACKOFF_SECONDS:-1}
+UPLOAD_CONNECT_TIMEOUT_SECONDS=${UPLOAD_CONNECT_TIMEOUT_SECONDS:-10}
+UPLOAD_MAX_TIME_SECONDS=${UPLOAD_MAX_TIME_SECONDS:-120}
 
 is_unedited_starter_stub() {
   # Match BOTH banner phrasings the SDLC has shipped (v0.1.36 changed
@@ -254,7 +256,10 @@ for FILE in "${FILES[@]}"; do
   # every consumer's CI silently fails on a stale base URL. `--max-redirs 3`
   # bounds the follow so a misconfigured redirect loop can't hang CI.
   CURL_ARGS=(
-    -X POST -L --max-redirs 3 "$UPLOAD_URL"
+    -X POST -L --max-redirs 3
+    --connect-timeout "$UPLOAD_CONNECT_TIMEOUT_SECONDS"
+    --max-time "$UPLOAD_MAX_TIME_SECONDS"
+    "$UPLOAD_URL"
     -H "Authorization: Bearer ${DEVAUDIT_API_KEY}"
     -F "file=@${FILE}"
     -F "projectSlug=${PROJECT_SLUG}"
@@ -277,11 +282,31 @@ for FILE in "${FILES[@]}"; do
   BACKOFF=$INITIAL_BACKOFF_SECONDS
   HTTP_CODE=0
   RESP_BODY_FILE=""
+  RESP_HEADERS_FILE=""
+  LAST_CURL_ERROR=""
   while [ "$ATTEMPT" -le "$MAX_ATTEMPTS" ]; do
     [ -n "$RESP_BODY_FILE" ] && rm -f "$RESP_BODY_FILE"
     RESP_BODY_FILE=$(mktemp)
     RESP_HEADERS_FILE=$(mktemp)
-    HTTP_CODE=$(curl -s -o "$RESP_BODY_FILE" -D "$RESP_HEADERS_FILE" -w "%{http_code}" "${CURL_ARGS[@]}")
+    CURL_EXIT=0
+    HTTP_CODE=$(curl -s -o "$RESP_BODY_FILE" -D "$RESP_HEADERS_FILE" -w "%{http_code}" "${CURL_ARGS[@]}") || CURL_EXIT=$?
+    if [ "$CURL_EXIT" -ne 0 ]; then
+      LAST_CURL_ERROR="curl exit ${CURL_EXIT}"
+      if [ "$CURL_EXIT" -eq 28 ]; then
+        LAST_CURL_ERROR="${LAST_CURL_ERROR} (timed out after ${UPLOAD_MAX_TIME_SECONDS}s)"
+      fi
+      if [ "$ATTEMPT" -lt "$MAX_ATTEMPTS" ]; then
+        WAIT_SECONDS=$BACKOFF
+        echo -n "(${LAST_CURL_ERROR}, retry in ${WAIT_SECONDS}s) "
+        rm -f "$RESP_HEADERS_FILE"
+        sleep "$WAIT_SECONDS"
+        ATTEMPT=$((ATTEMPT + 1))
+        BACKOFF=$((BACKOFF * 2))
+        continue
+      fi
+      rm -f "$RESP_HEADERS_FILE"
+      break
+    fi
     if [ "$HTTP_CODE" -ge 200 ] && [ "$HTTP_CODE" -lt 300 ]; then
       rm -f "$RESP_HEADERS_FILE"
       break
@@ -317,8 +342,14 @@ for FILE in "${FILES[@]}"; do
     SUCCEEDED=$((SUCCEEDED + 1))
     TOTAL_SIZE=$((TOTAL_SIZE + FILE_SIZE))
   else
-    echo "FAILED (HTTP ${HTTP_CODE} after ${ATTEMPT} attempt(s))"
-    echo "  Response: $(head -c 500 "$RESP_BODY_FILE")"
+    if [ -n "$LAST_CURL_ERROR" ]; then
+      echo "FAILED (${LAST_CURL_ERROR} after ${ATTEMPT} attempt(s))"
+    else
+      echo "FAILED (HTTP ${HTTP_CODE} after ${ATTEMPT} attempt(s))"
+    fi
+    if [ -s "$RESP_BODY_FILE" ]; then
+      echo "  Response: $(head -c 500 "$RESP_BODY_FILE")"
+    fi
     rm -f "$RESP_BODY_FILE"
     FAILED=$((FAILED + 1))
   fi

package/sdlc/ai-rules/INSTRUCTIONS-SDLC.md

@@ -34,7 +34,7 @@ The default way to implement a tracked change is the **`sdlc-implementer`** skil
 Even if a change doesn't need a REQ entry:
 1. Review existing tests that cover the changed code
 2. Update or add tests BEFORE committing
-3. Run all gates locally — do not push without verifying no regressions
+3. Run the applicable local checks from the approved scope/test plan — do not push without verifying the change-relevant commands pass
 4. If the change affects financial calculations, user-facing data, or access control — it needs a REQ entry regardless of size
 
 What needs a REQ entry: New features → always. Bug fixes affecting financial data, user-facing behaviour, access control → always. Internal logic → only if MEDIUM/HIGH risk. Typos, formatting, dependency bumps → never.
@@ -47,7 +47,7 @@ When creating an issue via `gh issue create`, ALWAYS append this to the body:
 - [ ] Requirement: RTM entry created (or confirmed trivial)
 - [ ] Planning: test-scope.md and test-plan.md created (or confirmed trivial)
 - [ ] Tests: existing tests reviewed, tests updated/added
-- [ ] Gates: all pass locally (tsc, semgrep, audit, playwright)
+- [ ] Gates: applicable local checks pass; CI/UAT full gates pass where required
 - [ ] Evidence: compiled and uploaded (if tracked requirement)
 
 ### Requirement Planning (do this BEFORE coding)
@@ -73,22 +73,24 @@ Read `SDLC/2-implement-and-test.md` for full details. Summary:
 - **Before coding:** Verify ALL exist: `ls compliance/evidence/REQ-XXX/test-scope.md` AND `ls compliance/evidence/REQ-XXX/test-plan.md`. If either is missing, STOP and run planning workflow first. For MEDIUM/HIGH also verify `implementation-plan.md` exists.
 - **Phase 1 — Unit tests (TDD):** Write unit tests before implementation. Tests should initially fail. **CHECKPOINT:** Unit test coverage matches test plan.
 - **Phase 2 — Implementation:** Write the code. Unit tests should now pass. **CHECKPOINT:** All unit tests green.
-- **Phase 3 — E2E tests:** Write E2E tests against the working implementation. **CHECKPOINT:** All E2E tests green.
-- **Phase 4 — All gates:** Run full gate suite (TypeScript, SAST, dep audit, all tests, build). **CHECKPOINT:** All gates green, push to develop.
+- **Phase 3 — E2E tests:** Write E2E tests against the working implementation when the test plan calls for E2E coverage. Before starting a full local E2E suite, confirm local prerequisites (services, database, secrets, seeded auth/test data, browsers). If prerequisites are missing, run the targeted local checks from the test plan and let CI/UAT provide the authoritative full E2E gate.
+- **Phase 4 — All gates:** Run the applicable local gate suite for the change (TypeScript/SAST/dep audit/unit or targeted tests/build as specified). **CHECKPOINT:** Local scoped checks are green, then push to develop for authoritative CI gates.
 - Every commit: conventional format with `Ref: REQ-XXX` and `Co-Authored-By` for AI.
 - Add `@requirement REQ-XXX` JSDoc headers to modified files.
 - Log AI prompts in `compliance/evidence/REQ-XXX/ai-prompts.md` for MEDIUM/HIGH risk.
 
 ### Before Pushing
 
-Run ALL gates — every one must pass:
+Run the local checks required by the approved test plan/scope. For a typical code change this includes:
 ```
 npx tsc --noEmit                    # 0 errors
 semgrep scan --config auto src/     # 0 high/critical
 npm audit --audit-level=high        # 0 vulnerabilities
-npx playwright test                 # all pass
+npm test                            # unit/integration tests pass
 ```
 
+**Full local E2E boundary:** Do NOT start `npx playwright test` locally unless you have confirmed the local environment has every required service, database, secret, seeded fixture, authenticated test setup, and browser dependency. For LOW-risk docs/tooling/script-only changes, run the targeted commands in the approved test plan and rely on CI/UAT for the full E2E gate unless the operator explicitly requests a local full-suite run.
+
 **Verify test plan tests are written:** For tracked requirements, check that every test file referenced in `compliance/evidence/REQ-XXX/test-plan.md` exists and passes. If `test-plan.md` lists tests that haven't been written yet, STOP — write and run the tests before pushing.
 
 ### After Pushing: WAIT — Confirm CI Green
@@ -97,7 +99,7 @@ npx playwright test                 # all pass
 gh run list --branch develop --limit 1
 ```
 
-Do NOT proceed to evidence compilation or PR creation until CI is green. If CI fails, fix locally and re-push.
+Do NOT proceed to evidence compilation or PR creation until CI is green. If CI fails, fix locally and re-push. CI/UAT is the authoritative full E2E verification environment when local prerequisites are unavailable.
 
 ### Evidence Storage Rule
 

package/sdlc/ai-rules/README.md

@@ -22,6 +22,7 @@ devaudit update v1.5.0 ../your-project
 ```
 
 This generates:
+- `AGENTS.md` → pointer to `INSTRUCTIONS.md` and relevant `SDLC/` workflows
 - `.cursorrules` → pointer to `INSTRUCTIONS.md`
 - `.windsurfrules` → pointer to `INSTRUCTIONS.md`
 - `CLAUDE.md` → preserves project header, adds pointer to `INSTRUCTIONS.md`
@@ -95,7 +96,7 @@ Only `wawagardenbar-app` is an active consumer as of 2026-05-19; META-AGENT / ME
 This:
 1. Tags DevAudit as `sdlc-v1.1.0` and pushes the tag
 2. Copies SDLC files, hooks, scripts, and CI templates to each project
-3. Generates AI agent pointer files (.cursorrules, .windsurfrules, CLAUDE.md, GEMINI.md) referencing `INSTRUCTIONS.md`
+3. Generates AI agent pointer files (AGENTS.md, .cursorrules, .windsurfrules, CLAUDE.md, GEMINI.md) referencing `INSTRUCTIONS.md`
 4. Appends/replaces the SDLC section in `INSTRUCTIONS.md` from `INSTRUCTIONS-SDLC.md`
 5. Updates tag references in consuming project CI workflows
 6. Reports what was synced — review the diff before committing

package/sdlc/files/_common/0-project-setup.md

@@ -390,7 +390,7 @@ If any step fails, fix the configuration before starting real work.
 | Local tooling installed (Semgrep, Playwright) | [ ] |
 | Git hooks configured (Husky, Commitlint, lint-staged) | [ ] |
 | Hook verification passed (commitlint, pre-push tsc) | [ ] |
-| AI assistant SDLC rules configured (CLAUDE.md / .windsurfrules / .cursorrules) | [ ] |
+| AI assistant SDLC rules configured (AGENTS.md / CLAUDE.md / GEMINI.md / .windsurfrules / .cursorrules) | [ ] |
 | DevAudit evidence upload configured in CI | [ ] |
 | Project Test Plan created | [ ] |
 | End-to-end pipeline verified with test change | [ ] |

package/sdlc/files/_common/2-implement-and-test.md

@@ -1,5 +1,5 @@
 ---
-description: Implement changes on develop, run all local gates (tests + security scans), commit with compliance-aware conventions
+description: Implement changes on develop, run scoped local gates, and let CI/UAT provide authoritative full E2E verification when local prerequisites are unavailable
 ---
 
 # Implement & Test
@@ -14,11 +14,9 @@ description: Implement changes on develop, run all local gates (tests + security
 ## Prerequisites
 
 - On the `develop` branch
-- Dev server starts
-- Database running locally
-- Playwright browsers installed
-- Test data seeded
+- Dev server starts when the local test scope requires it
 - Semgrep installed
+- For a full local E2E suite only: database/services running locally, required secrets available, Playwright browsers installed, test data seeded, and auth/session setup configured
 
 ## Steps
 
@@ -124,7 +122,7 @@ npm test
 
 Write or update E2E tests **after** implementation. E2E tests need working UI/API to test against — writing Playwright tests against routes and selectors that don't exist is impractical.
 
-> **Skill available:** invoke the **`e2e-test-engineer`** skill for this step (at `.claude/skills/e2e-test-engineer/SKILL.md`). It derives scenarios from the requirement's acceptance criteria, reconciles with the existing test pack (flags obsoletes — but never deletes without confirmation), runs the suite, and files defects for failures or missed ACs. Framework-agnostic (Playwright, Cypress, pytest-playwright, etc.) and tracker-agnostic (GitHub, Linear, Jira, etc.). For projects with no e2e suite yet, the skill also covers bootstrapping one. See [`sdlc/SKILLS.md`](../sdlc/SKILLS.md) for the full list of available skills.
+> **Skill available:** invoke the **`e2e-test-engineer`** skill for this step (at `.claude/skills/e2e-test-engineer/SKILL.md`). It derives scenarios from the requirement's acceptance criteria, reconciles with the existing test pack (flags obsoletes — but never deletes without confirmation), checks local full-suite prerequisites before running broad E2E locally, and files defects for failures or missed ACs. Framework-agnostic (Playwright, Cypress, pytest-playwright, etc.) and tracker-agnostic (GitHub, Linear, Jira, etc.). For projects with no e2e suite yet, the skill also covers bootstrapping one. See [`sdlc/SKILLS.md`](../sdlc/SKILLS.md) for the full list of available skills.
 
 > **Run authenticated flows in CI.** Tests that need a logged-in session (admin forms, role-gated flows) belong in their own Playwright project that depends on `auth-setup`. Register that project name in `sdlc-config.json` `e2e_projects` and set `e2e_seed_command` / `e2e_env` so CI seeds fixtures and runs it as a **report-only** gate (continue-on-error — it surfaces failures as evidence without blocking the merge until proven stable). Prove each UI-driven AC with an `evidenceShot(page, 'REQ-XXX', acN, 'slug')` so the PNG lands in `compliance/evidence/REQ-XXX/screenshots/`. This is what lets Stage 3 Step 10 reduce manual UAT to a light smoke instead of a full re-click.
 
@@ -146,14 +144,23 @@ cat compliance/evidence/REQ-XXX/test-plan.md
 
 **4d. Remove obsolete E2E tests** listed in the "Tests to Remove" section (if any).
 
-### WAIT CHECKPOINT: E2E Tests Green
+### WAIT CHECKPOINT: E2E Scope Complete
 
-All E2E tests must pass:
+Run the E2E checks required by the approved test plan. Before running the full local suite, confirm the local prerequisites are present:
+
+- Required services/databases are running locally
+- Required secrets/env vars point to disposable local or test resources
+- Test data and authenticated fixtures are seeded
+- Playwright browsers and project dependencies are installed
+
+If those prerequisites are confirmed, run:
 ```bash
 npx playwright test
 ```
 
-**Do NOT proceed** until all E2E tests are green.
+If prerequisites are missing, do **not** start the full local suite. Run the targeted local checks listed in the test plan and record that full E2E verification is delegated to CI/UAT. For LOW-risk docs/tooling/script-only changes, targeted local verification is expected unless the operator explicitly requests a full local E2E run.
+
+**Do NOT proceed** until the scoped E2E/test-plan checks are complete and any local limitations are called out.
 
 ### Step 5: Stage Selectively
 
@@ -184,7 +191,7 @@ EOF
 
 Types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`, `compliance`, `security`
 
-### Step 7: Run All Local Gates (Mandatory)
+### Step 7: Run Applicable Local Gates (Mandatory)
 
 #### Gate 1: TypeScript
 ```bash
@@ -205,10 +212,13 @@ npm audit
 ```
 
 #### Gate 3: E2E Tests
+Run the E2E scope from the approved test plan. Use full local Playwright only after confirming local services, secrets, seeded data, auth fixtures, and browser dependencies are ready:
 ```bash
 npx playwright test
 ```
 
+For LOW-risk docs/tooling/script-only changes or environments without the required local prerequisites, do not run the full local suite by default. Run the targeted commands in the test plan and rely on CI/UAT for the authoritative full E2E gate.
+
 #### Exit Criteria
 
 | Gate | Threshold |
@@ -216,7 +226,7 @@ npx playwright test
 | TypeScript | 0 errors |
 | SAST (high/critical) | 0 findings |
 | Dependencies (high/critical) | 0 vulnerabilities |
-| E2E tests | All pass |
+| E2E tests | Scoped local E2E checks pass; full CI/UAT E2E passes before PR/release |
 | Severity-1 defects | 0 open |
 
 For Medium/High risk, also verify access control and audit log tests pass (see Test Plan and test-scope.md).
@@ -235,7 +245,7 @@ git push origin develop
 If rejected:
 ```bash
 git pull --rebase origin develop
-# Re-run ALL local gates after rebase
+# Re-run applicable local gates after rebase
 git push origin develop
 ```
 
@@ -251,7 +261,7 @@ gh run list --branch develop --limit 1
 gh run watch
 ```
 
-**Do NOT proceed** until CI is green. If CI fails, diagnose the failure, fix locally, re-run all local gates, and push again. Do not push repeatedly hoping CI will pass — fix the root cause.
+**Do NOT proceed** until CI is green. If CI fails, diagnose the failure, fix locally, re-run the applicable local gates, and push again. Do not push repeatedly hoping CI will pass — fix the root cause. CI/UAT is the authoritative full E2E environment when local services/secrets/seeded auth state are not available.
 
 ### Step 9: Update Evidence
 
@@ -264,7 +274,7 @@ git push origin develop
 
 ## Iteration
 
-Repeat Steps 3-9. Every commit must leave all local gates green. Step 2 (implementation plan) is done once per requirement. Each push triggers full CI and auto-deploys to UAT.
+Repeat Steps 3-9. Every commit must leave the applicable local gates green. Step 2 (implementation plan) is done once per requirement. Each push triggers full CI and auto-deploys to UAT.
 
 ## Output
 

package/sdlc/files/_common/implementing-an-sdlc-issue.md

@@ -209,7 +209,7 @@ If production smoke fails:
 
 ## Sample prompts
 
-Copy-paste these into Claude Code, Cursor, or any agent with shell access to kick off each stage. The agent should already have `AGENT.md` (portal) or the consumer's `INSTRUCTIONS.md` loaded as the canonical rules file.
+Copy-paste these into Claude Code, Cursor, or any agent with shell access to kick off each stage. The agent should already have `AGENTS.md` (consumer), `AGENT.md` (portal), or the consumer's `INSTRUCTIONS.md` loaded as the canonical rules file.
 
 > **Replace placeholders.** `{ISSUE_NUMBER}`, `{REQ_ID}`, `{PROJECT_SLUG}`, `{VERSION}` etc. are placeholders — substitute the real values before invoking.
 
@@ -231,7 +231,7 @@ stage 1 (plan-requirement) for it:
 
 STOP after the plan is posted. Do NOT begin implementation.
 
-Reference: AGENT.md (or INSTRUCTIONS.md for consumer repos), and the canonical
+Reference: AGENTS.md / INSTRUCTIONS.md for consumer repos (or AGENT.md for the portal), and the canonical
 sdlc/_common/1-plan-requirement.md from DevAudit-Installer.
 ```
 

package/sdlc/files/_common/joining-an-existing-project.md

@@ -33,7 +33,7 @@ When you `git clone`, you've already got everything the framework synced into th
 | `compliance/RTM.md`, `compliance/risk-register.md`, … | Compliance artefacts | Team — appended by tracked work |
 | `scripts/*.sh` | Helpers (`upload-evidence.sh`, `close-out-release.sh`, `validate-commits.sh`, …) | Team — synced from DevAudit-Installer |
 | `.husky/`, `.github/workflows/*.yml` | Git hooks + CI gates | Team — generated by the operator's onboarding install |
-| `.cursorrules`, `.windsurfrules`, `GEMINI.md`, `INSTRUCTIONS.md`, `CLAUDE.md` | AI rule files | Team — synced |
+| `AGENTS.md`, `.cursorrules`, `.windsurfrules`, `GEMINI.md`, `INSTRUCTIONS.md`, `CLAUDE.md` | AI rule files | Team — synced |
 | `.claude/skills/` | The `sdlc-implementer` + `e2e-test-engineer` Claude Code skills | Team — synced |
 
 Your job is to wire up the **local** half (the bits per-developer):
@@ -101,7 +101,7 @@ devaudit status .
 #   Stack:      node / python
 #   Host:       railway
 #   …
-#   ✓ INSTRUCTIONS.md, CLAUDE.md, .cursorrules, …
+#   ✓ INSTRUCTIONS.md, AGENTS.md, CLAUDE.md, .cursorrules, …
 ```
 
 If any of the framework files are missing, the operator hasn't completed onboarding yet (or your clone is behind `main` — `git pull`). Ask them to run `devaudit update`.