@metasession.co/devaudit-cli 0.1.1 → 0.1.3

package/sdlc/files/hosts/_schema/adapter.schema.json

@@ -0,0 +1,103 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://devaudit.metasession.co/sdlc/hosts/adapter.schema.json",
+  "title": "Host adapter manifest",
+  "description": "Declares a hosting platform's deploy trigger, production-URL resolution, and post-deploy hooks. One adapter per platform — railway, vercel, fly, kubernetes, self-hosted-docker, etc.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "name",
+    "description",
+    "deploy_trigger",
+    "production_url_from"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Optional self-reference to the schema URL for editor tooling."
+    },
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]{0,31}$",
+      "description": "Lowercase identifier — matches the parent directory under sdlc/files/hosts/ and the `host` key in sdlc-config.json."
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "description": "One-line human summary of what this host is and how it deploys."
+    },
+    "deploy_trigger": {
+      "type": "string",
+      "enum": ["push_to_main", "git_tag", "manual", "ci_step"],
+      "description": "What triggers a production deploy on this host. `push_to_main` (Railway), `git_tag` (some Vercel setups), `manual` (operator clicks), `ci_step` (workflow runs an explicit deploy command)."
+    },
+    "production_url_from": {
+      "type": "string",
+      "enum": ["secret", "static", "api_lookup", "env"],
+      "description": "Where the production URL comes from. `secret` — name configured per-project via sdlc-config.json. `static` — hardcoded in adapter. `api_lookup` — resolved by calling the host's API. `env` — read from an env var in the running workflow."
+    },
+    "production_url_secret_key": {
+      "type": "string",
+      "description": "When `production_url_from` is `secret`, the sdlc-config.json key whose value names the GitHub Secret holding the URL. Typically `production_url_secret`."
+    },
+    "production_url_static": {
+      "type": "string",
+      "description": "When `production_url_from` is `static`, the literal URL (or template string)."
+    },
+    "wait_for_deploy": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Optional shell command snippet that 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 (e.g. push-to-main on Railway typically completes by the time CI re-runs)."
+    },
+    "post_deploy_hook": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Optional shell command snippet that runs after a successful deploy — e.g. cache warmup, smoke test, host-specific bookkeeping. Embedded into post-deploy-prod.yml.template."
+    },
+    "required_secrets": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true,
+      "description": "GitHub Secrets the host adapter expects to be set on the consumer repo. Sync may warn if missing; CI workflows will fail at runtime if they're not present."
+    },
+    "required_env": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true,
+      "description": "Environment variables the consumer must set (typically populated from sdlc-config.json fields). Separate from `required_secrets` because env vars are non-sensitive identifiers (app names, region IDs)."
+    },
+    "config_keys": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "required": {
+          "type": "array",
+          "items": { "type": "string" },
+          "uniqueItems": true
+        },
+        "optional": {
+          "type": "array",
+          "items": { "type": "string" },
+          "uniqueItems": true
+        },
+        "defaults": { "type": "object" }
+      },
+      "description": "sdlc-config.json keys this host adapter consumes. `required` keys must be present; `optional` are tolerated; `defaults` provides fallback values."
+    },
+    "notes": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Free-form notes about the host's quirks — backed up here so future maintainers don't have to rediscover them. Not consumed by templates."
+    }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "production_url_from": { "const": "secret" } } },
+      "then": { "required": ["production_url_secret_key"] }
+    },
+    {
+      "if": { "properties": { "production_url_from": { "const": "static" } } },
+      "then": { "required": ["production_url_static"] }
+    }
+  ]
+}

