@metasession.co/devaudit-cli 0.3.14 → 0.3.16

package/sdlc/files/ci/post-deploy-prod.yml.template

@@ -97,10 +97,18 @@ jobs:
           # release ticket (the same set the dev/UAT pipeline versioned via
           # derive-release-version.sh → REQ-XXX). A bundled develop→main PR
           # carries several; promote ALL of them, not just the first. A manual
-          # dispatch can target one via the `release` input. Fall back to a
-          # bare date for date-versioned (ticketless) releases.
+          # dispatch can target one via the `release` input. A ticketless
+          # main promotion is only valid when its explicit standalone
+          # housekeeping declaration is present and valid.
           if [ -n "${RELEASE_INPUT}" ]; then
             REQS="${RELEASE_INPUT}"
+            if [[ "$REQS" =~ ^v[0-9]{4}\.[0-9]{2}\.[0-9]{2}(\.[0-9]+)?$ ]]; then
+              chmod +x scripts/standalone-housekeeping-release.sh 2>/dev/null || true
+              DECLARATION="compliance/standalone-housekeeping/STANDALONE-HOUSEKEEPING-${REQS}.json"
+              bash scripts/standalone-housekeeping-release.sh validate "$REQS" "$DECLARATION"
+              echo "STANDALONE_DECLARATION=${DECLARATION}" >> "$GITHUB_ENV"
+              echo "TERMINAL_STATUS=released" >> "$GITHUB_ENV"
+            fi
           else
             REQS=""
             if [ -d compliance/pending-releases ]; then
@@ -111,7 +119,20 @@ jobs:
             fi
             REQS=$(echo ${REQS} | tr ' ' '\n' | sort -u | tr '\n' ' ' | sed 's/[[:space:]]*$//')
             if [ -z "${REQS}" ]; then
-              REQS="v$(date +%Y.%m.%d)"
+              chmod +x scripts/derive-release-version.sh scripts/standalone-housekeeping-release.sh 2>/dev/null || true
+              VERSION=$(bash scripts/derive-release-version.sh)
+              DECLARATION="compliance/standalone-housekeeping/STANDALONE-HOUSEKEEPING-${VERSION}.json"
+              if [ -f "$DECLARATION" ]; then
+                bash scripts/standalone-housekeeping-release.sh validate "$VERSION" "$DECLARATION"
+                REQS="$VERSION"
+                echo "STANDALONE_DECLARATION=${DECLARATION}" >> "$GITHUB_ENV"
+                # Standalone housekeeping is reviewed in its GitHub promotion
+                # PR. It does not enter the portal UAT/production queue unless
+                # a project deliberately supplies a tracked REQ instead.
+                echo "TERMINAL_STATUS=released" >> "$GITHUB_ENV"
+              else
+                echo "No tracked release ticket or standalone declaration: ordinary housekeeping has no portal promotion."
+              fi
             fi
           fi
           echo "In-scope releases to promote: ${REQS}"
@@ -413,6 +434,9 @@ jobs:
             # Carry the release ticket into the production environment so the
             # prod-review gate is self-contained.
             TICKET=""
+            if [ -n "${STANDALONE_DECLARATION:-}" ] && [ "$VERSION" = "${REQS}" ]; then
+              TICKET="$STANDALONE_DECLARATION"
+            fi
             for DIR in compliance/pending-releases compliance/approved-releases; do
               if [ -f "${DIR}/RELEASE-TICKET-${VERSION}.md" ]; then
                 TICKET="${DIR}/RELEASE-TICKET-${VERSION}.md"; break
@@ -447,6 +471,11 @@ jobs:
             fi
             # Advance status (idempotent — re-PATCHing an already-promoted release is a no-op).
             if [ -n "$RELEASE_ID" ]; then
