Objectuve Docs

Appearance

v4.3 — Keystone Architecture Sweep ​

Ran the objectuve-keystone audit verb across all 14 registry domains — 56 gates each, scored against the B/C/I/L/D/O rubric — and landed a triage-ready findings report per domain plus one consolidated index. Report-only: zero app-code changes. Its output became the input to v4.4 Keystone Findings Remediation, which closed all 18 items on the resulting fix-before-ship shortlist.

Summary ​

Before this milestone, the codebase's architectural health was assessed one domain at a time, ad hoc — the audit billing pilot (PR #1371) had found 3 confirmed structural defects in a single domain, which meant the other 13 domains almost certainly carried latent debt nobody had systematically looked for. This milestone ran that look: nine audit passes (Phases 1–9), one per domain or coupled domain cluster, each scoring every in-scope gate from A (boundary integrity) through H (operational integrity) with an explicit blocking/should-fix/clean verdict and a file:line citation. Phase 9 rolled all nine reports plus the earlier billing pilot into one consolidated triage index — .planning/milestones/v4.3-keystone-arch-sweep-AUDIT-FINDINGS.md — with an 18-item, milestone-wide fix-before-ship shortlist ranked by confidence and cost.

The sweep surfaced a consistent shape across domains: most defects were one of three recurring patterns — an unwrapped multi-write sequence missing its transaction (6 of 9 passes), the same business rule reimplemented in two or more places with no shared home (5 of 9 passes), and scripts/arch-domains.mjs's own registry entries under- or mis-claiming a domain's real surface (every single one of the 9 passes). Two findings stood out as worth fixing immediately: a live, currently-shipped EnqueueClear job-id bug (the cheapest, highest-confidence fix in the sweep), and a cross-cutting acts_as_paranoid documentation drift that no single domain phase could see on its own — the locked doc named 9 soft-deletable models; the real count was at least 30.

What shipped here is exactly what the milestone promised: nine domain reports plus the index, no code. The remediation — six atomicity fixes, two idempotency guards, a boundary-violation extraction, three deduplicated business rules, a registry-wide fix, and two documentation passes — shipped as its own milestone, v4.4 Keystone Findings Remediation, one day after this sweep's branch tip. That timing gap meant the sweep's own reports briefly described several findings as open that v4.4 had already fixed by the time anyone read them closely — the milestone-close pass that produced this page (2026-08-04, almost four weeks after the sweep itself) reconciled every report against v4.4's real outcome, closing that gap. See Key Decisions for why this milestone sat stranded on its own branch for that long in the first place.

Goal ​

Surface the load-bearing structural debt across the whole server side that a single-domain spot check can't see. Run the objectuve-keystone audit verb across all 14 registry domains, scored against the B/C/I/L/D/O rubric and the 56 numbered arch gates (A–H), and land a triage-ready findings report per domain plus one consolidated index. Report-only — this milestone produces zero code changes. Its output is the input to a later remediation milestone Roy scopes from the findings.

— .planning/milestones/v4.3-keystone-arch-sweep-ROADMAP.md