package/sdlc/files/hosts/railway/adapter.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "../_schema/adapter.schema.json",
+  "name": "railway",
+  "description": "Railway-hosted services. Push-to-main auto-deploy; production URL from a repo secret; deploys verified by curling the URL until it responds 2xx/3xx.",
+  "deploy_trigger": "push_to_main",
+  "production_url_from": "secret",
+  "production_url_secret_key": "production_url_secret",
+  "wait_for_deploy": "for i in $(seq 1 30); do HTTP_CODE=$(curl -s -o /dev/null -w \"%{http_code}\" \"${PROD_URL}/\" || echo \"000\"); if [ \"$HTTP_CODE\" -ge 200 ] && [ \"$HTTP_CODE\" -lt 400 ]; then echo \"Production is up (HTTP ${HTTP_CODE})\"; break; fi; echo \"Attempt ${i}/30: HTTP ${HTTP_CODE} — waiting 10s...\"; sleep 10; done",
+  "required_secrets": [
+    "DEVAUDIT_API_KEY"
+  ],
+  "config_keys": {
+    "required": [
+      "production_url_secret",
+      "runner"
+    ],
+    "optional": [
+      "database_service",
+      "database_image",
+      "database_port",
+      "database_env"
+    ],
+    "defaults": {
+      "runner": "ubuntu-latest"
+    }
+  },
+  "notes": [
+    "Railway auto-deploys on push to main; no explicit deploy step needed in CI.",
+    "Production URL is set as a repo secret (name configured per-project via production_url_secret in sdlc-config.json).",
+    "Test-time database services are declared per-project (database_service, database_image, database_port, database_env) so CI can spin up a matching container alongside the app container."
+  ]
+}

package/sdlc/files/sdlc-config.example.json

@@ -0,0 +1,74 @@
+{
+  "_comment": "SDLC project configuration — used by `devaudit install` / `devaudit update` to generate CI workflows",
+
+  "project_slug": "your-project-slug",
+  "production_url_secret": "YOUR_PROJECT_PROD_URL",
+  "node_version": 20,
+  "runner": "self-hosted",
+
+  "source_dirs": "app/ lib/ src/",
+  "sast_baseline": 0,
+  "accepted_dep_risks": "",
+
+  "database_service": "mongodb",
+  "database_image": "mongo:7",
+  "database_port": "27017",
+  "database_env": {
+    "MONGODB_URI": "mongodb://localhost:27017",
+    "MONGODB_DB_NAME": "your_test_db"
+  },
+
+  "app_env": {
+    "NODE_ENV": "test",
+    "NEXT_PUBLIC_APP_URL": "http://localhost:3000",
+    "NEXT_PUBLIC_API_URL": "http://localhost:3000/api"
+  },
+
+  "build_env": {
+    "MONGODB_URI": "mongodb://localhost:27017",
+    "MONGODB_DB_NAME": "placeholder"
+  },
+
+  "e2e_project": "chromium",
+  "e2e_start_command": "npm run dev",
+
+  "paths_ignore": [
+    ".github/workflows/**",
+    "SDLC/**",
+    "compliance/**",
+    "*.md",
+    ".cursorrules",
+    ".windsurfrules",
+    "sdlc-config.json",
+    "scripts/upload-evidence.sh",
+    "scripts/validate-compliance-artifacts.sh",
+    "scripts/validate-commits.sh",
+    "scripts/check-requirement-jsdoc.sh"
+  ],
+
+  "_comment_devaudit": "DevAudit destination. base_url lives in git so URL changes are visible in PR review. Falls back to repo Variable DEVAUDIT_BASE_URL if base_url is empty (deprecated in v1.23.0).",
+  "devaudit": {
+    "base_url": "https://devaudit.metasession.co",
+    "project_slug": "",
+    "api_key_secret": "DEVAUDIT_API_KEY"
+  },
+
+  "_comment_uat": "UAT-environment verification (Stage 3 Step 10). Opt-in: enabled=false skips Step 10 entirely. When enabled, only requirements whose risk class is listed in required_risk_classes go through UAT-env verification.",
+  "uat": {
+    "enabled": false,
+    "url": "",
+    "required_risk_classes": ["payment", "destructive_migration", "realtime", "physical_ux"]
+  },
+
+  "_comment_approval": "Four-eyes release approval policy (Stage 3 Step 11). dual_actor = DevAudit enforces approver ≠ release_creator. solo_with_gap = self-approval allowed with documented control gap in compliance/risk-register.md. auto_low_risk = LOW-risk auto-approved by CI, MEDIUM/HIGH require human.",
+  "approval": {
+    "mode": "dual_actor",
+    "auto_low_risk_threshold": "LOW"
+  },
+
+  "_comment_production_review": "Post-deploy production review gate (Stage 5). terminal_status='prod_review' (default, Option A) means post-deploy-prod.yml stops at prod_review; a human in the portal clicks 'Approve Production' (→ prod_approved) then 'Mark as Released' (→ released) for an explicit two-event audit trail. terminal_status='released' (Option B) preserves the v1.21.x auto-release behaviour — workflow PATCHes straight to released with no human click. Closes #138.",
+  "production_review": {
+    "enabled": true,
+    "terminal_status": "prod_review"
+  }
+}

