docs: close-out — CHANGELOG 0.2.0, TEST-NEEDS, READINESS, ROADMAP, architecture, quickstarts

hyperpolymath · claude · hyperpolymath · commit 8ace8c1cc784 · 2026-06-11T23:14:00.000+01:00
- CHANGELOG: 0.2.0 entry (engine v2, design record, realignment, TruffleHog)
- TEST-NEEDS: 5 files / 35 tests with coverage map; real run commands
- READINESS (new): CRG C — engine tested; apps unwired/untested, marked X
- ROADMAP (new): NOW/NEXT/THEN/LATER in liquidity order, Jan-May 2027 wave,
  never-promise-stable-matching constraint
- architecture.md: honest two-layer state (legacy v0 wired, engine v2 not)
  + epistemic-typed server target
- quickstarts: real commands only, phantom recipes and wrong names removed

All claims execution-verified by the authoring agents (tests run, recipes
checked against Justfile/deno.json).

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -55,6 +55,25 @@ this project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0
 - ci: update SHA pins for codeql-action and trufflehog
 - ci: deploy missing standard workflows (10 added)
 
+## [0.2.0] - 2026-06-11
+
+### Added
+
+- feat(matching): land matching engine v2 at `packages/shared/src/matching/` — directional behaviour/tolerance scoring (weakest direction governs), feasibility/harmony split scores with banded verdicts, `auditGroup` (pairwise matrix, budget intersection, dispersion detection, shared-space minimum forecast), conceal lattice disclosure tiers T0/T1/T2 with `effectiveTier = min`, house-agreement + search-brief generators; 35 unit tests across 5 test files
+
+### Changed
+
+- chore: retain legacy v0 swipe+listings stack (`domain.js`/`encoding.js`, `apps/api`, `apps/web`, `apps/mobile`) in-tree, marked LEGACY, pending a quarantine/removal decision — apps are NOT yet wired to engine v2
+
+### Documentation
+
+- docs(design): add Squad Audit v1 design decision record (`docs/design/squad-audit-v1.adoc`) — product spec: harmony+feasibility audit for already-formed groups, upstream of SpareRoom, no listings, Jan–May 2027 London target wave
+- docs: realign README and docs to the Squad Audit posture (drop the "matching + listings in one flow" claim)
+
+### CI
+
+- ci: standardize TruffleHog secret scanning
+
 ## Pre-history
 
 Prior commits to this file's introduction are recorded in git history but not formally classified into Keep-a-Changelog sections. To backfill, run `git cliff -o CHANGELOG.md` locally using the canonical [`cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) — this is one-shot mechanical work.
diff --git a/QUICKSTART-DEV.adoc b/QUICKSTART-DEV.adoc
@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: MPL-2.0
 // Copyright (c) Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
-= Flat Mate Fix — Developer Quickstart
+= flat-mate — Developer Quickstart
 :toc: preamble
 
 Clone, build, test, contribute.
@@ -9,16 +9,16 @@ Clone, build, test, contribute.
 
 * Git 2.40+
 * just (command runner)
-* See `just doctor` output for language-specific requirements
+* Deno 2.x
+* See `just doctor` output for further requirements
 
 == Setup
 
 [source,bash]
 ----
-git clone https://github.com/hyperpolymath/flat-mate-fix
-cd flat-mate-fix
+git clone https://github.com/hyperpolymath/flat-mate
+cd flat-mate
 just doctor    # verify toolchain
-just heal      # auto-install missing tools
 ----
 
 == Development Workflow
@@ -27,8 +27,14 @@ just heal      # auto-install missing tools
 ----
 just tour      # understand the codebase
 just help-me   # see available commands
+deno task check     # type-check + lint (api + shared)
+deno task dev:api   # run the API locally
+deno task dev:web   # run the web app locally
 ----
 
+Run the matching-engine tests (engine v2, the only tested code) with
+`deno test packages/shared/src/matching/ --allow-read` (or `deno task test`).
+
 == Before Committing
 
 [source,bash]
diff --git a/QUICKSTART-MAINTAINER.adoc b/QUICKSTART-MAINTAINER.adoc
@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: MPL-2.0
 // Copyright (c) Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
