@metasession.co/devaudit-cli 0.1.1 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metasession.co/devaudit-cli",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "DevAudit CLI — installs, syncs, and operates the Metasession SDLC across consumer projects.",
   "type": "module",
   "bin": {
@@ -13,6 +13,8 @@
   "files": [
     "bin",
     "dist",
+    "sdlc",
+    "scripts",
     "README.md",
     "LICENSE"
   ],
@@ -22,25 +24,27 @@
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
+    "bundle:templates": "node tools/bundle-templates.mjs",
+    "prepack": "npm run build && npm run bundle:templates",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
     "start": "node ./bin/devaudit.js"
   },
   "dependencies": {
-    "commander": "^12.1.0",
     "@clack/prompts": "^0.8.2",
+    "@metasession.co/devaudit-plugin-sdk": "file:../plugin-sdk",
+    "commander": "^12.1.0",
     "consola": "^3.2.3",
-    "execa": "^9.5.1",
     "env-paths": "^3.0.0",
-    "@metasession.co/devaudit-plugin-sdk": "^0.1.1"
+    "execa": "^9.5.1"
   },
   "devDependencies": {
     "@types/node": "^22.9.0",
     "msw": "^2.7.0",
     "tsup": "^8.3.5",
     "typescript": "^5.7.2",
-    "vitest": "^2.1.5"
+    "vitest": "^4.1.6"
   },
   "publishConfig": {
     "access": "public"

package/scripts/upload-evidence.sh

@@ -0,0 +1,225 @@
+#!/usr/bin/env bash
+# @requirement REQ-007 - CLI upload script for CI pipelines
+# @requirement REQ-020 - Extended with release/environment/category flags
+# @requirement REQ-XXX - #224: posts to META-COMPLY's API instead of Supabase
+#
+# Usage:
+#   ./scripts/upload-evidence.sh <project-slug> <requirement-id> <evidence-type> <file-or-directory>
+#
+# Optional flags:
+#   --git-sha <sha>             Git commit SHA
+#   --ci-run-id <id>            CI run identifier
+#   --branch <branch>           Git branch name
+#   --release <version>         Release version (e.g. v1.0.0). The route
+#                               resolves it to a release UUID server-side.
+#   --create-release-if-missing Auto-create the release as 'draft' if absent
+#   --environment <env>         Environment: uat or production
+#   --category <cat>            Evidence category: ci_pipeline, local_dev,
+#                               planning, test_report, security_scan,
+#                               release_artifact
+#
+# Required environment variables:
+#   DEVAUDIT_BASE_URL  e.g. https://meta-comply-production.up.railway.app
+#   DEVAUDIT_API_KEY   project-scoped API key (uploader role); format `mc_…`.
+#                         Issue from: Project Settings → API Keys in
+#                         META-COMPLY's web UI.
+#
+# Examples:
+#   ./scripts/upload-evidence.sh meta-ats REQ-001 screenshot \
+#       compliance/evidence/REQ-001/screenshots/
+#   ./scripts/upload-evidence.sh meta-ats _compliance-docs compliance_document \
+#       compliance/RTM.md --git-sha abc123
+#   ./scripts/upload-evidence.sh meta-ats REQ-001 e2e_result \
+#       playwright-report/ --release v1.0.0 --environment uat \
+#       --category ci_pipeline --create-release-if-missing
+
+set -euo pipefail
+
+# --- Parse arguments ---
+if [ "$#" -lt 4 ]; then
+  echo "Usage: $0 <project-slug> <requirement-id> <evidence-type> <file-or-directory> [flags…]"
+  exit 1
+fi
+
+PROJECT_SLUG="$1"
+REQUIREMENT_ID="$2"
+EVIDENCE_TYPE="$3"
+FILE_PATH="$4"
+shift 4
+
+GIT_SHA=""
+CI_RUN_ID=""
+BRANCH=""
+RELEASE_VERSION=""
+CREATE_RELEASE_IF_MISSING=false
+ENVIRONMENT=""
+EVIDENCE_CATEGORY=""
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --git-sha) GIT_SHA="$2"; shift 2 ;;
+    --ci-run-id) CI_RUN_ID="$2"; shift 2 ;;
+    --branch) BRANCH="$2"; shift 2 ;;
+    --release) RELEASE_VERSION="$2"; shift 2 ;;
+    --create-release-if-missing) CREATE_RELEASE_IF_MISSING=true; shift ;;
+    --environment) ENVIRONMENT="$2"; shift 2 ;;
+    --category) EVIDENCE_CATEGORY="$2"; shift 2 ;;
+    *) echo "Unknown option: $1"; exit 1 ;;
+  esac
+done
+
+if [ -n "$ENVIRONMENT" ] && [ -z "$RELEASE_VERSION" ]; then
+  echo "Error: --environment requires --release (evidence without a release is orphaned)"
+  exit 1
+fi
+if [ -n "$RELEASE_VERSION" ] && [ -z "$EVIDENCE_CATEGORY" ]; then
+  echo "Error: --category is required when --release is specified (gate validation)"
+  exit 1
+fi
+
+if [ -z "${DEVAUDIT_BASE_URL:-}" ]; then
+  echo "Error: DEVAUDIT_BASE_URL environment variable is required"
+  exit 1
+fi
+if [ -z "${DEVAUDIT_API_KEY:-}" ]; then
+  echo "Error: DEVAUDIT_API_KEY environment variable is required (issue from"
+  echo "       Project Settings → API Keys in META-COMPLY)"
+  exit 1
+fi
+
+# Strip any trailing slash so we don't double-up later.
+DEVAUDIT_BASE_URL="${DEVAUDIT_BASE_URL%/}"
+
+# --- Build metadata JSON ---
+METADATA="{}"
+if [ -n "$GIT_SHA" ] || [ -n "$CI_RUN_ID" ] || [ -n "$BRANCH" ]; then
+  METADATA="{"
+  FIRST=true
+  if [ -n "$GIT_SHA" ]; then
+    METADATA="${METADATA}\"gitSha\":\"${GIT_SHA}\""
+    FIRST=false
+  fi
+  if [ -n "$CI_RUN_ID" ]; then
+    [ "$FIRST" = false ] && METADATA="${METADATA},"
+    METADATA="${METADATA}\"ciRunId\":\"${CI_RUN_ID}\""
+    FIRST=false
+  fi
+  if [ -n "$BRANCH" ]; then
+    [ "$FIRST" = false ] && METADATA="${METADATA},"
+    METADATA="${METADATA}\"branch\":\"${BRANCH}\""
+  fi
+  METADATA="${METADATA}}"
+fi
+
+# --- Collect files ---
+FILES=()
+if [ -d "$FILE_PATH" ]; then
+  while IFS= read -r -d '' f; do
+    FILES+=("$f")
+  done < <(find "$FILE_PATH" -type f -print0)
+else
+  FILES=("$FILE_PATH")
+fi
+if [ ${#FILES[@]} -eq 0 ]; then
+  echo "Error: No files found at $FILE_PATH"
+  exit 1
+fi
+
+# --- Upload each file via /api/evidence/upload ---
+#
+# Retry-on-429 / 5xx: consumer CI workflows fire 8-12 sequential uploads per
+# requirement (test-scope, test-plan, implementation-plan, security-summary,
+# test-execution-summary, ai-prompts, ai-use-note, uat-checklist, gates/*.json).
+# That cadence trips DevAudit's per-IP rate limiter, marking otherwise-green
+# CI runs as failed. Retry transiently with exponential backoff (1s → 16s),
+# honouring Retry-After if the portal supplies it. Auth/validation errors
+# (4xx other than 429) still fail fast — they won't fix themselves.
+#
+# Issue: devaudit#263.
+SUCCEEDED=0
+FAILED=0
+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}
+
+for FILE in "${FILES[@]}"; do
+  FILENAME=$(basename "$FILE")
+  FILE_SIZE=$(stat -c%s "$FILE" 2>/dev/null || stat -f%z "$FILE")
+  echo -n "Uploading ${FILENAME}... "
+  CURL_ARGS=(
+    -X POST "$UPLOAD_URL"
+    -H "Authorization: Bearer ${DEVAUDIT_API_KEY}"
+    -F "file=@${FILE}"
+    -F "projectSlug=${PROJECT_SLUG}"
+    -F "requirementId=${REQUIREMENT_ID}"
+    -F "evidenceType=${EVIDENCE_TYPE}"
+    -F "metadata=${METADATA}"
+  )
+  [ -n "$RELEASE_VERSION" ] && CURL_ARGS+=(-F "releaseVersion=${RELEASE_VERSION}")
+  if [ "$CREATE_RELEASE_IF_MISSING" = true ]; then
+    CURL_ARGS+=(-F "createReleaseIfMissing=true")
+  fi
+  [ -n "$BRANCH" ] && CURL_ARGS+=(-F "releaseBranch=${BRANCH}")
+  [ -n "$ENVIRONMENT" ] && CURL_ARGS+=(-F "environment=${ENVIRONMENT}")
+  [ -n "$EVIDENCE_CATEGORY" ] && CURL_ARGS+=(-F "evidenceCategory=${EVIDENCE_CATEGORY}")
+
+  ATTEMPT=1
+  BACKOFF=$INITIAL_BACKOFF_SECONDS
+  HTTP_CODE=0
+  RESP_BODY_FILE=""
+  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[@]}")
+    if [ "$HTTP_CODE" -ge 200 ] && [ "$HTTP_CODE" -lt 300 ]; then
+      rm -f "$RESP_HEADERS_FILE"
+      break
+    fi
+    # Decide whether the failure is retriable (429 or 5xx).
+    if [ "$HTTP_CODE" = "429" ] || { [ "$HTTP_CODE" -ge 500 ] && [ "$HTTP_CODE" -lt 600 ]; }; then
+      if [ "$ATTEMPT" -lt "$MAX_ATTEMPTS" ]; then
+        # Honour Retry-After (seconds) if the portal supplied it; otherwise back off.
+        WAIT_SECONDS=$BACKOFF
+        RETRY_AFTER=$(grep -i '^retry-after:' "$RESP_HEADERS_FILE" 2>/dev/null | head -1 | sed 's/^[Rr]etry-[Aa]fter:[[:space:]]*//' | tr -d '\r')
+        if [[ "$RETRY_AFTER" =~ ^[0-9]+$ ]] && [ "$RETRY_AFTER" -gt 0 ]; then
+          WAIT_SECONDS=$RETRY_AFTER
+        fi
+        echo -n "(HTTP ${HTTP_CODE}, retry in ${WAIT_SECONDS}s) "
+        rm -f "$RESP_HEADERS_FILE"
+        sleep "$WAIT_SECONDS"
+        ATTEMPT=$((ATTEMPT + 1))
+        BACKOFF=$((BACKOFF * 2))
+        continue
+      fi
+    fi
+    rm -f "$RESP_HEADERS_FILE"
+    break
+  done
+
+  if [ "$HTTP_CODE" -ge 200 ] && [ "$HTTP_CODE" -lt 300 ]; then
+    rm -f "$RESP_BODY_FILE"
+    if [ "$ATTEMPT" -gt 1 ]; then
+      echo "OK (${FILE_SIZE} bytes, attempt ${ATTEMPT}/${MAX_ATTEMPTS})"
+    else
+      echo "OK (${FILE_SIZE} bytes)"
+    fi
+    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")"
+    rm -f "$RESP_BODY_FILE"
+    FAILED=$((FAILED + 1))
+  fi
+done
+
+# --- Summary ---
+echo ""
+echo "=== Upload Summary ==="
+echo "Files: ${SUCCEEDED} succeeded, ${FAILED} failed (${#FILES[@]} total)"
+echo "Total size: $((TOTAL_SIZE / 1024)) KB"
+if [ "$FAILED" -gt 0 ]; then
+  exit 1
+fi