package/sdlc/files/stacks/_schema/adapter.schema.json

@@ -0,0 +1,151 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://devaudit.metasession.co/sdlc/stacks/adapter.schema.json",
+  "title": "Stack adapter manifest",
+  "description": "Declares a stack's quality-gate commands, hooks framework, and per-stack scripts. One adapter per language/package-manager combination — e.g. node, python, go.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "name",
+    "description",
+    "manifest_file",
+    "hook_framework",
+    "hook_install_dir",
+    "install",
+    "type_check",
+    "sast",
+    "dep_audit",
+    "test",
+    "build",
+    "evidence_paths",
+    "runtime_setup"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Optional self-reference to the schema URL for editor tooling."
+    },
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]{0,31}$",
+      "description": "Lowercase identifier — matches the parent directory under sdlc/files/stacks/ and the `stack` key in sdlc-config.json."
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "description": "One-line human summary of what this stack is."
+    },
+    "manifest_file": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The dependency manifest the consuming project carries — package.json, pyproject.toml, go.mod, Cargo.toml, etc."
+    },
+    "hook_framework": {
+      "type": "string",
+      "enum": ["husky", "pre-commit", "lefthook", "cargo-husky"],
+      "description": "Which git-hooks framework the consuming project uses. Determines which hook files are placed and where."
+    },
+    "hook_install_dir": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Directory the hook framework manages — e.g. .husky, .git/hooks. Sync only writes hooks if this directory exists in the consumer (so projects opt in by bootstrapping the framework first)."
+    },
+    "hooks": {
+      "type": "array",
+      "items": { "type": "string" },
+      "uniqueItems": true,
+      "description": "Hook filenames to place under hook_install_dir/. Each must exist at sdlc/files/stacks/<name>/hooks/<filename>."
+    },
+    "hook_config_files": {
+      "type": "array",
+      "items": { "type": "string" },
+      "uniqueItems": true,
+      "description": "Hook framework config files placed at the consumer's repo root — e.g. commitlint.config.mjs for husky+commitlint, .pre-commit-config.yaml for pre-commit."
+    },
+    "stack_scripts": {
+      "type": "array",
+      "items": { "type": "string" },
+      "uniqueItems": true,
+      "description": "Stack-specific helper scripts copied to the consumer's scripts/ directory. Each must exist at sdlc/files/stacks/<name>/scripts/<filename>."
+    },
+    "required_dev_dependencies": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true,
+      "description": "Dev-time dependencies the adapter assumes are present (e.g. husky for node). Sync may auto-install them or warn if missing — implementation detail of the sync script."
+    },
+    "install": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Command CI runs once to fetch dependencies — `npm ci`, `pip install -e \".[dev]\"`, `go mod download`, etc."
+    },
+    "type_check": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Command that returns non-zero if static type-checking fails. MUST output 0 errors on a green build."
+    },
+    "sast": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Command that runs the SAST scanner and writes results to evidence_paths.sast. MUST exit 0 unless the scanner itself failed (findings above baseline are caught by downstream evaluation, not by this command's exit code)."
+    },
+    "dep_audit": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Command that runs the dependency audit and writes results to evidence_paths.dep_audit. Same exit-code semantics as `sast`."
+    },
+    "test": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Command that runs the full test suite (unit + integration). MUST exit 0 only if every test passes. Should also produce machine-readable output at evidence_paths.test."
+    },
+    "build": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Command that produces the deployable artifact. MUST exit 0 only on a successful build."
+    },
+    "evidence_paths": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["sast", "dep_audit", "test"],
+      "properties": {
+        "sast": { "type": "string", "minLength": 1 },
+        "dep_audit": { "type": "string", "minLength": 1 },
+        "test": { "type": "string", "minLength": 1 }
+      },
+      "description": "Repo-relative paths where each gate's machine-readable output lands. The compliance-evidence upload workflow reads these to know what to publish to DevAudit."
+    },
+    "runtime_setup": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["action", "with"],
+      "properties": {
+        "action": {
+          "type": "string",
+          "pattern": "^[^@]+@v[0-9]+$",
+          "description": "GitHub Actions reference — e.g. actions/setup-node@v4, actions/setup-python@v5."
+        },
+        "with": {
+          "type": "object",
+          "additionalProperties": { "type": "string" }
+        }
+      },
+      "description": "GitHub Actions step that installs the language runtime in CI. Embedded into ci.yml.template at sync time."
+    },
+    "config_keys": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "required": {
+          "type": "array",
+          "items": { "type": "string" },
+          "uniqueItems": true
+        },
+        "defaults": {
+          "type": "object"
+        }
+      },
+      "description": "sdlc-config.json keys this stack consumes. `required` lists keys that must be present; `defaults` provides values the adapter will fall back to when a key is absent."
+    }
+  }
+}

