@metasession.co/devaudit-cli 0.1.21 → 0.1.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metasession.co/devaudit-cli",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "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.21",
+    "@metasession.co/devaudit-plugin-sdk": "^0.1.23",
     "commander": "^12.1.0",
     "consola": "^3.2.3",
     "env-paths": "^3.0.0",

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

@@ -4,6 +4,8 @@ description: One-time project setup — configure repository, CI pipeline, compl
 
 # Project Setup Guide
 
+> **For the operator only.** This guide is for the first developer setting up the project. If you're joining an **already-onboarded** project, you don't need to run any of this — the synced framework files are already in the repo. See [`SDLC/joining-an-existing-project.md`](./joining-an-existing-project.md) for the second-developer path.
+
 **Document Type:** Setup Guide | **Run Once:** At project start, before any workflow is executed
 
 **Parent Documents:** Test Policy, Test Strategy, Test Architecture (all Tier 1, in devaudit/sdlc/files/)

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

@@ -16,7 +16,7 @@ End-to-end walkthrough for taking a GitHub issue from triage to merged-and-deplo
 | Your `gh` CLI is authenticated against the project's GitHub repo                                | `gh auth status`                                   |
 | Your local checkout is on `develop` (or branched from it) and up-to-date                        | `git status`                                       |
 