-= Flat Mate Fix — Maintainer Quickstart
+= flat-mate — Maintainer Quickstart
 :toc: preamble
 
 Packaging, deployment, and release management.
@@ -17,25 +17,20 @@ This project uses GitHub Actions. Workflows are in `.github/workflows/`.
 
 Key workflows:
 
+* `ci.yml` — Deno fmt/check/test (`deno task fmt:check`, `check`, `test`)
 * `hypatia-scan.yml` — Neurosymbolic security scanning
-* `codeql.yml` — Code analysis
-* `scorecard.yml` — OpenSSF Scorecard
+* `scorecard-enforcer.yml` — OpenSSF Scorecard enforcement
+* `secret-scanner.yml` — Secret scanning
+* `governance.yml` — Governance checks
 * `mirror.yml` — GitLab/Bitbucket mirroring
 
 == Releasing
 
-1. Update version in project config
+1. Update version in `deno.json`
 2. Update CHANGELOG.md
 3. Tag: `git tag -s v<VERSION>`
 4. Push: `git push origin main --tags`
 
-== Container Build (if applicable)
-
-[source,bash]
-----
-podman build -f Containerfile -t flat-mate-fix:latest .
-----
-
 == Mirrors
 
 This repo is mirrored to GitLab and Bitbucket (hyperpolymath accounts)