package/sdlc/files/stacks/node/adapter.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "../_schema/adapter.schema.json",
+  "name": "node",
+  "description": "Node.js / npm / TypeScript stack with husky hooks, commitlint, ESLint, Prettier, Playwright E2E.",
+  "manifest_file": "package.json",
+  "hook_framework": "husky",
+  "hook_install_dir": ".husky",
+  "hooks": ["commit-msg", "pre-commit", "pre-push"],
+  "hook_config_files": ["commitlint.config.mjs", "lint-staged.config.mjs", ".prettierrc.json"],
+  "stack_scripts": ["check-requirement-jsdoc.sh"],
+  "required_dev_dependencies": [
+    "husky",
+    "@commitlint/cli",
+    "@commitlint/config-conventional",
+    "lint-staged",
+    "prettier",
+    "eslint",
+    "typescript",
+    "@playwright/test"
+  ],
+  "install": "npm ci",
+  "type_check": "npx tsc --noEmit",
+  "sast": "npx semgrep scan --config auto --json",
+  "dep_audit": "npm audit --json --audit-level=high",
+  "test": "npm test",
+  "build": "npm run build",
+  "evidence_paths": {
+    "sast": "ci-evidence/sast-results.json",
+    "dep_audit": "ci-evidence/dependency-audit.json",
+    "test": "ci-evidence/e2e-results.json"
+  },
+  "runtime_setup": {
+    "action": "actions/setup-node@v4",
+    "with": { "node-version": "{{NODE_VERSION}}", "cache": "npm" }
+  },
+  "config_keys": {
+    "required": [
+      "node_version",
+      "source_dirs",
+      "sast_baseline",
+      "accepted_dep_risks",
+      "e2e_project",
+      "e2e_start_command"
+    ],
+    "defaults": {
+      "node_version": 20,
+      "source_dirs": "app/ lib/",
+      "sast_baseline": 0,
+      "accepted_dep_risks": "",
+      "e2e_project": "chromium",
+      "e2e_start_command": "npm run dev"
+    }
+  }
+}

package/sdlc/files/stacks/node/hooks/.prettierrc.json

@@ -0,0 +1,9 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "printWidth": 100,
+  "tabWidth": 2,
+  "trailingComma": "all",
+  "arrowParens": "always",
+  "endOfLine": "lf"
+}

package/sdlc/files/stacks/node/hooks/commit-msg

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# Husky commit-msg hook — runs commitlint to validate commit message format.
+# Enforces Conventional Commits and checks for SDLC trailers.
+#
+# Install: cp this file to .husky/commit-msg && chmod +x .husky/commit-msg
+
+npx commitlint --edit "$1"

package/sdlc/files/stacks/node/hooks/commitlint.config.mjs