+              if [ -n "${STANDALONE_DECLARATION:-}" ] && [ "$VERSION" = "${REQS}" ]; then
+                chmod +x scripts/standalone-housekeeping-release.sh 2>/dev/null || true
+                bash scripts/standalone-housekeeping-release.sh promote \
+                  "$PROJECT_SLUG" "$VERSION" "$STANDALONE_DECLARATION"
+              fi
               curl -s -o /dev/null -w "  ${VERSION} status patch: HTTP %{http_code}\n" \
                 -X PATCH "${BASE}/api/ci/releases/${RELEASE_ID}" \
                 -H "Authorization: Bearer ${DEVAUDIT_API_KEY}" \

package/sdlc/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metasession.co/devaudit-sdlc",
-  "version": "0.3.14",
+  "version": "0.3.16",
   "description": "DevAudit SDLC CLI Engine — cross-agent terminal-driven SDLC orchestrator.",
   "bin": {
     "devaudit-sdlc": "./src/bin/devaudit-sdlc.js"

package/sdlc/src/blueprints/3-compile-evidence.raw.md

@@ -70,37 +70,21 @@ Both `ci.yml` and `compliance-evidence.yml` call the same helper, so a feature s
 
 If you need a separate release container for a sub-piece of work — e.g. carving REQ-038 out of an in-flight feature — give it its own REQ-ID and tag the commits accordingly.
 
-## Two release shapes
+## Release modes
 
-A release is classified by its version pattern. **Most of this doc walks the tracked path** (a REQ-XXX-tagged release for a single requirement). For develop pushes that don't carry a REQ tag — typically `docs:`, `chore:`, `ci:`, `build:`, `test:`, `compliance:`, `revert:` — the version-deriver falls back to a bare date and the release is **housekeeping**.
+A release is classified by version shape and release mode. **Most of this doc walks the tracked path** (a REQ-XXX-tagged release for a single requirement). For develop pushes without a REQ tag — typically `docs:`, `chore:`, `ci:`, `build:`, `test:`, `compliance:`, `revert:` — the version deriver falls back to a bare date.
 
-| Shape | Version pattern | Triggered by | Per-REQ ceremony |
+| Mode | Version pattern | Triggered by | Outcome |
 | --- | --- | --- | --- |
 | **Tracked** | `REQ-037`, `REQ-046-FIX`, etc. | A `feat`/`fix`/`refactor`/`perf` commit (REQ tag required by commitlint) | Yes — full Steps 1-9 |
-| **Housekeeping** | `v2026.06.04` (bare date, optionally `.N`) | A push containing only REQ-exempt commit types | **No** per-REQ artefacts; the portal auto-skips test-scope, test-plan, implementation-plan, and test-execution-summary completeness checks |
+| **Integration housekeeping** | `v2026.06.04` (bare date, optionally `.N`) | A normal REQ-exempt change | Terminal-green reviewed integration history; no tracked approval ceremony |
+| **Standalone housekeeping** | `v2026.06.04` (bare date, optionally `.N`) | An explicitly declared exception | Distinct release only after its validated declaration, reason, and production verification |
 
-### Housekeeping releases — what's required
+### Housekeeping outcomes
 
-Housekeeping releases **skip** the per-requirement evidence (no REQ → no `compliance/evidence/REQ-XXX/` folder) but **still produce two release-scoped artefacts**:
+Normal housekeeping skips the per-requirement evidence and approval path. Run the relevant gates, obtain terminal-green PR review, and merge to `develop`; the bare-date portal row is integration history. When a tracked release later absorbs the work, its bundled-change manifest preserves the source title, evidence ownership, stage, and cycles.
 
-| Artefact | Tracked path | Housekeeping path | Auto-generated by CI? |
-| --- | --- | --- | --- |
-| Release ticket | `compliance/pending-releases/RELEASE-TICKET-REQ-XXX.md` (Step 8) | `compliance/pending-releases/RELEASE-TICKET-<version>.md` (e.g. `RELEASE-TICKET-v2026.06.04.md`) | **Yes** — `generate-housekeeping-release-ticket.sh` runs after `derive-release-version.sh` and emits a stub the operator reviews + signs off |
-| Security summary | `compliance/evidence/REQ-XXX/security-summary.md` (Step 4) | `compliance/security-summary-<version>.md` at the compliance root (release-scoped, not REQ-scoped) | **Yes** — `generate-security-summary.sh` scrapes the SAST + dep-audit gate JSON and emits a stub with an operator sign-off block |
-
-**Filename conventions are enforced.** Release tickets must match `RELEASE-TICKET-REQ-XXX.md` or `RELEASE-TICKET-vYYYY.MM.DD.md` exactly. Security summaries must be named `security-summary.md` exactly. The CI upload pipeline (`compliance-evidence.yml`) routes per-REQ artifacts by basename to specific `evidence_type` values — unrecognized filenames are skipped with a warning (DevAudit-Installer#205). The `validate-compliance-artifacts.sh` PR-time check also warns on unrecognized filenames in `compliance/evidence/REQ-XXX/`. The version-suffixed conventions above are recommended for **searchability + audit trail** when a project has many housekeeping releases stacked up — they keep the artefacts distinct per release without needing folder scoping.
-
-**What housekeeping operators do, end to end:**
-
-1. Push the `docs:` / `chore:` / `ci:` commits to develop. CI runs the four gates as usual.
-2. CI's `compliance-evidence.yml` workflow auto-opens a PR (`chore/housekeeping-release-<version>`) containing the two stubs.
-3. Review the stubs — confirm the commit-summary list in the release ticket is sensible, confirm the SAST + dep-audit summary reads correctly, fill in the operator sign-off block on each.
-4. Merge that PR. The next CI run picks up the artefacts and the portal's release-completeness checklist flips both items to ✓.
-5. Submit for UAT review on the portal. The approval flow is identical to the tracked path — same four-eyes rules (per project risk tier), same `draft → uat_review → uat_approved → prod_review → prod_approved → released` state machine.
-
-**No auto-approval.** Housekeeping releases still require operator action to advance through the gates. The CI-generated stubs replace the operator's authoring effort, not the operator's review.
-
-> **Versions of the framework before 2026-06 produced housekeeping stubs by hand.** Older release records may have `security-summary.md` under a REQ-XXX-shaped folder or no release ticket at all — leave those in DRAFT for the audit trail; backfilling isn't required.
+Use standalone housekeeping only when the change cannot reasonably wait for that tracked release. Follow `docs/release-playbooks/housekeeping-release.md`: add the validated `STANDALONE-HOUSEKEEPING-vYYYY.MM.DD.json` declaration, document why promotion is necessary, pass the required checks, and verify production. There is no automatic release-ticket or security-summary stub PR for either housekeeping outcome.
 
 ## Steps
 

package/sdlc/src/blueprints/5-deploy-main.raw.md

@@ -45,13 +45,13 @@ gh pr merge [PR-NUMBER] --merge --delete-branch=false
 
 **Do NOT delete `develop`** — it's the permanent working branch.
 
-### Step 2: Sync Branches
+### Step 2: Preserve GitFlow
 
-```bash
-git checkout main && git pull origin main
-git checkout develop && git pull origin develop
-git merge main --no-edit && git push origin develop
-```
+Normal release synchronization is performed by the portal-dispatched close-out
+PR after the release reaches `released`; do not directly merge the release
+branch into the integration branch. A real hotfix is the exception: after its
+reviewed merge to the release branch, open the mandatory `backmerge/*` PR to the
+integration branch and merge it only after terminal-green checks.
 
 ### Step 3: Verify Production Deployment
 
@@ -149,11 +149,11 @@ The backend stores both with reviewer identity, SHA, and timestamp. This satisfi
 
 #### Steps
 
-1. Wait for `post-deploy-prod.yml` to complete (the workflow's "Advance release status" step prints `Release vYYYY.MM.DD → prod_review` when done).
+1. Wait for `post-deploy-prod.yml` to complete successfully **and** for its host-deployment check to confirm terminal success for the merged SHA.
 2. Open the release in DevAudit: `https://[DEVAUDIT_BASE_URL]/projects/[PROJECT_SLUG]/releases/[releaseId]`.
-3. Review the `prod-smoke-results.json` evidence (uploaded by the workflow) plus any post-deploy actions logged in the release ticket.
+3. Review the production deployment and smoke cycle records, their evidence, and any post-deploy actions logged in the release ticket. Do not approve while either cycle or the host deployment remains queued/in progress.
 4. Click **Approve Production** — status transitions to `prod_approved`.
-5. Click **Mark as Released** — status transitions to `released`. Pipeline lifecycle complete in DevAudit.
+5. Click **Mark as Released** — status transitions to `released`. This dispatches the automated close-out flow.
 
 If the smoke results look wrong or a manual verification fails, click **Reject** on the production approval and follow the Rollback procedure below before retrying.
 
@@ -161,41 +161,21 @@ If the smoke results look wrong or a manual verification fails, click **Reject**
 
 `approval.mode` is checked again here. `dual_actor` means the post-deploy approver must differ from the release creator. `solo_with_gap` accepts self-approval but records the control gap. `auto_low_risk` allows LOW-risk requirements to auto-advance through both transitions on workflow completion; MEDIUM/HIGH always require a human click.
 
-### Step 6: Finalize Compliance (Tracked Requirements Only)
-
-> **Automated path (preferred).** Run the synced helper instead of doing this by hand — it flips the ticket Status → `RELEASED` (+ backlinks the release PR and records the sign-off), flips the matching `RTM.md` row, and `git mv`s the ticket to `approved-releases/`, then stages the changes for you to commit:
->
-> ```bash
-> ./scripts/close-out-release.sh REQ-XXX --release-pr <release-PR-#>
-> git add -A && git commit -m "docs(compliance): close out REQ-XXX release ticket (RELEASED)" && git push origin develop
-> ```
->
-> It is **idempotent** (a no-op if already closed out) and, when `DEVAUDIT_API_KEY` + `DEVAUDIT_BASE_URL` are set, **refuses** unless the portal reports the release as `released` (so you can't flip the local tree ahead of the Production approval). The `close-out-release.yml` workflow runs the same script automatically when the portal marks a release released (and is `workflow_dispatch`-able for catch-up). The manual steps below are the fallback / reference for what the script does.
-
-```bash
-mv compliance/pending-releases/RELEASE-TICKET-REQ-XXX.md compliance/approved-releases/
-```
+### Step 6: Automated Close-out (Tracked Requirements Only)
 
-Update `compliance/RTM.md`:
-```markdown
-| REQ-XXX | Description | [RISK] | files | evidence | APPROVED - DEPLOYED | [Reviewer] | [Date] |
-```
+When the portal status becomes `released`, it dispatches `release-closed` to the
+consumer repository. `close-out-release.yml` then opens a
+`chore/close-out-REQ-XXX` PR to the configured integration branch. That PR is
+the canonical reconciliation record: it updates the RTM, moves the release
+ticket to `approved-releases/`, and moves manifest-listed absorbed predecessors
+to `superseded-releases/`.
 
-Add audit trail to release ticket:
-```markdown
-| [date] | UAT verification passed | [who] | Health + smoke + feature verified on UAT |
-| [date] | PR approved | [reviewer] | PR #[number] |
-| [date] | CI verification | GitHub Actions | All gates passed independently |
-| [date] | Deployed to production | System | Auto-deploy from main |
-| [date] | PROD post-deploy verification | [who] | Health + security checks passed on PROD |
-```
-
-```bash
-git add compliance/RTM.md compliance/approved-releases/ compliance/evidence/REQ-XXX/
-git rm compliance/pending-releases/RELEASE-TICKET-REQ-XXX.md 2>/dev/null
-git commit -m "compliance: [REQ-XXX] approved and deployed - PR #[number]"
-git push origin develop
-```
+Review and merge the close-out PR after its required checks are terminal green
+on its current head SHA. It is an administrative reconciliation PR, not a new
+production release. If the dispatch did not arrive, manually dispatch the
+Release Close-out workflow. Run `scripts/close-out-release.sh` locally only for
+documented recovery or historical catch-up; never create a normal direct
+close-out commit on a protected branch.
 
 ### Step 7: Close the GitHub Issue
 
@@ -207,17 +187,10 @@ gh issue close [ISSUE-NUMBER] --comment "Implemented in PR #[PR-NUMBER] (REQ-XXX
 
 This is the final traceability link: Issue → Requirement → PR → Deployment → Issue closed.
 
-### Step 8: Final Sync
-
-```bash
-git checkout main && git merge develop --no-edit && git push origin main
-git checkout develop
-```
-
 ## Rollback
 
 1. **Hosting dashboard:** Redeploy previous version
-2. **Git:** `git checkout main && git revert HEAD --no-edit && git push origin main`
+2. **Git:** create `hotfix/revert-REQ-XXX` from the release branch, revert the merge, and open a reviewed PR to the release branch. After terminal-green checks and merge, open the mandatory backmerge PR to integration.
 3. **Document:** Add rollback entry to release ticket audit trail
 4. **Correlate with incident (DevAudit-Installer#210 §10a):** If the rollback was triggered by a post-deploy smoke failure, the `post-deploy-prod.yml` workflow files an incident issue with the `incident` label. Reference this incident in the rollback commit message (`Fixes #N` or a comment on the issue) so the incident report captures the containment action. This ensures `incident-export.yml` exports the full incident timeline including the rollback.
 

package/sdlc/src/blueprints/implementing-an-sdlc-issue.raw.md

@@ -55,7 +55,7 @@ A worked end-to-end example for a zero-risk change (a typo, a dependency bump, a
 3. **Commit with a housekeeping type.** `docs:` / `chore:` / `ci:` / `build:` / `test:` / `revert:` are **exempt** from the `[REQ-XXX]` rule — e.g. `git commit -m "docs: fix typo in README"`. A `feat` / `fix` / `refactor` / `perf` subject without a `[REQ-XXX]` or `Ref: REQ-XXX` is **rejected** by commitlint and `validate-commits.sh` — if that fires, you picked the wrong type and the change isn't trivial.
 4. **Run the gates locally — not optional.** `npx tsc --noEmit`, lint, and the test suite must pass before you push. Trivial ≠ unverified.
 5. **Push and open a PR.** CI runs the same quality gates. `compliance-validation.yml` finds no `REQ-XXX` and **skips** artifact validation; no release ticket, no RTM row, no evidence pack is required.
-6. **Merge once CI is green** and a reviewer approves the PR. A housekeeping push **does** produce a portal release record — a bare-date release (`vYYYY.MM.DD`) — and it **does** go through the same UAT → production four-eyes flow as a tracked release. What the portal **auto-skips for housekeeping** is the four per-REQ completeness items (test-scope / test-plan / implementation-plan / test-execution-summary) — those have nothing to evaluate without a `REQ-XXX`. What's still required: all four CI gates green, a release ticket (`compliance/pending-releases/RELEASE-TICKET-<version>.md`), and a security summary (`compliance/security-summary-<version>.md`). **CI auto-generates both stubs as an operator-sign-off PR** (DevAudit-Installer v0.1.41+, scripts `generate-housekeeping-release-ticket.sh` + `generate-security-summary.sh`). Review the stubs + replace the `REPLACE — …` markers + merge → next CI run uploads them → matrix flips both items to ✓ → submit for UAT review on the portal. See [stage-3 housekeeping section](./3-compile-evidence.md) for the full walkthrough.
+6. **Merge only after terminal-green CI** and reviewer approval. A housekeeping push may create a bare-date portal row, but it is integration history, not a UAT/production approval release. It needs no release ticket, security-summary stub, per-REQ evidence pack, or portal sign-off. The next tracked REQ records absorbed work through bundled-change lineage. Use standalone housekeeping only through the explicit declaration and production-verification path in the release playbook.
 
 If at any step it stops feeling trivial — it changes behaviour, touches auth/payments/data, or an auditor would ask about it — switch to a tracked change and run `sdlc-implementer`. When unsure, it's not trivial.