package/sdlc/.claude/settings.local.json

@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git init:*)",
+      "Bash(git add:*)",
+      "Bash(git branch:*)",
+      "Bash(git commit:*)",
+      "Bash(gh repo:*)"
+    ]
+  }
+}

package/sdlc/CLAUDE.md

@@ -0,0 +1,73 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What This Repository Is
+
+This is a compliance-grade SDLC template system — a set of 12 documents across two tiers that implement a workflow-driven development pipeline satisfying ISO 29119, ISO 27001, GDPR, SOC 2, and EU AI Act requirements. It is not a software application; it contains markdown templates and an accompanying article.
+
+## Repository Structure
+
+- `article.md` — Long-form article explaining the system's design and rationale
+- `files/` — The 12 template documents:
+  - **Tier 1 (universal, never project-specific):** `Test_Policy.md`, `Test_Strategy.md`, `Test_Architecture.md`, `Periodic_Security_Review_Schedule.md`
+  - **Tier 2 (project-specific, customized per project):** `0-project-setup.md` through `5-deploy-main.md` (workflows), `Test_Plan_TEMPLATE.md`, `README_TEMPLATE.md`
+
+## Key Design Principles
+
+- **Single responsibility per document.** Policy says _what_ and _why_, Strategy says _how methodically_, Architecture says _with what tools_. No content should appear in two places.
+- **Tier 1 never references a specific project.** Tools are referenced by category in Policy/Strategy; only Architecture names specific products and versions.
+- **Risk-based proportionality.** Documentation, testing depth, and review requirements scale with risk level (Low/Medium/High). AI involvement raises risk by one level for Medium/High categories.
+- **Workflow-driven compliance.** The six workflows (0-5) are executable procedures with specific commands, not guidelines. Compliance artifacts are natural outputs of following the workflows.
+
+## Development Model: Developer + AI Partner
+
+Each project follows a **single owner-developer partnered with AI coding agents** model:
+
+- **Owner-developer** provides direction, judgment, and approval. They are accountable for the project.
+- **AI agent** (Claude Code, Windsurf, Cursor) acts as implementation partner, compliance enforcer, and reviewer. The SDLC process is enforced by the AI on every code change via drop-in rules (`sdlc/ai-rules/`).
+- **Branching is trunk-based** with a permanent `develop` branch — no feature branches. Parallel work is handled by the AI within a single stream, not by multiple developers on separate branches.
+- **PR reviews** are owner-reviewed with AI-assisted verification. CI provides independent, tamper-resistant evidence. The SDLC workflows and compliance gates replace traditional team ceremonies (standups, sprint planning).
+- **The AI is the second pair of eyes.** It asks which requirement a change is for, blocks implementation until planning is complete, enforces commit conventions, runs compliance gates, and guides evidence compilation.
+
+## Workflow Sequence
+
+0. **Project Setup** (run once) — repo, branches, CI, compliance directories
+1. **Plan Requirement** — define in RTM, classify risk, generate test scope _before_ implementation
+2. **Implement and Test** — code on `develop`, all local gates green on every commit
+3. **Compile Evidence** — gather artifacts, create release ticket, update RTM
+4. **Submit for Review** — PR triggers independent CI verification + human review
+5. **Deploy to Main** — merge, verify deployment, finalize compliance artifacts
+
+## Mandatory Gates
+
+All templates assume these gates: TypeScript (0 errors), SAST/Semgrep (0 high/critical), dependency audit (0 high/critical), E2E tests (all pass), human PR approval.
+
+## Conventions in Templates
+
+- **Commit format:** Conventional Commits with `Co-Authored-By` tags for AI, `Ref: REQ-XXX` for tracked requirements
+- **Requirement IDs:** `REQ-XXX` format, tracked in `compliance/RTM.md`
+- **Status lifecycle:** DRAFT → IN PROGRESS → TESTED - PENDING SIGN-OFF → APPROVED - DEPLOYED
+- **Branching:** permanent `develop` branch, protected `main` (production), merge commits to preserve audit trail
+- **Evidence model:** local testing (comprehensive) + CI testing (independent verification, tamper-resistant)
+- **Placeholders:** Templates use `[BRACKETED_VALUES]` and `# UPDATE` markers for project-specific customization
+
+## When Editing These Templates
+
+- Maintain the separation between Tier 1 and Tier 2 — if content applies universally, it belongs in Tier 1; if project-specific, Tier 2.
+- Keep workflow documents as executable procedures with concrete commands, not abstract guidance.
+- Risk classification rules and AI governance controls are defined in Test_Policy.md and Test_Strategy.md — don't duplicate them in workflow files.
+- The article (`article.md`) should stay consistent with the templates; if you change a process in a template, check whether the article describes the old process.
+
+## Syncing Templates to Consuming Projects
+
+After updating SDLC templates, sync to consuming projects:
+
+```bash
+# Pass one path per active consumer. Only WGB is live as of 2026-05-19.
+devaudit update v1.x.0 ../wawagardenbar-app
+```
+
+This tags DevAudit, copies all templates (workflow files, AI rules, hooks, scripts, CI templates), and updates tag references in the consuming project's CI workflows. Review the diff in each project before committing.
+
+META-AGENT / META-ATS / META-JOBS onboarding attempts were reverted (see [docs/consuming-projects.md](../docs/consuming-projects.md)); pass their paths to the same command if and when they return as live consumers.

