Merge pull request #17 from szTheory/merge/docs-maintaining-into-main

Merge docs/maintaining-actions-runbook into main

Author: szTheory

.formatter.exs

@@ -1,5 +1,14 @@
 [
   import_deps: [:ecto, :phoenix],
-  inputs: ["*.{ex,exs}", "{config,lib,test}/**/*.{ex,exs}"],
+  inputs: [
+    "*.{ex,exs}",
+    "{config,lib}/**/*.{ex,exs}",
+    # Do not use a blanket `test/**` — `test/example/_build` and `deps` contain
+    # non-Elixir *.ex copies of install templates that break `mix format`.
+    "test/{sigra,support,mix,fixtures}/**/*.{ex,exs}",
+    "test/*.{ex,exs}",
+    "test/example/{lib,config,test,priv}/**/*.{ex,exs}",
+    "test/example/mix.exs"
+  ],
   export: [locals_without_parens: []]
 ]

.github/workflows/ci.yml

@@ -36,14 +36,15 @@ jobs:
       - name: Detect installer-related changes (PRs only)
         id: detect
         shell: bash
+        # Phase 51: include GA-adjacent lib surfaces (MFA/OAuth/account/passkeys) — see MAINTAINING.md §Installer golden CI contract.
         run: |
           set -euo pipefail
           if [ "${{ github.event_name }}" != "pull_request" ]; then
             echo "run=true" >> "$GITHUB_OUTPUT"
             exit 0
           fi
           git fetch origin "${{ github.base_ref }}" --depth=1
-          if git diff --name-only "origin/${{ github.base_ref }}...HEAD" | grep -qE '^priv/templates/sigra\.install/|^lib/sigra/install/'; then
+          if git diff --name-only "origin/${{ github.base_ref }}...HEAD" | grep -qE '^priv/templates/sigra\.install/|^lib/sigra/install/|^lib/sigra/mfa(\.ex|/)|^lib/sigra/oauth(\.ex|/)|^lib/sigra/account(\.ex|/)|^lib/sigra/passkeys(\.ex|/)'; then
             echo "run=true" >> "$GITHUB_OUTPUT"
           else
             echo "run=false" >> "$GITHUB_OUTPUT"
@@ -52,6 +53,72 @@ jobs:
         if: steps.detect.outputs.run == 'true'
         run: bash scripts/ci/installer-milestone-audit.sh
 
+  install_golden_contract:
+    name: Install golden + idempotency contract (subprocess harness)
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:15
+        env:
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: sigra_test
+        ports: ['5432:5432']
+        options: >-
+          --health-cmd pg_isready --health-interval 10s
+          --health-timeout 5s --health-retries 5
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          fetch-depth: 0
+      - name: Detect installer-related changes (PRs only)
+        id: detect
+        shell: bash
+        # Phase 51: include GA-adjacent lib surfaces (MFA/OAuth/account/passkeys) — see MAINTAINING.md §Installer golden CI contract.
+        run: |
+          set -euo pipefail
+          if [ "${{ github.event_name }}" != "pull_request" ]; then
+            echo "run=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          git fetch origin "${{ github.base_ref }}" --depth=1
+          if git diff --name-only "origin/${{ github.base_ref }}...HEAD" | grep -qE '^priv/templates/sigra\.install/|^lib/sigra/install/|^lib/sigra/mfa(\.ex|/)|^lib/sigra/oauth(\.ex|/)|^lib/sigra/account(\.ex|/)|^lib/sigra/passkeys(\.ex|/)'; then
+            echo "run=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "run=false" >> "$GITHUB_OUTPUT"
+          fi
+      - uses: erlef/setup-beam@fc68ffb90438ef2936bbb3251622353b3dcb2f93  # v1.24.0
+        if: steps.detect.outputs.run == 'true'
+        with:
+          version-file: .tool-versions
+          version-type: strict
+      - name: Cache library deps
+        if: steps.detect.outputs.run == 'true'
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830  # v4.3.0
+        with:
+          path: |
+            deps
+            _build
+          key: ${{ runner.os }}-library-${{ hashFiles('mix.lock') }}
+      - name: Install Hex + Rebar
+        if: steps.detect.outputs.run == 'true'
+        run: |
+          mix local.hex --force
+          mix local.rebar --force
+      - name: Install phx_new archive
+        if: steps.detect.outputs.run == 'true'
+        run: mix archive.install --force hex phx_new
+      - name: Fetch library deps
+        if: steps.detect.outputs.run == 'true'
+        run: mix deps.get
+      - name: Run install golden + idempotency tests
+        if: steps.detect.outputs.run == 'true'
+        env:
+          MIX_ENV: test
+          PGUSER: postgres
+          PGPASSWORD: postgres
+          PGHOST: localhost
+        run: mix test test/sigra/install/golden_diff_test.exs test/sigra/install/idempotency_test.exs
+
   library_tests:
     name: Library tests
     runs-on: ubuntu-latest

.planning/MILESTONES.md

@@ -159,3 +159,70 @@
 - [v1.3 Milestone Audit](milestones/v1.3-MILESTONE-AUDIT.md)
 
 ---