Scope — What Shipped ​

  • 9 domain audit reports under docs/architecture/audits/: goal-tracking.md, gamification.md, user-identity-critical-path.md, social-feedback.md, ai-coaching.md, ai-workforce.md, teams.md, content-moderation-admin-gdpr.md, platform.md — covering all 14 registry domains (billing folded in from its earlier pilot, PR #1371).
  • One consolidated triage index, .planning/milestones/v4.3-keystone-arch-sweep-AUDIT-FINDINGS.md, grouping every finding by gate category (A–H) and blocking status, with an 18-item milestone-wide fix-before-ship shortlist.
  • Zero rails_api/app/**, agent_runner/src/**, ionic_frontend/src/**, or admin_dashboard/src/** changes — every report's own "report-only invariant" line was verified true across all 9 phases.
  • At milestone close (this pass, 2026-08-04): each domain report's own "Resolution status" note reconciling its findings against v4.4 Keystone Findings Remediation's real shipped outcome, a corrected acts_as_paranoid model count in the consolidated index's §8, corrected stale-status rows in the index's §4, and one pre-existing doc-drift fix in docs/architecture/ddd/01-bounded-contexts.md (the GenerateAiCheckInPromptsJob Background Job table row still read "Not scheduled anywhere" after v4.4 scheduled it).

Phases ​

PhaseNameStatusPlansHighlights
1Goal TrackingShipped15 blocking findings incl. CheckInHabit's unwrapped transaction; established the report template every later phase reused
2GamificationShipped1Live write-on-read bug in StreakRepairOfferResolver; 2 published domain events with zero subscribers
3User Identity + Critical PathShipped1UpdateUser#call's .delete-not-.destroy GDPR-shaped bug (spun out same-day as OBJ-1276, fixed pre-v4.4); RecordPlay/AwardStimXp non-atomicity
4Social + FeedbackShipped1FinalizeCommunityChallenge's self-perpetuating duplicate-notification bug — worst blast-radius finding in the sweep (unconditional daily cron retry)
5AI CoachingShipped1A fully-built, fully-tested job (GenerateAiCheckInPromptsJob) never scheduled anywhere — 5 frontend surfaces permanently dark
6AI WorkforceShipped1First cross-service audit (rails_api + agent_runner + admin_dashboard); promotion_criteria actively disagreeing with the model's real validation
7TeamsShipped1teams/ had zero presence in the locked DDD docs — largest single doc-coverage gap in the sweep
8Cross-cutting governance (content moderation, admin, GDPR)Shipped1Two contradictory GDPR doc sections, one asserting a fictional GdprExport model
9Platform + consolidated indexShipped1Platform catch-all report + the 14-domain consolidated triage index; explicit g53/g36 PASS verdicts

Key Decisions ​

  • Report-only, enforced at review, not just declared. The milestone's delivery policy hard-gated every phase PR to findings-doc-only diffs — "a PR touching rails_api/app/**, agent_runner/src/**, or admin_dashboard/src/** is scope creep and bounces back." All 9 phases held that line; the actual fixes shipped one day later as a deliberately separate milestone (v4.4), keeping the audit's own findings independent of its remediator's judgment calls.
  • Cite, don't rediscover. Every phase was explicitly instructed to cite already-catalogued debt (the coupling-point tally, known doc drifts, the pending Critical Path ADR) rather than re-raise it as new — kept each report focused on genuinely new findings and made the consolidated index's roll-up tractable.
  • Branch promotion sat stranded for ~3.5 weeks. This milestone's own integration branch (gsd/v4.3-keystone-arch-sweep) never got its "merge to master" step — the same silent gap docs/development/branch-hygiene-poisoned-first-commit-postmortem.md's sibling gotcha describes: a milestone can finish every phase and simply sit, with nothing in the pipeline checking. It surfaced only when check-branch-promotion.mjs's daily nag flagged it (OBJ-2150 → OBJ-2160), by which point v4.4 (this sweep's own remediation) had already shipped its fixes and its docs pass against master directly — leaving this branch's copies of the same reports one day stale relative to its own fix milestone. Per the pr-scope-guard gotcha in CLAUDE.md — the same procedure OBJ-2003/OBJ-2012 established for v4.19 — the promotion opens from the branch's own ref (merge master in place, push back, merge-commit not squash) rather than a rebased copy; Task 1 of this close (Codi) already did the in-place merge (commit 0b05a7603), and this milestone-close docs pass committed onto that same branch. It didn't go through the normal Riley hand-off, though — Josh merged PR #2110 (merge commit ed4bdd1bb) directly to promote the branch to master.
  • Milestone-close reconciliation, not a re-audit. Rather than re-running objectuve-keystone against current master (which would re-derive everything v4.4 already fixed, mostly to produce the same "resolved" verdicts a citation check gets to faster), each report's own findings were checked directly against the current codebase — confirming the fix landed, citing the ticket/PR — and each report was annotated in place. The underlying gate-by-gate walkthroughs are left exactly as the original phases wrote them, preserving the point-in-time record; only the resolution status is new.

Requirements Coverage ​

This milestone has no numeric REQUIREMENTS.md in the usual sense — its "requirement" per phase was "produce a findings report covering all in-scope gates A–H with file:line + gate # + blocking/non-blocking classification," per the ROADMAP's own Definition of Done. All 9 are satisfied:

CategoryCountStatus
Domain findings reports (Phases 1–8)8All shipped, PR-reviewed, Roy-verified against source
Platform report + consolidated index (Phase 9)1Shipped; Roy flagged 2 content-accuracy nits (§8 undercount, §4 stale rows), both closed at this milestone-close pass

Full phase-by-phase detail: v4.3-keystone-arch-sweep-ROADMAP.md on GitHub.

Outcomes ​

  • Every one of the 14 registry domains now has a triage-ready, gate-by-gate architectural health report, each reconciled at this close to say plainly which of its findings are already fixed and which are still open — landed on master via PR #2110, merged by Josh directly rather than through the normal Riley hand-off.
  • The 18-item fix-before-ship shortlist this sweep produced is entirely closed — v4.4 Keystone Findings Remediation shipped every item, verified live against current source at this milestone's own close rather than taken on v4.4's summary alone.
  • docs/architecture/ddd/02-ubiquitous-language.md's soft-deletable-model list, 01-bounded-contexts.md's Teams section and GDPR sections, and scripts/arch-domains.mjs's registry globs for teams/gdpr/ai_coaching/gamification/goal_tracking are all confirmed current against the live codebase, not just "fixed at some point."
  • The check-branch-promotion.mjs guard that caught this branch stranded is now one report-only-milestone case study richer for the next time a finished-but-unmerged branch needs adjudicating.

Tech Debt ​

  • (§8, consolidated index) The acts_as_paranoid model list this milestone's own §8 finding covers has drifted again since v4.4 fixed it — 6 more models (AiUsageEvent, CheckinToken, HabitIntegrationMapping, IntegrationActivity, IntegrationConnection, IntegrationProvider) gained the annotation via later, unrelated integration-work milestones, bringing the live count to 40 against the doc's 34. Out of this milestone's scope to fix — flagged as a follow-up for whoever next touches 02-ubiquitous-language.md.
  • (carried forward from v4.4) Several should-fix findings across the 9 domain reports were never in v4.4's scope and remain open as of this close — each report's own "Resolution status" section names exactly which. None are blocking; Roy's triage call on sequencing a possible v4.4.5-shaped follow-up.
  • 0b05a7603 — chore(merge): merge master into gsd/v4.3-keystone-arch-sweep in place (OBJ-2160 Task 1)
  • 129adf068 — Phase 1 (Goal Tracking) findings report, PR #1384
  • 833be3842 — Phase 2 (Gamification) findings report, PR #1385
  • 4ef64a08c — Phase 3 (User Identity + Critical Path) findings report, PR #1390
  • 82d04b21d — Phase 4 (Social + Feedback) findings report, PR #1393
  • e5a4e52a0 — Phase 5 (AI Coaching) findings report, PR #1395
  • 5c3fdc9f4 — Phase 6 (AI Workforce) findings report, PR #1396
  • 392000c9e — Phase 7 (Teams) findings report, PR #1397
  • 257a8a460 — Phase 8 (Cross-cutting governance) findings report, PR #1401
  • 095c17220 — Phase 9 (Platform + consolidated index) findings report, PR #1402

Last updated: 2026-08-06

Loading…