@@ -0,0 +1,64 @@
+/**
+ * Commitlint configuration for Metasession SDLC.
+ *
+ * Enforces:
+ * - Conventional Commits format (feat, fix, docs, test, refactor, chore, compliance, security)
+ * - Co-Authored-By tag presence (warning — not every commit is AI-generated)
+ * - Ref: REQ-XXX trailer presence (warning — trivial commits skip requirements)
+ *
+ * Install:
+ *   npm install --save-dev @commitlint/cli @commitlint/config-conventional
+ *   cp this file to your project root as commitlint.config.mjs
+ */
+
+export default {
+  extends: ['@commitlint/config-conventional'],
+  rules: {
+    // Allow SDLC-specific commit types beyond the conventional set
+    'type-enum': [
+      2,
+      'always',
+      [
+        'feat',
+        'fix',
+        'docs',
+        'test',
+        'refactor',
+        'chore',
+        'compliance',
+        'security',
+        'perf',
+        'ci',
+        'build',
+        'revert',
+      ],
+    ],
+    // Warn (not error) when body is missing — some commits are one-liners
+    'body-empty': [1, 'never'],
+  },
+  plugins: [
+    {
+      rules: {
+        'trailer-ref-requirement': ({ raw }) => {
+          // Warn if Ref: REQ-XXX is missing — trivial commits don't need it
+          const hasRef = /Ref:\s*REQ-\d+/i.test(raw);
+          return [
+            hasRef,
+            'Commit should include "Ref: REQ-XXX" for tracked requirements',
+          ];
+        },
+        'trailer-co-authored-by': ({ raw }) => {
+          // Warn if Co-Authored-By is missing — not every commit is AI-generated
+          const hasCoAuthor = /Co-Authored-By:/i.test(raw);
+          return [
+            hasCoAuthor,
+            'AI-generated commits should include a "Co-Authored-By:" tag',
+          ];
+        },
+      },
+    },
+  ],
+  // Apply custom rules as warnings (level 1), not errors
+  // Override in your project if you want stricter enforcement
+  helpUrl: 'https://www.conventionalcommits.org/',
+};

package/sdlc/files/stacks/node/hooks/lint-staged.config.mjs

@@ -0,0 +1,16 @@
+/**
+ * lint-staged configuration for Metasession SDLC node-stack consumers.
+ *
+ * Runs on staged files only via the pre-commit husky hook:
+ *   - TS/JS sources: ESLint --fix then Prettier --write
+ *   - Other files:   Prettier --write
+ *
+ * Consumer projects can override by replacing this file. The sync script
+ * re-copies it on every run, so persistent local overrides should live
+ * in a separate file (.lintstagedrc.json, etc.) which takes precedence.
+ */
+
+export default {
+  '*.{ts,tsx,js,jsx}': ['eslint --fix', 'prettier --write'],
+  '*.{json,css,md,yml,yaml}': ['prettier --write'],
+};

package/sdlc/files/stacks/node/hooks/pre-commit

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# Husky pre-commit hook — runs lint-staged on staged files.
+# Catches linting issues before they enter the commit history.
+#
+# Install: cp this file to .husky/pre-commit && chmod +x .husky/pre-commit
+#
+# Requires lint-staged config in package.json:
+#   "lint-staged": {
+#     "*.{ts,tsx}": ["eslint --fix"],
+#     "*.{ts,tsx,js,jsx,json,md}": ["prettier --write"]
+#   }
+
+npx lint-staged

package/sdlc/files/stacks/node/hooks/pre-push

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Husky pre-push hook — runs TypeScript check as a fast gate before push.
+# The full test suite (E2E, SAST, dependency audit) runs in CI.
+#
+# Install: cp this file to .husky/pre-push && chmod +x .husky/pre-push
+
+echo "Pre-push: running TypeScript check..."
+npx tsc --noEmit
+if [ $? -ne 0 ]; then
+  echo ""
+  echo "ERROR: TypeScript check failed. Fix type errors before pushing."
+  echo "Run 'npx tsc --noEmit' to see all errors."
+  exit 1
+fi
+echo "Pre-push: TypeScript check passed."