-If `devaudit status` reports gaps, see [`DevAudit-Installer/docs/onboarding.md`](https://github.com/metasession-dev/DevAudit-Installer/blob/main/docs/onboarding.md) to re-sync the framework, then come back here.
+If `devaudit status` reports gaps and you're a developer joining an already-onboarded project, see [`SDLC/joining-an-existing-project.md`](./joining-an-existing-project.md) — your local clone may just need `devaudit auth login` + `devaudit join`. If the project hasn't been onboarded yet (you're the first developer), see [`DevAudit-Installer/docs/onboarding.md`](https://github.com/metasession-dev/DevAudit-Installer/blob/main/docs/onboarding.md) for the operator flow. Either way, come back here once `devaudit status` is green.
 
 ## The five stages, at a glance
 

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

@@ -0,0 +1,191 @@
+# Joining an existing project
+
+You're the second (or nth) developer joining a project that's already been DevAudit-onboarded by the first dev (the project's "operator"). This guide is for you. **Don't run `devaudit install`** — that's the operator's command and it touches the team's shared CI configuration. Use `devaudit join` instead, or just the verify commands below if you already trust the synced framework files.
+
+---
+
+## TL;DR — the five commands
+
+```bash
+npm install -g @metasession.co/devaudit-cli            # one-time, all projects
+# Issue a personal PAT at https://devaudit.metasession.co/settings/tokens
+devaudit auth login                                    # paste mctok_…
+gh auth login                                          # if not already
+devaudit doctor                                        # node ≥22, git, gh, jq, curl
+devaudit status .                                      # framework files present?
+devaudit join .                                        # re-sync templates + git hooks (optional)
+```
+
+If `devaudit doctor` and `devaudit status .` are both green, you can skip `devaudit join` — the synced framework files (`SDLC/`, `compliance/`, `scripts/`, `.husky/`, `.github/workflows/`, AI rule files) are already in the repo from the first dev's onboarding commit, and you'll get them on `git clone`. Run `join` after the next `devaudit update` from the operator, or whenever your local templates feel out of date.
+
+> **One-liner you'll want to remember:** *`install` creates / rotates / re-applies team configuration; `join` does not.* The CLI auto-detects this scenario as a safety net, but `join` is the explicit second-dev command.
+
+---
+
+## What's already in the repo (and why)
+
+When you `git clone`, you've already got everything the framework synced into the project on first install:
+
+| Path | What it is | Who owns it |
+|---|---|---|
+| `sdlc-config.json` | Project-wide config (stack, host, slug, runtime, UAT, approval mode, e2e knobs, …) | Team — committed by the operator |
+| `SDLC/*.md` | Stage walkthroughs (0-project-setup, 1-plan-requirement, …) — synced from DevAudit-Installer | Team — refreshed by `devaudit update` |
+| `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 |
+| `.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):
+
+- The CLI globally on your machine.
+- Your personal PAT in `~/.config/devaudit/auth.json` (set by `devaudit auth login`).
+- `gh` CLI authenticated against the project's GitHub repo.
+
+That's it. You **do not** create a new portal project, issue new API keys, or write new GitHub repo secrets — those belong to the operator.
+
+---
+
+## Step-by-step
+
+### 1. Install the CLI globally
+
+```bash
+npm install -g @metasession.co/devaudit-cli
+devaudit --version   # ≥ 0.1.23 — earlier versions don't have the dev-mode safety net
+```
+
+### 2. Issue + paste a personal access token
+
+Visit `https://devaudit.metasession.co/settings/tokens`, create a token (it starts with `mctok_`), then:
+
+```bash
+devaudit auth login
+# Paste the token when prompted. Stored at ~/.config/devaudit/auth.json (mode 0600).
+```
+
+Verify:
+
+```bash
+devaudit auth status
+#   token source: ~/.config/devaudit/auth.json
+#   portal:       https://devaudit.metasession.co
+#   accessible projects: <slug>, <slug>, …
+```
+
+### 3. Authenticate `gh` against GitHub
+
+```bash
+gh auth status   # already authenticated?
+# If not:
+gh auth login    # GitHub.com → HTTPS → with web browser
+```
+
+### 4. Verify your local environment
+
+```bash
+devaudit doctor
+#   ✓ node     v22.x.x (require ≥22)
+#   ✓ git      git version 2.x.x
+#   ✓ gh       gh version 2.x.x
+#   ✓ jq       jq-1.x
+#   ✓ curl     curl 8.x.x
+#   ✓ releases <N> pending ticket(s); none released on the portal
+```
+
+### 5. Verify the project is SDLC-ready
+
+```bash
+devaudit status .
+#   Project:    <slug>
+#   Stack:      node / python
+#   Host:       railway
+#   …
+#   ✓ INSTRUCTIONS.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`.
+
+### 6. (Optional) `devaudit join .` to refresh local-only state
+
+```bash
+devaudit join .
+# Runs auth probe, stack detect, hook bootstrap, template sync.
+# Skips: write sdlc-config, issue API key, set GH secrets, apply branch protection.
+```
+
+The output will tell you which steps it skipped and why (developer mode). If `git status` is clean after the join, your local state matches the team — you're done. If templates drift (occasionally on a new CLI version), commit the drift on a `chore:` branch and open a PR.
+
+You can skip this step entirely if the synced templates from `git clone` are already current — `devaudit status .` will tell you.
+
+---
+
+## The token model
+
+Two distinct credentials exist; conflating them is what causes the silent-CI-token rotation bug this guide exists to prevent.
+
+| Credential | Format | Where it lives | Who it identifies | Used by |
+|---|---|---|---|---|
+| **Personal PAT** | `mctok_…` | `~/.config/devaudit/auth.json` (per developer) | You (the user) | Your local CLI commands |
+| **Project API key** | `dak_…` | Repo secret `DEVAUDIT_API_KEY` | The project | CI's `devaudit push` calls |
+| **Operator's PAT** | `mctok_…` | Repo secret `DEVAUDIT_USER_TOKEN` | The operator (singular) | CI's mutation calls (release register, approval submit) |
+
+**Never paste your personal PAT into a repo secret.** Repo `DEVAUDIT_USER_TOKEN` is operator-owned. CI portal mutations are attributed to whoever's PAT is there — if it's yours, your name shows up against every release the team ships, and the moment your PAT expires CI breaks. Rotation belongs to the operator: `devaudit install --force-team-config` on their machine.
+
+If `devaudit auth status` shows the wrong user, run `devaudit auth logout && devaudit auth login` and paste the right PAT.
+
+---
+
+## Why not `devaudit install`
+
+`install` is the **operator's** command. It does eleven steps including:
+- writing `sdlc-config.json`,
+- creating the portal project (if absent),
+- issuing a new project API key (if absent),
+- writing four repo secrets (including `DEVAUDIT_USER_TOKEN` to whoever ran the command),
+- applying branch protection rules.
+
+A second dev running it silently rotates the team's `DEVAUDIT_USER_TOKEN` repo secret to their personal PAT — which (a) breaks CI attribution and (b) ties CI's expiry to your PAT lifetime.
+
+**As of 0.1.23 the CLI detects this scenario and routes to developer mode automatically** (skipping the destructive steps), but `devaudit join` is the explicit, intent-correct command. If you ran `install` and want to verify the safety net engaged, look at the report's "11/11 Done" line — `Done (developer mode)` means it did; `Done` (no suffix) means you were in operator mode (either a fresh project, the safety net didn't engage, or `--force-team-config` was passed).
+
+---
+
+## Local-vs-CI parity
+
+The synced CI gates expect a specific environment. Here's what you need locally if you're running them against the same project:
+
+| Surface | CI | Local (your machine) |
+|---|---|---|
+| Personal identity | `secrets.DEVAUDIT_USER_TOKEN` (operator's) | `~/.config/devaudit/auth.json` (yours) — `devaudit auth login` |
+| Project API key | `secrets.DEVAUDIT_API_KEY` | Usually unset locally — only needed if you're testing `devaudit push` against the live portal; ask the operator if you need to debug it |
+| Portal URL | `vars.DEVAUDIT_BASE_URL` | `~/.config/devaudit/auth.json` (set by `auth login`) or `$DEVAUDIT_BASE_URL` env |
+| GitHub auth | `${{ github.token }}` (auto) | `gh auth login` |
+| Node | matrix-pinned to project's `node_version` | nvm / volta / whatever — `devaudit doctor` checks ≥ 22 |
+| `jq` / `curl` | always present on GH runners | install via package manager — `devaudit doctor` flags absence |
+
+For everything else (DB migrations, env files, `npm install`), the consumer's `README.md` is the source of truth.
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `devaudit status` reports missing framework files | Local clone is behind `main`, or the operator hasn't run a recent `devaudit update` | `git pull origin develop` first; if still missing, ping the operator |
+| `devaudit auth status` says "token rejected" | PAT expired, was revoked, or you typed it wrong | Issue a fresh PAT at `/settings/tokens` and re-run `devaudit auth login` |
+| `devaudit doctor` flags missing tool | The matching binary isn't on PATH | Install via your package manager (`brew install gh`, `apt install jq`, etc.) |
+| "I ran `devaudit install` and now CI is broken" | The 0.1.23+ safety net should have caught this, but if you're on an older CLI version, `DEVAUDIT_USER_TOKEN` may have been rotated to your PAT | Ask the operator to run `devaudit install --force-team-config` from their machine — that re-writes `DEVAUDIT_USER_TOKEN` from their PAT |
+| `devaudit join` exits 7 saying "sdlc-config.json missing" | The project hasn't been onboarded yet (you're the first dev) | This is the operator's job — run `devaudit install <path>` |
+
+---
+
+## What to do next
+
+The framework's per-stage walkthrough is in `SDLC/implementing-an-sdlc-issue.md`. For day-to-day implementation work, run the `sdlc-implementer` skill from your AI assistant (Claude Code, Windsurf, Cursor — it's already synced into `.claude/skills/`):
+
+```text
+> Implement issue #N under the SDLC.
+```
+
+For the operator-side onboarding flow (your reference if you ever become the operator on a new project), see [`docs/onboarding.md`](https://github.com/metasession-dev/DevAudit-Installer/blob/main/docs/onboarding.md) in DevAudit-Installer.

package/sdlc/files/ci/check-release-approval.yml.template

@@ -70,8 +70,18 @@ jobs:
           esac
           # Bootstrap probe (#301): project may not exist in DevAudit yet —
           # the first compliance-evidence.yml run auto-creates it. A 404 here
-          # means we're on the introducing PR; pass with a notice. 401/403
+          # means we're on the introducing PR; pass with a warning. 401/403
           # means the API key is invalid → fail (not bootstrap).
+          #
+          # Defense in depth (#74): if /api/ci/projects/<slug> 404s we
+          # cross-check against /api/ci/releases/resolve — a known-good
+          # read endpoint scoped to the same project. If THAT returns 2xx
+          # the project clearly exists, and the projects-endpoint 404 is a
+          # portal-side bug. Failing closed beats silently passing the
+          # four-eyes gate. The original "GET /api/ci/projects/<slug>"
+          # endpoint didn't exist on the portal before metasession-dev/
+          # devaudit#NN, so this exact false-positive was the universal
+          # state of the gate across every consumer.
           PROJ_CODE=$(curl -s -o /dev/null -w "%{http_code}" -m 10 \
             -H "Authorization: Bearer ${DEVAUDIT_API_KEY}" \
             "${BASE%/}/api/ci/projects/${PROJECT_SLUG}" || echo "000")
@@ -80,9 +90,34 @@ jobs:
               echo "DevAudit project '${PROJECT_SLUG}' confirmed (HTTP ${PROJ_CODE})"
               ;;
             404)