package/sdlc/HOST_ADAPTER.md

@@ -0,0 +1,127 @@
+# Host adapter contract
+
+A host adapter teaches the Metasession SDLC how to deploy and verify on one platform — `railway`, `vercel`, `fly`, `kubernetes`, `self-hosted-docker`, etc. Each adapter is a single directory under `sdlc/files/hosts/` containing:
+
+```
+sdlc/files/hosts/<name>/
+└── adapter.json          ← the manifest (validated against the schema)
+```
+
+Hosts don't usually bring their own hooks or scripts the way stacks do — the host's contribution is the deploy trigger, the URL-resolution scheme, and the wait/verify snippet that lands inside the post-deploy workflow template. So most host adapters are just a manifest.
+
+The schema lives at [`sdlc/files/hosts/_schema/adapter.schema.json`](./files/hosts/_schema/adapter.schema.json) (JSON Schema draft-07). The validator is `scripts/validate-adapter.cjs`; CI runs `node scripts/validate-adapter.cjs --all` on every push to `develop` and validates both stack and host adapters at once.
+
+## Required fields
+
+### Identity
+
+| Field         | Type                               | Purpose                                                                                     |
+| ------------- | ---------------------------------- | ------------------------------------------------------------------------------------------- |
+| `name`        | string (`[a-z0-9][a-z0-9-]{0,31}`) | Identifier matching the parent directory and the `host` key in consumer `sdlc-config.json`. |
+| `description` | string                             | One-line human summary of the platform and how it deploys.                                  |
+
+### Deploy trigger
+
+| Field            | Type                                                  | Purpose                             |
+| ---------------- | ----------------------------------------------------- | ----------------------------------- |
+| `deploy_trigger` | enum (`push_to_main`, `git_tag`, `manual`, `ci_step`) | What kicks off a production deploy. |
+
+- `push_to_main` — Railway, Vercel default. The platform watches the repo and deploys whenever `main` changes. No explicit deploy step in CI.
+- `git_tag` — Some setups deploy on tag push, not on every commit to main.
+- `manual` — Operator clicks "deploy" in the platform's UI. CI doesn't trigger anything.
+- `ci_step` — The CI workflow runs an explicit deploy command (`flyctl deploy`, `kubectl rollout`, `docker compose up`).
+
+### Production URL resolution
+
+The post-deploy workflow needs to know **the URL** of the just-deployed production service so it can run smoke tests and record evidence.
+
+| Field                       | Type                                           | Purpose                                                                                                            |
+| --------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `production_url_from`       | enum (`secret`, `static`, `api_lookup`, `env`) | Where the URL comes from.                                                                                          |
+| `production_url_secret_key` | string (when `production_url_from = secret`)   | The `sdlc-config.json` key whose value names the GitHub Secret holding the URL. Typically `production_url_secret`. |
+| `production_url_static`     | string (when `production_url_from = static`)   | The literal URL (or template).                                                                                     |
+
+- `secret` — URL stored as a GitHub Secret per-consumer. Most flexible; right when each project deploys to a different URL.
+- `static` — URL hardcoded in the adapter. Right when all consumers on this host share a fixed URL pattern (rare).
+- `api_lookup` — Adapter ships a snippet that resolves the URL by calling the host's API (e.g. `flyctl status --json`). Right when the URL is auto-generated and changes per deploy.
+- `env` — URL is set as a workflow env var from elsewhere in the consumer's CI. Right for self-hosted setups that already know the URL out-of-band.
+
+The schema enforces that `production_url_secret_key` is present iff `production_url_from = secret`, and same for `static`.
+
+## Optional fields
+
+### Wait and post-deploy
+
+| Field              | Type                   | Purpose                                                                                                                                              |
+| ------------------ | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `wait_for_deploy`  | string (shell snippet) | Blocks until the deploy is live and healthy. Embedded into `post-deploy-prod.yml.template` at sync time. Omit for hosts where deploy is synchronous. |
+| `post_deploy_hook` | string (shell snippet) | Runs after a successful deploy — cache warmup, host-specific bookkeeping, additional smoke tests.                                                    |
+
+Both snippets run in a `bash -e` step; they can reference `${PROD_URL}` and any `required_env` values.
+
+### Required secrets and env
+
+| Field              | Type     | Purpose                                                                                                                |
+| ------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `required_secrets` | string[] | GitHub Secrets the adapter expects to be set on the consumer repo. CI workflows fail at runtime if these are missing.  |
+| `required_env`     | string[] | Non-sensitive identifiers (app names, region IDs) the consumer must set — typically populated from `sdlc-config.json`. |
+
+Sync may warn if these are absent; it's a soft check (the CI workflow is the hard check, since the script can't authenticate to the host on the dev's behalf).
+
+### sdlc-config.json keys
+
+| Field                  | Type     | Purpose                                                        |
+| ---------------------- | -------- | -------------------------------------------------------------- |
+| `config_keys.required` | string[] | Keys consumers must define.                                    |
+| `config_keys.optional` | string[] | Keys consumers may define (e.g. an optional database service). |
+| `config_keys.defaults` | object   | Fallback values when a key is absent.                          |
+
+### Notes
+
+| Field   | Type     | Purpose                                                                                                                         |
+| ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `notes` | string[] | Free-form notes about the host's quirks. Backed up here so future maintainers don't rediscover them. Not consumed by templates. |
+
+## Adding a new host
+
+See the step-by-step walkthrough: **[docs/adding-a-host.md](../docs/adding-a-host.md)** — uses Fly.io as the worked example. The high-level shape is:
+
+1. **Create the directory** `sdlc/files/hosts/<name>/`.
+2. **Author `adapter.json`** with every required field. Use `hosts/railway/adapter.json` as a worked example.
+3. **Run the validator:** `node scripts/validate-adapter.cjs sdlc/files/hosts/<name>/adapter.json`. Fix any errors.
+4. **Validate against a real consumer** before merging — at least one project on this host should sync cleanly and reach `released` end-to-end. A host adapter validated only against `examples/` isn't load-bearing.
+
+## Worked example: Fly.io
+
+```json
+{
+  "$schema": "../_schema/adapter.schema.json",
+  "name": "fly",
+  "description": "Fly.io-hosted services. CI runs `flyctl deploy` explicitly; production URL discovered via the Fly API.",
+  "deploy_trigger": "ci_step",
+  "production_url_from": "api_lookup",
+  "wait_for_deploy": "for i in $(seq 1 30); do flyctl status --app \"${APP_NAME}\" --json | jq -e '.Deployment.Status == \"successful\"' && break; sleep 10; done",
+  "required_secrets": ["FLY_API_TOKEN", "DEVAUDIT_API_KEY"],
+  "required_env": ["APP_NAME"],
+  "notes": [
+    "Production URL is resolved at deploy time by flyctl — no GitHub Secret to maintain.",
+    "Deploy step runs `flyctl deploy --remote-only` in the post-deploy workflow; FLY_API_TOKEN is the auth."
+  ]
+}
+```
+
+This adapter isn't shipped yet — listed here as a sketch of what a non-Railway host adapter looks like.
+
+## Why JSON Schema
+
+Same reasons as [STACK_ADAPTER.md](./STACK_ADAPTER.md#why-json-schema-not-zod-not-a-typescript-interface): IDE tooling, language-neutrality, stable versioned artifact. The validator script is the same one stacks use — auto-detects the type from path and applies the matching schema.
+
+## Evolution
+
+Backward-compatible additions (new optional fields) need:
+
+1. Schema update.
+2. This doc updated.
+3. Existing adapters can stay as they are.
+
+Backward-incompatible changes (renaming or removing required fields, narrowing an enum) need a v1.24.0-level version bump and a migration note for consumers.

package/sdlc/SKILLS.md

@@ -0,0 +1,137 @@
+# SDLC Skills — contract and conventions
+
+The Metasession SDLC framework ships **Claude Code Skills** alongside its stage docs, adapters, and CI templates. Skills are self-contained behaviour packs the AI agent invokes when it recognises a relevant trigger — "add e2e tests for [ticket]", "classify the risk tier of this REQ", "triage these SAST findings". They specialise within stages (the stage doc owns _when and why_; the skill owns _how_).
+
+This document is the contract every framework-shipped skill must follow. For the walkthrough on adding a new skill, see [docs/adding-a-skill.md](../docs/adding-a-skill.md). For the architectural rationale on the framework's layered design, see [ADR-001](../docs/ADR/ADR-001-polyglot-sdlc-architecture.md).
+
+## Where skills live
+
+Same layering as adapters:
+
+```
+sdlc/files/
+├── _common/
+│   └── skills/                          ← universal skills (stack-agnostic)
+│       ├── _schema/skill.schema.json    ← frontmatter schema
+│       └── <skill-name>/
+│           ├── SKILL.md                 ← required: frontmatter + instructions
+│           └── references/              ← optional: longer docs the skill links to
+└── stacks/
+    ├── node/
+    │   └── skills/                      ← node-only skills (when needed)
+    └── python/
+        └── skills/                      ← python-only skills (when needed)
+```
+
+A skill is `_common/` when its body is genuinely framework-agnostic (auto-detects toolchain, doesn't depend on a single ecosystem). It's stack-scoped when its instructions assume a specific package manager, test framework, or build tool that other stacks don't share.
+
+## How skills reach consumers
+
+`devaudit update` (cli/src/update/skills.ts) copies every skill directory into the consumer's `.claude/skills/<skill-name>/` on every sync:
+
+- All `_common/skills/<name>/` directories sync to every consumer.
+- `stacks/<stack>/skills/<name>/` directories sync only when the consumer's `sdlc-config.json` selects that stack.
+- The `_schema/` directory (and any other `_`-prefixed directory) is **not** synced — schemas are framework infrastructure.
+
+Claude Code reads `.claude/skills/*/SKILL.md` for discovery; once synced, the skill is immediately available to the consumer's AI agent without further configuration.
+
+Other AI tools (Cursor, Windsurf, Gemini CLI) don't have a native Skill mechanism. The skill content is referenced from `INSTRUCTIONS.md` so non-Claude agents can still consume it manually — they don't auto-invoke based on `description` triggers, but the content is reachable.
+
+### Additional emissions
+
+A skill is allowed to ship code that the consumer's test/build tooling needs to `import` at runtime — a helper, a fixture, a shared utility. The canonical source lives under the skill's `references/` directory (so it's discoverable alongside the SKILL.md that teaches its use), and `devaudit update` emits a copy into the right place in the consumer's source tree.
+
+Currently the only such emission is the e2e-test-engineer skill's `evidence.ts` helper, which syncs to `<consumer>/e2e/helpers/evidence.ts` on node-stack consumers. The pattern: add a guarded section to the CLI skill sync (`cli/src/update/skills.ts`) — the skill's main bundle still syncs to `.claude/skills/` as normal, but the extra file lands where the consumer's tests can import it.
+
+Use this pattern sparingly. If the skill only needs to teach a concept, a Markdown example in SKILL.md is enough. If the skill prescribes a helper consumers must call from their own code, that helper deserves to be canonical and shipped — not copy-pasted from a doc.
+
+## SKILL.md frontmatter contract
+
+Required fields:
+
+| Field         | Type   | Constraint                  | Purpose                                                                                                                                                  |
+| ------------- | ------ | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`        | string | `^[a-z0-9][a-z0-9-]{1,63}$` | Identifier matching the parent directory. How Claude refers to the skill when reporting which one fired.                                                 |
+| `description` | string | minLength 50                | What the skill does **and** when to invoke it. The "when" half drives discovery — without trigger phrases, the skill never fires. Aim for 100–500 chars. |
+
+Optional fields:
+
+| Field     | Type     | Purpose                                                                                    |
+| --------- | -------- | ------------------------------------------------------------------------------------------ |
+| `version` | string   | Semver. Useful when a skill's behaviour changes incompatibly so consumers can pin.         |
+| `tags`    | string[] | Documentation grouping (e.g. `testing`, `security`, `compliance`). Not consumed by Claude. |
+| `license` | string   | SPDX identifier or `proprietary`.                                                          |
+
+`additionalProperties: false` — new fields require a deliberate schema update first.
+
+The body of SKILL.md (everything after the closing `---`) is free-form Markdown. Claude reads it as the skill's instructions. Conventions worth following:
+
+- Open with a one-paragraph summary of what the skill does.
+- A **Scope** section: in-scope and out-of-scope behaviours.
+- A **Workflow** section: numbered phases the skill walks through. Each phase should be self-contained enough that re-entering mid-skill is sensible.
+- **Principles** at the end: cross-cutting rules the skill never violates (e.g. "never delete tests without explicit confirmation").
+
+## How to write a good `description`
+
+This is the load-bearing field. Bad descriptions lead to "the skill never fires" or "the skill fires constantly on irrelevant requests". Aim for:
+
+1. **What the skill does**, in one clause. _"Maintain or bootstrap a project's end-to-end and visual regression test pack."_
+2. **When to invoke it.** Both natural-language phrasings and concrete triggers. _"Use when the user wants to add, update, or retire e2e or visual tests for a feature, ticket, issue, or PR."_ Then list explicit trigger phrases: _"Trigger on phrases like 'add e2e tests for [ticket]', 'update the test pack', 'what tests do we need for this issue'…"_
+3. **When NOT to invoke.** Explicit out-of-scope rules. _"Do NOT use for unit, component, or API-only tests, or performance tests."_
+
+If a contributor reads only the description and gets the right invocation pattern, the description is doing its job.
+
+## Validation
+
+CI runs `node scripts/validate-adapter.cjs --all` on every push to develop. The validator parses the YAML frontmatter at the top of every `SKILL.md` and validates against `sdlc/files/_common/skills/_schema/skill.schema.json`. Errors are reported with the offending field path.
+
+To validate a single skill locally:
+
+```bash
+node scripts/validate-adapter.cjs sdlc/files/_common/skills/<name>/SKILL.md
+```
+
+## Skills currently shipped
+
+| Skill               | Location          | Triggers (paraphrased)                                                                                                       | Additional emissions                             |
+| ------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
+| `e2e-test-engineer` | `_common/skills/` | "add e2e tests", "bootstrap an e2e suite", "update the test pack", "are any tests obsolete", "run e2e tests and file issues" | `e2e/helpers/evidence.ts` (node-stack consumers) |
+
+## Skills on the roadmap
+
+| Candidate skill     | Likely trigger surface                                                                                                                   | Supports SDLC stage |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
+| `sdlc-implementer`  | "implement issue #N under the SDLC", "run the SDLC for issue #N", "automate REQ-XXX from issue to release", "do the SDLC for [issue]"   | All stages (1–5)    |
+
+`sdlc-implementer` is an **orchestration skill** — it drives Claude Code's native tools (`gh`, shell, `devaudit` CLI, portal API) through the full 5-stage flow against a single GitHub issue, pausing only at the UAT-review gate (and at the plan checkpoint for HIGH/CRITICAL risk). It replaces an earlier roadmap of five atomic skills (`risk-classifier`, `commit-message-author`, `compliance-evidence-author`, `sast-triager`, `release-ticket-author`) that were deprioritised — Claude Code's innate capabilities already cover what those atomic skills wrapped; the value-add is end-to-end orchestration with framework-compliant pauses, not five discoverable helpers a human still has to compose.
+
+**Current status.** SKILL.md + 3 references files are authored at [`sdlc/files/_common/skills/sdlc-implementer/`](./files/_common/skills/sdlc-implementer/) on `main` (Phase B, PR #31). Validator passes. Phase C — smoke against `wawagardenbar-app` — is the last step before this row moves to "Skills currently shipped" above.
+
+**Sub-skill invocation requirement.** During its Phase 2 (Implement & test), the orchestrator **MUST** invoke `e2e-test-engineer` for any end-to-end or visual-regression test work — both scenario derivation from the implementation plan and execution of the resulting suite. The orchestrator does NOT author e2e tests directly. (Unit tests stay with the orchestrator until a unit-test counterpart skill ships.) The invocation pattern is documented in [docs/adding-a-skill.md §Orchestrator skills](../docs/adding-a-skill.md#orchestrator-skills-calling-other-skills); this is a hard contract — the orchestrator's SKILL.md fails review if it inlines `e2e-test-engineer`'s procedure.
+
+Tracking: [`metasession-dev/DevAudit-Installer#29`](https://github.com/metasession-dev/DevAudit-Installer/issues/29) (umbrella).
+
+Other speculative skills land when a real driver appears (a project's day-to-day work surfaces the same pain repeatedly and the orchestrator's internals demonstrably need it as a separable component).
+
+## When to make a skill vs. when to keep something in a stage doc
+
+Three rules of thumb:
+
+1. **Stage docs own _when_ and _why_.** "After Stage 2 implementation, before Stage 3 evidence compilation, the team should…" — that's stage-doc material, not skill material.
+2. **Skills own _how_.** Multi-step procedures that are reusable across requirements, opinionated about technique, and benefit from being invoked by a discovery-trigger phrase belong in skills.
+3. **If two stage docs would each instruct the AI to do the same multi-step procedure, lift it into a skill.** Both Stage 2 ("update tests") and Stage 3 ("re-run the suite, file defects") need the same e2e-test-engineering procedure. Lifting that into a skill keeps the stage docs focused on flow and avoids drift.
+
+## Evolution
+
+Backward-compatible additions to the frontmatter (new optional fields): update the schema first, then the docs, then the skills can adopt the new field.
+
+Renaming or removing a required field is a v1.next-major change with a deprecation cycle (mirror `working_directory` rollout: warn for one minor version, refuse in the next).
+
+When a skill's behaviour changes meaningfully, bump its `version`. Consumers pinning to an old version can re-sync at their own pace.
+
+## See also
+
+- [docs/adding-a-skill.md](../docs/adding-a-skill.md) — walkthrough for authoring a new skill.
+- [STACK_ADAPTER.md](./STACK_ADAPTER.md) / [HOST_ADAPTER.md](./HOST_ADAPTER.md) — sibling contracts for the adapter layers.
+- [ADR-001](../docs/ADR/ADR-001-polyglot-sdlc-architecture.md) — why the framework is layered this way.
+- [Anthropic's Claude Code Skills docs](https://docs.claude.com/en/docs/claude-code/skills) — upstream format reference.