@metasession.co/devaudit-cli 0.1.1 → 0.1.3

package/sdlc/STACK_ADAPTER.md

@@ -0,0 +1,130 @@
+# Stack adapter contract
+
+A stack adapter teaches the Metasession SDLC how to run quality gates and place hooks for one language / package-manager combination — `node`, `python`, `go`, `rust`, etc. Each adapter is a single directory under `sdlc/files/stacks/` containing:
+
+```
+sdlc/files/stacks/<name>/
+├── adapter.json          ← the manifest (validated against the schema)
+├── hooks/                ← git-hook files placed in consumers
+└── scripts/              ← stack-specific helper scripts
+```
+
+The manifest is the contract. The directory contents are referenced from the manifest by filename.
+
+The schema lives at [`sdlc/files/stacks/_schema/adapter.schema.json`](./files/stacks/_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`.
+
+## Required fields
+
+### Identity
+
+| Field           | Type                               | Purpose                                                                                             |
+| --------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `name`          | string (`[a-z0-9][a-z0-9-]{0,31}`) | Identifier matching the parent directory and the `stack` key in consumer `sdlc-config.json`.        |
+| `description`   | string                             | One-line human summary.                                                                             |
+| `manifest_file` | string                             | The dependency manifest the consuming project carries — `package.json`, `pyproject.toml`, `go.mod`. |
+
+### Quality-gate commands
+
+Every adapter declares six commands. Each must be runnable from the consumer's repo root. Exit-code semantics are part of the contract — downstream evaluation code (CI workflow templates, evidence-upload script) relies on them.
+
+> **Note (v1.23.0 transitional state).** The six commands and `evidence_paths` are declared in every adapter manifest, but `sdlc/files/ci/*.template` still has the Node values hardcoded for back-compat. Substituting these fields into the templates is Phase 4 of the polyglot architecture umbrella (portal repo issue #287, internal tracker); until then, changing the values in a Node adapter has no effect on generated workflows. A new (e.g. Python) adapter will land alongside the substitution refactor so the field becomes load-bearing the moment it's first different from Node.
+
+| Field        | Exit-0 means                 | Exit non-0 means                                                                                                   |
+| ------------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `install`    | dependencies fetched         | fetch failed (network, registry auth)                                                                              |
+| `type_check` | 0 type errors                | at least one type error                                                                                            |
+| `sast`       | scanner ran successfully     | scanner crashed; **findings don't fail this command** — they are evaluated separately against `sast_baseline`      |
+| `dep_audit`  | scanner ran successfully     | scanner crashed; **findings don't fail this command** — they are evaluated separately against `accepted_dep_risks` |
+| `test`       | every test passed            | at least one test failed                                                                                           |
+| `build`      | deployable artifact produced | build failed                                                                                                       |
+
+The distinction between `sast` / `dep_audit` (scanner-ran-cleanly) and `type_check` / `test` / `build` (gate-passed) is deliberate: it lets the templates report richer status — "scanner crashed" vs. "findings above baseline" — without conflating the two.
+
+### Evidence paths
+
+| Field                      | Type   | Purpose                                                                                         |
+| -------------------------- | ------ | ----------------------------------------------------------------------------------------------- |
+| `evidence_paths.sast`      | string | Repo-relative path the `sast` command writes its JSON output to.                                |
+| `evidence_paths.dep_audit` | string | Repo-relative path the `dep_audit` command writes its JSON output to.                           |
+| `evidence_paths.test`      | string | Repo-relative path the `test` command writes its results to (JUnit XML, Playwright JSON, etc.). |
+
+The compliance-evidence upload workflow reads these to know what to publish to DevAudit. Adapters MUST write to these exact paths; consumers MUST NOT override them in `sdlc-config.json` (an override would break evidence visibility).
+
+### Hooks
+
+| Field               | Type                                                    | Purpose                                                                                                                                                                            |
+| ------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `hook_framework`    | enum (`husky`, `pre-commit`, `lefthook`, `cargo-husky`) | Which git-hooks framework the consumer uses.                                                                                                                                       |
+| `hook_install_dir`  | string                                                  | Directory the framework manages (`.husky`, `.git/hooks`). Sync only writes hooks if the directory already exists in the consumer — projects opt in by bootstrapping the framework. |
+| `hooks`             | string[]                                                | Hook filenames placed under `hook_install_dir/`. Each must exist at `sdlc/files/stacks/<name>/hooks/<filename>`.                                                                   |
+| `hook_config_files` | string[]                                                | Framework config files placed at the consumer's repo root — `commitlint.config.mjs` for husky+commitlint, `.pre-commit-config.yaml` for pre-commit.                                |
+
+### Runtime setup
+
+| Field                  | Type                           | Purpose                                                                                                                                                              |
+| ---------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `runtime_setup.action` | string (`<owner>/<repo>@v<N>`) | GitHub Actions reference that installs the language runtime — `actions/setup-node@v4`, `actions/setup-python@v5`.                                                    |
+| `runtime_setup.with`   | object                         | `with:` inputs for the action. Token substitution applies — e.g. `{ "node-version": "{{NODE_VERSION}}" }` pulls `node_version` from `sdlc-config.json` at sync time. |
+
+## Optional fields
+
+| Field                       | Type     | Purpose                                                                                                                                 |
+| --------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `stack_scripts`             | string[] | Stack-specific helpers copied to the consumer's `scripts/` directory. Each must exist at `sdlc/files/stacks/<name>/scripts/<filename>`. |
+| `required_dev_dependencies` | string[] | Dev-time deps the adapter expects to be present. Sync may auto-install or warn.                                                         |
+| `config_keys.required`      | string[] | `sdlc-config.json` keys this stack consumes. Sync refuses if a required key is missing.                                                 |
+| `config_keys.defaults`      | object   | Fallback values for keys that may be omitted from `sdlc-config.json`.                                                                   |
+
+## Consumer config: `working_directory`
+
+For projects where the stack's dependency manifest (e.g. `pyproject.toml`, `package.json`) lives in a subdirectory rather than at the repo root, set `working_directory` in `sdlc-config.json`:
+
+```json
+{
+  "stack": "python",
+  "working_directory": "mission-control-api",
+  "source_dirs": "src/ tests/",
+  ...
+}
+```
+
+Behaviour when set:
+
+- The Python `ci.yml` template's `quality-gates` job applies `defaults.run.working-directory: <value>` so every `run:` step starts there. `pip install -e ".[dev]"`, `pytest`, `pip-audit`, `python -m build` all resolve correctly.
+- `source_dirs` becomes relative to `working_directory` (e.g. `src/ tests/` resolves to `mission-control-api/src/ mission-control-api/tests/` on disk; ruff/mypy/semgrep see the right files).
+- `actions/upload-artifact` paths are workspace-rooted by GHA design and are auto-prefixed with `working_directory/` so the uploaded paths match where the gate steps wrote them.
+- The downstream `upload-evidence` job downloads with `path: .` (workspace root) so file paths round-trip identically.
+
+Default: `"."` (repo root). Omitting the field is equivalent to setting `"."` — no behavioural change for projects with root-level manifests.
+
+Currently honoured by: **Python `ci.yml` template** (Phase 4 onwards). The Node `ci.yml` template doesn't substitute these tokens yet — Node consumers don't typically need it. Symmetric Node support can be added when a Node monorepo first needs it.
+
+## Adding a new stack
+
+See the step-by-step walkthrough: **[docs/adding-a-stack.md](../docs/adding-a-stack.md)** — uses the Python adapter as the worked example. The high-level shape is:
+
+1. **Create the directory** `sdlc/files/stacks/<name>/` (`<name>` must satisfy the regex above).
+2. **Author `adapter.json`** with every required field. Use `stacks/node/adapter.json` or `stacks/python/adapter.json` as a worked example.
+3. **Add hooks and scripts** referenced from the manifest. The validator does not check their existence yet; the sync script will fail at the consumer end if a referenced file is missing.
+4. **Author the per-stack `ci.yml.template`** at `sdlc/files/ci/<name>/ci.yml.template`. Stack-agnostic workflows (compliance-validation, check-release-approval, post-deploy-prod, compliance-evidence, ci-status-fallback) are shared at `sdlc/files/ci/` — no per-stack override needed for those.
+5. **Run the validator:** `node scripts/validate-adapter.cjs sdlc/files/stacks/<name>/adapter.json`. Fix any errors before opening a PR.
+6. **First consumer**: validate the adapter against at least one real project before merging. The Python adapter (Phase 4 of #287) was validated against META-AGENT, not against a fresh skeleton.
+
+## Evolution
+
+This contract is not frozen. If a new stack discovers a missing field — say, a separate `lint` command — open a PR that:
+
+1. Adds the field to the schema (`additionalProperties: false` means new fields must be schema-declared first).
+2. Updates this document.
+3. Adds the field to every existing adapter (default values where reasonable).
+4. Updates the validator and its unit tests.
+
+Backward-incompatible changes (renaming or removing a required field) need a v1.24.0-level version bump and a migration note for consumers.
+
+## Why JSON Schema (not Zod, not a TypeScript interface)
+
+- **Tooling.** Every IDE that speaks JSON Schema (which is every modern one) gets autocomplete and inline validation as you edit an adapter manifest.
+- **Language-neutral.** A future Python-only consumer can validate the same schema with `jsonschema` without pulling in Node.
+- **Stable artifact.** `adapter.schema.json` is a versioned file in the repo. A TypeScript type is implementation detail.
+
+The validator currently uses `ajv` (already a transitive dep), but the schema would be re-usable from any JSON-Schema-aware tool.

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

@@ -0,0 +1,172 @@
+## SDLC Compliance Process (MANDATORY)
+
+This project follows the Metasession SDLC framework. These rules are MANDATORY and OVERRIDE default behaviour.
+
+### SDLC Workflow Files
+
+Detailed workflow instructions are in this project's `SDLC/` directory. Read the relevant workflow file before executing each stage:
+
+- Stage 0: `SDLC/0-project-setup.md` — One-time project initialisation
+- Stage 1: `SDLC/1-plan-requirement.md` — Starting a new feature or tracked change
+- Stage 2: `SDLC/2-implement-and-test.md` — Writing and testing code
+- Stage 3: `SDLC/3-compile-evidence.md` — After implementation, before PR
+- Stage 4: `SDLC/4-submit-for-review.md` — Creating the PR to main
+- Stage 5: `SDLC/5-deploy-main.md` — After PR approval, deploying
+
+When a workflow step requires detailed commands or templates, read the full workflow file rather than relying on the summary below.
+
+### Before ANY Code Change
+
+1. Ask: "Which GitHub Issue is this for?" before writing code. Fetch it with `gh issue view NNN`.
+2. If no issue exists: ask if one should be created. When creating via `gh issue create`, ALWAYS append the SDLC checklist to the body (see below).
+3. If new requirement needed: read `SDLC/1-plan-requirement.md` and follow it BEFORE implementing.
+4. If trivial (typo/formatting): proceed without requirement but use conventional commit format.
+5. Verify `develop` branch: `git branch --show-current` — never implement on `main`.
+
+### For ALL Code Changes (including bug fixes)
+
+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
+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.
+
+### Creating GitHub Issues
+
+When creating an issue via `gh issue create`, ALWAYS append this to the body:
+
+## SDLC Checklist
+- [ ] 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)
+- [ ] Evidence: compiled and uploaded (if tracked requirement)
+
+### Requirement Planning (do this BEFORE coding)
+
+Read `SDLC/1-plan-requirement.md` for full details. Summary:
+
+1. Confirm GitHub Issue `#NNN` exists (create if needed via `gh issue create`).
+2. Get next REQ ID: `grep -oP 'REQ-\d+' compliance/RTM.md | sort -t- -k2 -n | tail -1`
+3. Classify risk (use issue labels as input): LOW (internal, no auth) / MEDIUM (PII, user-facing, APIs) / HIGH (security, payments, RBAC). AI involvement raises risk by one level.
+4. Add to `compliance/RTM.md` Part B: `| REQ-XXX | #NNN | [RISK] | compliance/evidence/REQ-XXX/ | DRAFT | -- | -- |`
+5. **MEDIUM/HIGH risk:** Create `compliance/evidence/REQ-XXX/implementation-plan.md` — document approach, files, architecture decisions. **WAIT CHECKPOINT:** Present the plan to the developer. Do NOT proceed until approved.
+6. Create `compliance/evidence/REQ-XXX/test-scope.md` with acceptance criteria (derived from the implementation plan for MEDIUM/HIGH).
+7. **WAIT CHECKPOINT:** Present the test scope to the developer. Do NOT proceed until confirmed.
+8. Create `compliance/evidence/REQ-XXX/test-plan.md` — map acceptance criteria to specific tests, list tests to add/update/remove. Distinguish unit tests (TDD, before implementation) from E2E tests (after implementation).
+9. **WAIT CHECKPOINT:** Present the test plan to the developer. Do NOT proceed until confirmed.
+10. Create `compliance/evidence/REQ-XXX/ai-use-note.md` if AI is involved.
+11. Commit plan: `compliance: [REQ-XXX] define requirement, test scope, and test plan`
+
+### During Implementation
+
+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.
+- 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:
+```
+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
+```
+
+**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
+
+```
+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.
+
+### Evidence Storage Rule
+
+Markdown stays in git. Binary/JSON evidence goes to DevAudit portal.
+
+Upload to DevAudit (NEVER commit to git):
+- E2E results (JSON), screenshots (PNG/JPG), SAST results (JSON), dependency audit (JSON), unit test output (TXT), test reports (HTML)
+
+Keep in git (small markdown, needs PR review):
+- compliance/RTM.md, test-scope.md, security-summary.md, ai-use-note.md, ai-prompts.md, release tickets
+
+### After Implementation
+
+Read `SDLC/3-compile-evidence.md` for full details, including release ticket template. Summary:
+
+1. Confirm CI is green before compiling evidence: `gh run list --branch develop --limit 1`
+2. Generate `compliance/evidence/REQ-XXX/test-execution-summary.md` — gate results, test changes, coverage against test plan
+3. Upload binary/JSON evidence to DevAudit portal
+4. Create `compliance/evidence/REQ-XXX/security-summary.md` (in git)
+5. Update RTM status to `TESTED - PENDING SIGN-OFF`
+6. Create `compliance/pending-releases/RELEASE-TICKET-REQ-XXX.md` (use template from workflow file). If the change requires post-deploy actions (data migrations, backfill scripts), document them in the release ticket's Post-Deploy Actions section with exact commands
+7. Commit compliance markdown locally (do NOT push yet — batch with UAT results)
+8. **WAIT CHECKPOINT:** Confirm CI + UAT deployment complete before UAT verification.
+9. **Verify on UAT** (if configured) — health check, smoke test, feature verification. Record in `security-summary.md`. Commit locally. Do NOT create a PR until UAT is green.
+10. **Push all compliance commits** in a single push: `git push origin develop`
+11. **Verify release in DevAudit** — CI auto-creates releases and links evidence. Check that a release exists with the current version (date-based: `v{YYYY}.{MM}.{DD}` or `v{YYYY}.{MM}.{DD}.{N}` for multiple releases on the same day) and evidence is linked.
+
+### Pre-Flight Checklist (Before Creating PR)
+
+**Do NOT create the PR until ready to merge.** Every push to `develop` while a PR is open triggers duplicate CI runs. The PR is the merge request, not the development workspace.
+
+Before creating a PR, verify ALL of the following:
+- [ ] All development and iteration is complete
+- [ ] CI green on develop (not stale): `gh run list --branch develop --limit 1`
+- [ ] Working tree clean: `git status`
+- [ ] UAT verification passed (if configured)
+- [ ] DevAudit UAT approval granted
+- [ ] For tracked requirements: test-scope.md complete, implementation-plan.md exists (MEDIUM/HIGH), RTM is `TESTED - PENDING SIGN-OFF`, release ticket created, evidence uploaded
+
+If any item fails, resolve it before proceeding.
+
+### Status Reporting (MANDATORY before handing off)
+
+Before describing a PR as "awaiting review", "waiting on reviewers", "ready to merge", "Stage 4/5 requires human action", or any other happy-path language, you MUST:
+
+1. Run `gh pr checks <PR>` and capture the full output, and `gh pr view <PR> --json mergeable,mergeStateStatus` for GitHub's own mergeability signal.
+2. If ANY required check is `fail` or `pending`, do NOT use happy-path language. Instead report:
+   - Each failing check by name, with its error (from `gh run view <RUN> --log-failed` if needed)
+   - Each pending check by name
+   - The concrete fix you are about to apply, or a specific question for the developer
+3. If `mergeStateStatus` is anything other than `CLEAN` or `BLOCKED` (blocked only by required-reviewer approval), treat it as an open issue and investigate before claiming "ready".
+4. If `gh` itself fails (auth, rate limit, network): report "status unknown — gh call failed", never assume green.
+5. Only when every required check is `pass` AND the PR is mergeable may you say "awaiting review" or "awaiting approval".
+
+A summary like "awaiting UAT + 2 reviewers" reads to the developer as "nothing to do but approve." If a required check is red, that summary is a lie by omission — the PR cannot merge regardless of what the reviewer does.
+
+This rule applies any time you summarise PR state in chat, not only at the final handoff.
+
+### Review Policy (Risk-Tiered)
+
+- **LOW risk:** CI provides independent verification. Self-merge is permitted after all CI checks pass.
+- **MEDIUM/HIGH risk:** A second human reviewer MUST approve before merge. Self-merge is NOT permitted.
+
+### Rules (NEVER break these)
+
+- NEVER code without a GitHub Issue and requirement entry for tracked changes
+- NEVER push without all four gates passing
+- NEVER self-merge a MEDIUM or HIGH risk PR — a second human reviewer MUST approve
+- NEVER use `--no-verify` to skip hooks
+- NEVER commit secrets (.env, credentials, API keys)
+- NEVER commit binary/JSON evidence to git — upload to DevAudit instead
+- NEVER create a PR to main without UAT verification passing first (if UAT configured)
+- NEVER push directly to main — always develop → PR → main
+- NEVER skip Co-Authored-By when AI generates code
+- NEVER proceed past a WAIT CHECKPOINT without developer confirmation
+- NEVER describe a PR as "awaiting review" or "ready to merge" without first running `gh pr checks <PR>` and confirming every required check is `pass`
+- ALWAYS commit compliance markdown to git (RTM, test-scope, implementation-plan, security-summary, release tickets)
+- ALWAYS use merge commits (not squash) for develop → main

package/sdlc/ai-rules/README.md

@@ -0,0 +1,103 @@
+# SDLC AI Rules
+
+Drop-in instruction files that enforce the Metasession SDLC compliance process through AI coding assistants. When added to a project, the AI assistant will guide developers through the SDLC workflow on every code change.
+
+## What These Rules Do
+
+- **Ask which GitHub Issue a change is for** before writing any code
+- **Create issues when needed** via `gh issue create`
+- **Guide requirement planning** (RTM entry with issue reference, risk classification, test scope)
+- **Enforce commit conventions** (Ref: REQ-XXX, Co-Authored-By tags)
+- **Run compliance gates** before pushing (TypeScript, SAST, dependencies, E2E)
+- **Compile evidence** after implementation (security summary, release ticket)
+- **Block anti-patterns** (pushing to main, skipping hooks, committing secrets)
+
+## Setup
+
+AI agent config files use a **single source of truth** pattern. The sync script generates pointer files that reference `INSTRUCTIONS.md`, where the SDLC rules live as the canonical source.
+
+```bash
+# Automatic setup via sync script (recommended)
+devaudit update v1.5.0 ../your-project
+```
+
+This generates:
+- `.cursorrules` → pointer to `INSTRUCTIONS.md`
+- `.windsurfrules` → pointer to `INSTRUCTIONS.md`
+- `CLAUDE.md` → preserves project header, adds pointer to `INSTRUCTIONS.md`
+- `GEMINI.md` → pointer to `INSTRUCTIONS.md`
+- `INSTRUCTIONS.md` → SDLC rules appended/replaced from `INSTRUCTIONS-SDLC.md`
+
+### Manual setup (if not using sync script)
+
+Copy `INSTRUCTIONS-SDLC.md` content into your project's `INSTRUCTIONS.md`, then create pointer files for each agent tool.
+
+## Source Files
+
+| File | Purpose |
+|------|---------|
+| `INSTRUCTIONS-SDLC.md` | Canonical SDLC rules — synced into consuming project `INSTRUCTIONS.md` |
+| `SDLC_RULES.md` | Full SDLC rules with detailed explanations (reference) |
+| `claude/CLAUDE.md` | Legacy Claude-specific format (superseded by pointer pattern) |
+| `cursor/.cursorrules` | Legacy Cursor format (superseded by pointer pattern) |
+| `windsurf/.windsurfrules` | Legacy Windsurf format (superseded by pointer pattern) |
+
+## Prerequisites
+
+Projects using these rules must have:
+
+1. **GitHub CLI (`gh`) installed and authenticated** — used to fetch and create issues:
+   ```bash
+   gh auth status   # verify you're logged in
+   ```
+2. **SDLC workflow files copied into the project** as `SDLC/` — the AI rules reference these files for detailed steps, templates, and checklists:
+   ```bash
+   cp -r path/to/devaudit/sdlc/files/ SDLC/
+   ```
+3. **Git hooks configured** (Husky + Commitlint + lint-staged) — enforces commit conventions and pre-push gates locally:
+   ```bash
+   # Install dependencies
+   npm install --save-dev husky @commitlint/cli @commitlint/config-conventional lint-staged
+   npx husky init
+
+   # Copy hook templates
+   cp path/to/devaudit/sdlc/files/hooks/commit-msg .husky/commit-msg
+   cp path/to/devaudit/sdlc/files/hooks/pre-commit .husky/pre-commit
+   cp path/to/devaudit/sdlc/files/hooks/pre-push .husky/pre-push
+   chmod +x .husky/commit-msg .husky/pre-commit .husky/pre-push
+   cp path/to/devaudit/sdlc/files/hooks/commitlint.config.mjs commitlint.config.mjs
+   ```
+4. **Validation scripts** (optional, for CI enforcement):
+   ```bash
+   cp path/to/devaudit/sdlc/files/scripts/*.sh scripts/
+   chmod +x scripts/*.sh
+   ```
+5. A `compliance/` directory with `RTM.md` (Part B must include the `Issue` column)
+6. A `compliance/evidence/` directory
+7. A `compliance/pending-releases/` directory
+8. A permanent `develop` branch with protected `main`
+
+Use `SDLC/0-project-setup.md` to initialise items 2-8 in a new project.
+
+The AI rules act as guardrails and summaries. The `SDLC/` workflow files contain the full detailed procedures. The AI assistant will read the relevant workflow file at each stage.
+
+## Syncing SDLC Updates to Consuming Projects
+
+When SDLC templates are updated in DevAudit, propagate changes to consuming projects using the sync script:
+
+```bash
+# From DevAudit root. Pass one path per active consumer.
+devaudit update v1.1.0 ../wawagardenbar-app
+```
+
+Only `wawagardenbar-app` is an active consumer as of 2026-05-19; META-AGENT / META-ATS / META-JOBS onboarding attempts were reverted (see [docs/consuming-projects.md](../../docs/consuming-projects.md)). The sync command accepts multiple consumer paths when more projects come back online.
+
+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`
+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
+
+See the CLI sync (`devaudit update`, `cli/src/update/`) for full details.