diff --git a/READINESS.md b/READINESS.md
@@ -0,0 +1,65 @@
+<!--
+SPDX-License-Identifier: MPL-2.0
+Copyright (c) Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
+-->
+# flat-mate Component Readiness Assessment
+
+**Standard:** [Component Readiness Grades (CRG) v1.0](https://github.com/hyperpolymath/standards/tree/main/component-readiness-grades)
+**Assessed:** 2026-06-11
+**Assessor:** Jonathan D.A. Jewell
+
+**Current Grade:** C
+
+Grade carried over from the prior TEST-NEEDS.md claim (CRG C, 2026-04-04) and
+re-assessed 2026-06-11. The grade applies to the matching engine library only —
+see honest notes below.
+
+## Grade Reference
+
+| Grade | Name                  | Release Stage      | Meaning                                              |
+|-------|-----------------------|--------------------|------------------------------------------------------|
+| X     | Untested              | —                  | No testing performed. Status unknown.                |
+| F     | Harmful / Wasteful    | —                  | Reject, deprecate, or delegate.                      |
+| E     | Minimal / Salvageable | Pre-alpha          | Barely functional. Needs redesign or major work.     |
+| D     | Partial / Inconsistent| Alpha              | Works on some things but not systematically.         |
+| C     | Self-Validated        | Beta               | Dogfooded and reliable in home context.              |
+| B     | Broadly Validated     | Release Candidate  | Tested on 6+ diverse external targets.               |
+| A     | Field-Proven          | Stable             | Real-world feedback confirms value. No harm in wild. |
+
+## Component Assessment
+
+| Component                          | Grade | Release Stage | Evidence Summary                                                          | Last Assessed |
+|------------------------------------|-------|---------------|---------------------------------------------------------------------------|---------------|
+| `packages/shared/src/matching` (engine v2) | C | Beta    | 35 unit tests passing across 5 test files; deterministic seed fixtures incl. a deliberately-broken group; lint/fmt clean. | 2026-06-11 |
+| `apps/api`                         | X     | —             | No tests; not wired to engine v2; no auth.                                | 2026-06-11    |
+| `apps/web`                         | X     | —             | No tests; legacy v0 UI; not wired to engine v2.                           | 2026-06-11    |
+| `apps/mobile`                      | X     | —             | No tests; Expo app; not wired to engine v2.                               | 2026-06-11    |
+| `packages/shared/src/domain.js` (legacy v0) | X | —       | No tests; legacy swipe domain pending quarantine decision.                | 2026-06-11    |
+
+## Detailed Assessment
+
+### `packages/shared/src/matching` (engine v2)
+
+- **Grade:** C (Beta)
+- **Last assessed:** 2026-06-11
+- **Evidence:** 35 unit tests covering directional behaviour/tolerance scoring,
+  dealbreakers, group audit (pairwise matrix, budget intersection, dispersion,
+  shared-space minimum forecast), conceal tiers T0/T1/T2, agreement + brief
+  artifacts, and the missing-data policy. Run with
+  `deno test packages/shared/src/matching/ --allow-read`.
+- **Known limitations:** Library only — no app consumes it yet. Weights are
+  literature-seeded, not fitted (calibration flywheel is roadmap LATER). No
+  property-based tests.
+- **Promotion path:** Wire `apps/web` to `auditGroup`, real-cohort dogfooding
+  in the Jan–May 2027 wave, external validation targets.
+- **Demotion risk:** Low — pure functions, deterministic fixtures.
+
+## Notes
+
+- **Not production-ready.** The tested engine is a library; the apps are
+  unwired, untested, and have no authentication.
+- The legacy v0 swipe+listings stack remains in-tree (marked LEGACY) pending a
+  quarantine/removal decision — see ROADMAP.adoc NEXT.
+- Grades are per-component, not per-project; the headline C reflects the
+  engine library, the only dogfooded component.
+- See the [full CRG standard](https://github.com/hyperpolymath/standards/tree/main/component-readiness-grades) for complete definitions, evidence requirements, and transition criteria.
diff --git a/ROADMAP.adoc b/ROADMAP.adoc
@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: MPL-2.0
+// Copyright (c) Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
+= flat-mate Roadmap
+:author: Jonathan D.A. Jewell
+:revdate: 2026-06-11
+
+== Current State
+
+flat-mate v1 is **Squad Audit**: an already-formed student group gets a
+harmony + feasibility audit, an auto-drafted house agreement, and a search
+brief to take to the listings market. flat-mate sits upstream of SpareRoom and
+hosts no listings. Authoritative spec: `docs/design/squad-audit-v1.adoc`
+(where code and that document disagree, the document wins).
+
+Engine v2 is a tested library at `packages/shared/src/matching/` (10 modules,
+5 test files, 35 unit tests passing). The apps (`apps/api`, `apps/web`,
+`apps/mobile`) are **not yet wired to it**; the legacy v0 swipe+listings stack
+remains in-tree marked LEGACY pending a quarantine decision.
+
+**Target wave: Jan–May 2027** London second-year wave; one university to seed;
+legal posture resolved by December 2026.
+
+**What we never promise:** a "stable matching" — the roommate market is
+non-bipartite, stable matchings typically do not exist at scale
+(Chin & Michelen 2026), couples make existence NP-complete, and households of
+3+ are hedonic games whose core stability is Σ₂ᵖ-complete to decide. Product
+copy and mechanism design must respect this.
+
+The roadmap below is sequenced by **liquidity**: each stage needs more
+marketplace participation than the one before it.
+
+== NOW -- done 2026-06-11
+
+* [x] Squad Audit v1 design decision record (`docs/design/squad-audit-v1.adoc`)
+* [x] Matching engine v2 (`packages/shared/src/matching/`): directional
+  behaviour/tolerance scoring, feasibility/harmony split with banded verdicts,
+  `auditGroup` (pairwise matrix, budget intersection, dispersion detection,
+  shared-space minimum forecast), conceal lattice T0/T1/T2 with
+  `effectiveTier = min`, agreement + brief generators; 35 tests
+* [x] proven-epistemic reference core — the conceal/disclosure semantics
+  mirror the formally verified Idris2 core in proven-servers
+  (ADR: `proven-servers/docs/decisions/0002-add-proven-epistemic-disclosure-core.md`)
+
+== NEXT
+
+* [ ] Wire `apps/web` to `auditGroup` — audit-first UI (the apps currently do
+  not call engine v2 at all)
+* [ ] Legacy v0 quarantine decision — swipe+listings stack
+  (`domain.js`/`encoding.js`, `apps/api`, `apps/web`, `apps/mobile`):
+  quarantine, rewrite, or remove
+* [ ] Privacy notice + retention schedule + verified VerisimDB erasure and
+  subject-access-export story (Art. 25 obligations named in the design record)
+* [ ] ICO controller registration decision
+
+== THEN
+
+* [ ] Solo **top-up** discovery for groups with open slots — conceal tiers
+  (built in v1) plus a consent lifecycle (Proposal -> mutual accept -> Match),
+  restoring the mutuality property the v0 swipe domain had
+* [ ] **DA rounds** for solo-joins-household — the one theory-clean
+  centralized mechanism (genuinely bipartite); one vacancy per household per
+  round; couples via heuristic + blocking-pair verification, never a
+  guarantee path
+
+== LATER
+
+* [ ] **Calibration flywheel** — anonymised outcome telemetry (moved in;
+  1-month / 3-month satisfaction); literature-seeded weights become fitted;
+  one learning cycle per academic year
+* [ ] **Blocking-pair stability audit** over the discovery graph (advisory,
+  private, bounded to pair deviations)
+* [ ] Borough/commute **prefilters** in candidate generation when discovery
+  lands (London-only invariant stands; the audit flow is location-light)
+
+== Estate invariants (unchanged)
+
+VerisimDB sole persistence; London-first; Deno JS-first with the four-file TS
+carve-out in `apps/api` (see `.claude/CLAUDE.md`); MPL-2.0; mobile via Expo.
diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md
@@ -10,23 +10,36 @@ Copyright (c) Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
 
 | Category | Count | Notes |
 |----------|-------|-------|
-| Test files | 0 | Current state |
+| Test files | 5 | All in `packages/shared/src/matching/` (engine v2) |
+| Unit tests | 35 | All passing (verified 2026-06-11) |
+| App tests (api/web/mobile) | 0 | Apps are NOT wired to engine v2 and have no tests |
 
 ## What's Covered
 
-- [ ] No test files found
+Engine v2 library only (`packages/shared/src/matching/`):
+
+- [x] Directional behaviour/tolerance scoring — weakest direction governs; drinking as interaction not distance; budget overlap-coefficient (containment scores 1, no-overlap scores 0 + warns) (`compatibility.test.js`)
+- [x] Dealbreakers — symmetric firing, behaviour-not-tolerance targeting (v1 regression locked), structured attribution, uncheckable-rule warnings (`compatibility.test.js`)
+- [x] Group audit — pairwise matrix catches the shipped broken "Bloomsbury Three" fixture; budget by INTERSECTION never mean; weakest pair named; group validation (`group.test.js`)
+- [x] Dispersion detection — bimodal groups reported as SPLIT not averaged; shared-space forecast at the MINIMUM member standard, naming friction nodes (`group.test.js`)
+- [x] Conceal tiers — `effectiveTier` lattice meet (symmetric, idempotent, never above either grant); T0 band leaks verdict only; T1 relational leaks no names/attribution/habit values; T2 unredacted (`conceal.test.js`)
+- [x] Artifacts — universal agreement sections for every group, divergence sections from actual gaps, markdown rendering; brief budget intersection, HMO scaling, zero-stored-data guarantor/scam checklist (`artifacts.test.js`)
+- [x] Missing-data policy — nulls score neutral WITH a warning, never favourably; corrupt enum values throw; weight sums asserted = 1 (`compatibility.test.js`)
+- [x] Discovery boundary — structural group detection, solo-to-group scoring, not_viable filtering, tier redaction at the boundary (`discovery.test.js`)
 
 ## Still Missing (for CRG B+)
 
-- [ ] Add unit tests
-- [ ] Add integration tests
-- [ ] Zig FFI tests (if applicable)
-- [ ] CI/CD test automation
-- [ ] Property-based tests
-- [ ] Edge case coverage
+- [ ] `apps/api` integration tests (service is untested and not wired to engine v2)
+- [ ] `apps/web` tests — none exist
+- [ ] `apps/mobile` tests — none exist
+- [ ] Legacy `packages/shared/src/domain.js` (v0 swipe domain) tests — none; pending the v0 quarantine decision
+- [ ] Property-based tests (e.g. conceal-lattice monotonicity, scoring bounds)
+- [ ] CI fuzz placeholder
 
 ## Run Tests
 
 ```bash
-# Tests needed
+deno task test          # = deno test --allow-read packages/shared/src/matching/
+deno task check         # typecheck + lint (engine, legacy domain, API)
+deno task fmt:check     # format check (engine)
 ```
diff --git a/docs/architecture.md b/docs/architecture.md