package/sdlc/files/stacks/node/scripts/check-requirement-jsdoc.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+# check-requirement-jsdoc.sh — Validates that modified source files contain @requirement JSDoc tags.
+#
+# Usage:
+#   ./scripts/check-requirement-jsdoc.sh [base-branch]
+#
+# Checks files changed between base-branch and HEAD for @requirement REQ-XXX JSDoc comments.
+# Reports warnings for files missing the tag. Exits 0 (warnings only) by default.
+# Set STRICT=1 to exit non-zero on missing tags.
+#
+# Install: cp this file to your project's scripts/ directory && chmod +x scripts/check-requirement-jsdoc.sh
+# CI usage: add as a step in your PR validation job.
+
+set -euo pipefail
+
+BASE_BRANCH="${1:-origin/main}"
+STRICT="${STRICT:-0}"
+EXIT_CODE=0
+
+# Get source files changed in this branch (exclude test files, configs, compliance docs)
+CHANGED_FILES=$(git diff --name-only --diff-filter=ACMR "$BASE_BRANCH"...HEAD -- \
+  '*.ts' '*.tsx' \
+  ':!*.spec.ts' ':!*.spec.tsx' ':!*.test.ts' ':!*.test.tsx' \
+  ':!*.config.*' ':!*.d.ts' \
+  ':!compliance/' ':!e2e/' ':!__tests__/' ':!tests/' \
+  2>/dev/null || true)
+
+if [ -z "$CHANGED_FILES" ]; then
+  echo "No source files changed — skipping @requirement check."
+  exit 0
+fi
+
+MISSING_COUNT=0
+TOTAL_COUNT=0
+
+while IFS= read -r file; do
+  [ -f "$file" ] || continue
+  TOTAL_COUNT=$((TOTAL_COUNT + 1))
+
+  if ! grep -q '@requirement REQ-' "$file"; then
+    echo "WARNING: Missing @requirement JSDoc tag: $file"
+    MISSING_COUNT=$((MISSING_COUNT + 1))
+  fi
+done <<< "$CHANGED_FILES"
+
+echo ""
+echo "Checked $TOTAL_COUNT source files: $((TOTAL_COUNT - MISSING_COUNT)) have @requirement, $MISSING_COUNT missing."
+
+if [ "$MISSING_COUNT" -gt 0 ] && [ "$STRICT" = "1" ]; then
+  echo "STRICT mode: failing due to missing @requirement tags."
+  EXIT_CODE=1
+fi
+
+exit $EXIT_CODE

package/sdlc/files/stacks/python/adapter.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "../_schema/adapter.schema.json",
+  "name": "python",
+  "description": "Python stack (3.11+) with pre-commit hooks, ruff (lint + format), mypy --strict, pytest, pip-audit, semgrep.",
+  "manifest_file": "pyproject.toml",
+  "hook_framework": "pre-commit",
+  "hook_install_dir": ".git/hooks",
+  "hooks": [],
+  "hook_config_files": [".pre-commit-config.yaml"],
+  "stack_scripts": [],
+  "required_dev_dependencies": ["pytest", "ruff", "mypy", "pip-audit", "pre-commit"],
+  "install": "pip install -e \".[dev]\"",
+  "type_check": "mypy src/",
+  "sast": "semgrep scan --config auto --json",
+  "dep_audit": "pip-audit --format=json --strict",
+  "test": "pytest --junit-xml=ci-evidence/junit.xml",
+  "build": "python -m build",
+  "evidence_paths": {
+    "sast": "ci-evidence/sast-results.json",
+    "dep_audit": "ci-evidence/dependency-audit.json",
+    "test": "ci-evidence/junit.xml"
+  },
+  "runtime_setup": {
+    "action": "actions/setup-python@v5",
+    "with": { "python-version": "{{PYTHON_VERSION}}", "cache": "pip" }
+  },
+  "config_keys": {
+    "required": ["python_version", "source_dirs", "sast_baseline", "accepted_dep_risks"],
+    "defaults": {
+      "python_version": "3.11",
+      "source_dirs": "src/",
+      "sast_baseline": 0,
+      "accepted_dep_risks": ""
+    }
+  }
+}