+
+## v1.4 GA readiness & audit trail completeness (Shipped: 2026-04-22)
+
+**Scope:** 12 phases (41–52), 38 plans.
+
+**What shipped:** **SEED-001** closure with **TOTP-gated backup-code rotation** (`Sigra.MFA.regenerate_backup_codes/4`), example and install parity, and regression tests; a canonical **GA matrix** (`.planning/v1.4-GA-UAT.md`) with **Executed / Waived / Blocked** rows, dated evidence under `.planning/uat-evidence/v1.4/`, and machine substitutes where explicitly waived. **SEED-002** continuation: **AUD-04** inventory plus prioritized **`log_safe/3` → `Ecto.Multi`** conversions across **Auth**, **MFA**, **Account/API**, and **OAuth/ops** batches with **audit-aware** tests; formal **43/44/45 `*-VERIFICATION.md`** merge gates (**47–49**) including **`mix ci.audit_45`** and refreshed **Phase 9 C-1** matrices. **Phase 50** documented **Nyquist policy for 41–44** in **`MAINTAINING.md`**, **`mix ci.install_golden`**, and **`install_golden_contract`**. **Phase 51** widened CI path detection for installer-golden jobs and locked **GA waiver ↔ install-golden attestation** cross-links in contract tests. **Phase 52** aligned ROADMAP presentation (implementation vs verification phases) and added milestone-honesty contract coverage.
+
+### Key accomplishments
+
+1. **Phase 41 — GA-01 product fact** — Library backup-code rotation with optional audit on the same `Ecto.Multi`, generator/example wiring, and automated rotation regression.
+2. **Phases 42 + 46 — defensible GA posture** — Matrix scaffold plus gap closure so **GA-02..GA-05** are not “silent Pending” at close.
+3. **Phases 43–45 + 47–49 — audit atomicity + honest verification** — Inventory-driven batches, merge-gated verification docs, and **AUD-04..AUD-08** traceability reconciled with implementation reality.
+4. **Phase 50 — Nyquist + expensive CI as policy** — Explicit batch posture for **41–44** and documented **install golden** / CI truth on `main`.
+5. **Phase 51 — CI merge coupling** — Path filters and structural tests so **`install_golden_contract`** stays coupled to relevant PRs and waived GA rows point at attestations.
+6. **Phase 52 — planning honesty** — ROADMAP reader clarity for **44/45 vs 48/49** and contract tests guarding milestone narrative drift.
+
+### Stats
+
+- **Requirements:** 10/10 GA + AUD IDs in archived `milestones/v1.4-REQUIREMENTS.md` (mix of **Complete** and **Waived** with documented substitutes).
+- **Milestone audit:** early **`gaps_found`** snapshot preserved under `milestones/v1.4-MILESTONE-AUDIT.md` with an archive note; gaps were closed by phases **46–52** before ship.
+- **Pre-close `audit-open`:** all artifact types clear (2026-04-22).
+- **Timeline:** 2026-04-20 → 2026-04-22 (execution on disk + verification closure).
+
+### Tech debt carried forward
+
+- **Nyquist `nyquist_compliant: false` on 41–44** remains intentional unless policy elevates it (`MAINTAINING.md`).
+- **Explicitly deferred `log_safe/3` rows** under **AUD-08** must stay listed with reopen triggers (see post-close **C-1** matrices).
+- **`gsd-sdk query milestone.complete`** did not complete archival in this environment; maintainers used the same manual archive path as v1.3.
+
+**Archive:**
+
+- [v1.4 Roadmap](milestones/v1.4-ROADMAP.md)
+- [v1.4 Requirements](milestones/v1.4-REQUIREMENTS.md)
+- [v1.4 Milestone Audit](milestones/v1.4-MILESTONE-AUDIT.md)
+
+---
+
+## v1.5 Public release narrative & community readiness (Shipped: 2026-04-22)
+
+**Scope:** 4 phases (53–56), 5 plans.
+
+**What shipped:** **PUB-01** — `mix.exs` / Hex description and `package[:links]` aligned with shipped **v1.0–v1.4** capabilities and optional deps. **PUB-02** — `CHANGELOG.md` milestone glossary, roadmap traceability for **v1.2–v1.4**, ordered **0.1.0** sections, and Keep a Changelog compare links. **DOC-01** / **DOC-02** — README **Production readiness & GA evidence** block, new **`SECURITY.md`**, **`docs/ga-evidence.md`**, ExDoc extras, and clean `mix docs --warnings-as-errors`. **MAINT-01** — **First public launch** checklist in **`MAINTAINING.md`** with owners, tag-scoped `.planning` evidence URLs, and explicitly optional comms rows where **v1.4** waivers apply.
+
+### Key accomplishments
+
+1. **Phase 53 — honest Hex surface** — Core vs optional integrations reflected in public package metadata without dead claims.
+2. **Phase 54 — changelog as narrative spine** — Planning milestones and SemVer releases are distinguishable; traceability blocks link roadmap archives and compare URLs.
+3. **Phase 55 — OSS entry to GA evidence** — README and ExDoc give a short path to **Executed / Waived** language and **v1.4** artifacts.
+4. **Phase 56 — shippable announcement runbook** — Maintainer checklist orders **tag → Hex → announce → monitor** with pointers to **install golden** and **v1.4-GA-UAT** evidence.
+
+### Stats
+
+- **Requirements:** 5/5 Complete in archived [`milestones/v1.5-REQUIREMENTS.md`](milestones/v1.5-REQUIREMENTS.md).
+- **Milestone audit:** none filed for v1.5; closure used requirements traceability + phase summaries.
+- **Pre-close `audit-open`:** all artifact types clear (2026-04-22).
+- **Timeline:** 2026-04-22 (single-day milestone execution on disk).
+
+### Tech debt carried forward
+
+- **`gsd-sdk query milestone.complete`** returned `version required for phases archive`; archival followed the same manual path as **v1.3** / **v1.4**.
+
+**Archive:**
+
+- [v1.5 Roadmap](milestones/v1.5-ROADMAP.md)
+- [v1.5 Requirements](milestones/v1.5-REQUIREMENTS.md)
+
+---