-              echo "::notice::DevAudit project '${PROJECT_SLUG}' does not exist yet (HTTP 404) — bootstrap mode. Gate passes. The project will be auto-created by the first compliance-evidence.yml run; enforcement kicks in on the next PR after that."
-              echo "BOOTSTRAP_MODE=true" >> "$GITHUB_ENV"
-              exit 0
+              # Cross-check: does the project actually exist? versionPrefix=v
+              # matches every release version shape (REQ-XXX, vYYYY.MM.DD,
+              # vX.Y.Z) — we don't care about the body, only whether the
+              # endpoint authorises the project. Endpoint returns 200 even
+              # when no releases match the prefix (just with latest: null).
+              CROSS_CODE=$(curl -s -o /dev/null -w "%{http_code}" -m 10 \
+                -H "Authorization: Bearer ${DEVAUDIT_API_KEY}" \
+                "${BASE%/}/api/ci/releases/resolve?projectSlug=${PROJECT_SLUG}&versionPrefix=v" \
+                || echo "000")
+              case "$CROSS_CODE" in
+                2*)
+                  echo "::error::Portal /api/ci/projects/${PROJECT_SLUG} returned 404 but releases/resolve confirms the project exists (HTTP ${CROSS_CODE}). This is a portal-side issue (missing or broken endpoint), not a bootstrap. Failing closed to avoid silently bypassing the four-eyes gate. Triage at metasession-dev/devaudit (and/or DevAudit-Installer#75)."
+                  exit 1
+                  ;;
+                404)
+                  echo "::warning::DevAudit project '${PROJECT_SLUG}' does not exist yet (HTTP 404 from both /api/ci/projects and /api/ci/releases/resolve) — bootstrap mode. Gate passes. The project will be auto-created by the first compliance-evidence.yml run; enforcement kicks in on the next PR after that."
+                  echo "BOOTSTRAP_MODE=true" >> "$GITHUB_ENV"
+                  exit 0
+                  ;;
+                401|403)
+                  echo "::error::DevAudit returned HTTP ${CROSS_CODE} for releases/resolve on project '${PROJECT_SLUG}' (cross-check after the projects endpoint 404'd) — API key is invalid or lacks access. Verify DEVAUDIT_API_KEY belongs to the right project."
+                  exit 1
+                  ;;
+                *)
+                  echo "::error::Cross-check endpoint /api/ci/releases/resolve returned unexpected HTTP ${CROSS_CODE} after the projects endpoint 404'd. Investigate before retrying."
+                  exit 1
+                  ;;
+              esac
               ;;
             401|403)
               echo "::error::DevAudit returned HTTP ${PROJ_CODE} for project '${PROJECT_SLUG}' — API key is invalid or lacks access. Verify DEVAUDIT_API_KEY belongs to the right project."