bert.hausmans/crewli
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

WS-6 v1.3-delta — Closure docs-PR #12

Merged
bert.hausmans merged 4 commits from docs/ws-6-v1.3-delta-closure into main 2026-05-08 10:30:20 +02:00
Conversation 0 Commits 4 Files Changed 3 +284 -17
bert.hausmans commented 2026-05-08 10:30:06 +02:00
Owner
Copy Link

WS-6 v1.3-delta — Closure docs-PR

Closes the docs side of WS-6 v1.3-delta. With this merged, all WS-6 v1.3 work is documented as complete, all chat-identified no-compromises gaps are closed (either by direct fix or actionable BACKLOG anchoring), and the only remaining task is the GlitchTip alert rule configuration in the web UI (operational, separate from code lifecycle).

This is a docs-only PR. No code changes, no migrations, no test changes.

Refs

What this PR delivers

1. Runbook addition: dev-docs/runbooks/observability-triage.md §7 Form-builder binding failures (commit 7ba01a6)

New top-level section, placed after §6 Audit trail to preserve existing cross-references. Five subsections:

  • §7.1 — failure_response_code triage matrix (4 tokens × triage path)
  • §7.2 — form_schema.has_public_token tag distinguishing customer-facing vs organizer-driven failures
  • §7.3 — Retry vs dismiss decision matrix with php artisan form-failures:retry examples + DismissalReasonType enum cases
  • §7.4 — Severe-failure escalation (>10 events/hour on single schema = P1, indicates publish-guard gap)
  • §7.5 — Cross-references to RFC, ARCH-BINDINGS, and the erasure runbook

Companion to the operational GlitchTip alert rule (configured separately in the GlitchTip web UI on monitoring.hausdesign.nl).

2. RFC-WS-6 v1.3.1 — fully implemented marker (commit 5ac6b41)

  • §1 Status gains an "Implementation status: v1.3.1 fully implemented in main as of 2026-05-08 (D1: PR #10 c6f4d1b, D2: PR #11 23a5696)" line
  • §10 Document history gains a v1.3-delta closure entry summarising what each PR delivered + what remains as separate operational task

No spec changes — purely lifecycle marker update.

3. BACKLOG.md updates — initial closure pass (commit ce552ec)

  • Appended WS-6 v1.3-delta — closure (mei 2026) bullet under ## Opgeloste items (mei 2026), following the existing single-bullet/strikethrough/✅ convention
  • Surgical correction to FORM-05 Stub-status paragraph: pre-D2 description claimed TriggerPersonIdentityMatchOnFormSubmit writes the initial 'pending'; post-D2 that's ApplyBindingsOnFormSubmit::handle's job per RFC §Q1 v1.3 add 1. The underlying ticket (detectMatchesByValues extension) stays open.

No pre-existing BACKLOG entries resolved. D1 + D2 implemented RFC §Q3 v1.3 changes that pre-existing tickets didn't anticipate.

4. BACKLOG.md updates — no-compromises gap closure (commit c5682f1)

Chat review of commit 3 surfaced three concessies that were too softly handled. This commit closes them:

  • FORM-05 'Resterend werk' sub-paragraph: surgical replacement of TWO obsolete references (not just one): the TriggerPersonIdentityMatchOnFormSubmit::resolveStatus method (D2 inlined the status derivation into handle()) AND the "altijd 'pending'" framing (failsafe-pad behaviour from v1.0/v1.2; failsafe-pad is gone post-D2). Updated to describe the actual post-D2 gap: self-registered public submitters whose exact-email matcher comes back empty get 'none' because PersonIdentityService skips fuzzy-name fallback for registration_source='self'. Includes concrete PHP fenced blocks showing the new detectMatchesByValues() method on PersonIdentityService and the new match-arm in handle()'s status-derivation. Cross-reference at the close to FRONTEND-ECHO-IDENTITY-MATCH-SUBSCRIPTION. Ticket stays open (description correction, not resolution).

  • FRONTEND-ECHO-IDENTITY-MATCH-SUBSCRIPTION (NEW): tracks the frontend follow-up where the portal IdentityMatchBanner subscribes to the submission.{id} private channel via Laravel Echo for live banner updates. Previously documented in PR #11 body and RFC §Q1 v1.3 add 2 commentary but without an actionable BACKLOG ticket. Trigger condition: bring forward when (a) TanStack refetch-on-focus UX produces customer complaints, OR (b) the next form-builder frontend sprint lands so all Echo-wiring lands together. Estimate: 0.5–1 day.

  • HARD-DEADLINE-QUERY-TIMEOUT (NEW): tracks the upgrade from soft post-call microtime deadline to a hard deadline that can interrupt hanging MySQL queries. The current FormBindingApplicator::withDeadline() works for "applicator runs slow over many bindings" (the long tail) but cannot interrupt during a hanging query or lock-for-update wait. Three potential implementation paths sketched: MySQL connection-level timeouts, per-query MAX_EXECUTION_TIME hints (MySQL 5.7+ only), or pcntl_alarm + signal handler in queue-worker context. Trigger condition: first production incident where soft deadline proves insufficient, OR enterprise SLO requirements demanding stricter response-time guarantees. Estimate: 2–3 days.

BACKLOG entries that stay open (intentional follow-up)

Entry Status Trigger / why open
TECH-CHANNEL-AUTH-ORG-ADMIN Open Extend submission.{id} channel auth to organisation admins after Spatie Permission helper-pattern audit
FRONTEND-ECHO-IDENTITY-MATCH-SUBSCRIPTION (new) Open Frontend portal IdentityMatchBanner Echo subscription; pairs with TECH-CHANNEL-AUTH-ORG-ADMIN
HARD-DEADLINE-QUERY-TIMEOUT (new) Open Hard query-level deadline; trigger condition (production incident OR enterprise SLO) not fired
PARTIAL-BINDING-SUCCESS Open Granular per-binding success-state — trigger condition (first enterprise customer complaint) not fired
FORM-SCHEMA-DRIFT-DETECTION Open Migration-listener for binding drift — trigger condition (first prod incident) not fired
FORM-05 Open detectMatchesByValues extension for public submissions — Stub-status AND Resterend werk paragraphs corrected in this PR; underlying work still open
FORM-BINDING-SNAPSHOT-MULTI Open Out of scope, untouched
FORM-BUILDER-LIBRARY-AUDIT-LOG Open Out of scope, untouched

Operational follow-up (NOT in this PR)

  • GlitchTip alert rule for apply_status=failed AND form_schema.has_public_token=true — configured manually in the GlitchTip web UI on monitoring.hausdesign.nl. The runbook procedure that the alert will trigger is documented in §7 of this PR.

Audit findings (Phase A — initial pass)

  • Section placement chosen as new ## §7 after §6 Audit trail (rather than mid-document) to avoid renumbering existing sections and preserve internal cross-refs.
  • BACKLOG ## Opgeloste items (mei 2026) convention followed: single-bullet, strikethrough, ✅ format.
  • FORM-05 audit initially identified only resolveStatus as obsolete; second audit (commit 4) caught the additional "altijd pending" framing as also obsolete. Both corrected in commit 4.

Audit findings (Phase A — review pass)

Chat review caught two BACKLOG gaps in commit 3 that were too softly handled:

  • Frontend Echo subscription was documented in PR #11 body and RFC commentary but had no actionable BACKLOG ticket — closed in commit 4 as FRONTEND-ECHO-IDENTITY-MATCH-SUBSCRIPTION.
  • Soft-deadline limitation in FormBindingApplicator::withDeadline() was documented as a code comment but had no actionable BACKLOG ticket — closed in commit 4 as HARD-DEADLINE-QUERY-TIMEOUT.

Both new entries follow the established BACKLOG convention: explicit trigger conditions (not "ooit eens een keer"), three potential implementation paths sketched where applicable, estimates included.

Commits

  1. 7ba01a6 — docs(runbooks): add form-builder binding failures section
  2. 5ac6b41 — docs(rfc-ws-6): mark v1.3.1 as fully implemented
  3. ce552ec — docs(backlog): WS-6 v1.3-delta closure entry + FORM-05 stub-status touch-up
  4. c5682f1 — docs(backlog): close no-compromises gaps from WS-6 v1.3-delta review

Review hints

  • The four commits are sequenced by intent, not by file. Commits 1–3 are the initial closure pass (runbook + RFC + BACKLOG). Commit 4 closes gaps surfaced during chat review of commits 1–3 — strict no-compromises hygiene applied retroactively to the same PR rather than punted to a separate follow-up.
  • One resolveStatus reference remains in BACKLOG but it's deliberate — the new FORM-05 text mentions it explanatorily ("D2 inlinete de status-derivation in handle() zelf — er is geen aparte resolveStatus methode meer") to anchor future readers in the post-D2 reality. Not a stale reference.
  • No code or test changes. This is pure markdown. The repo's binary state (1621 backend tests passing, 0 Larastan errors) is unchanged.
  • WS-6 v1.3-delta closes with this PR, except for the GlitchTip alert rule (operational, configured separately in the GlitchTip web UI). Three new BACKLOG entries (FRONTEND-ECHO-IDENTITY-MATCH-SUBSCRIPTION, HARD-DEADLINE-QUERY-TIMEOUT, plus pre-existing TECH-CHANNEL-AUTH-ORG-ADMIN) carry the small remaining surface area.

🤖 Co-Authored-By: Claude Opus 4.7

## WS-6 v1.3-delta — Closure docs-PR Closes the docs side of WS-6 v1.3-delta. With this merged, all WS-6 v1.3 work is documented as complete, all chat-identified no-compromises gaps are closed (either by direct fix or actionable BACKLOG anchoring), and the only remaining task is the GlitchTip alert rule configuration in the web UI (operational, separate from code lifecycle). **This is a docs-only PR.** No code changes, no migrations, no test changes. ### Refs - [`dev-docs/RFC-WS-6.md`](dev-docs/RFC-WS-6.md) v1.3.1 — implemented as of 2026-05-08 (D1: PR #10 `c6f4d1b`, D2: PR #11 `23a5696`) - [`dev-docs/ARCH-BINDINGS.md`](dev-docs/ARCH-BINDINGS.md) v1.2 — context only, no edits --- ### What this PR delivers **1. Runbook addition: `dev-docs/runbooks/observability-triage.md` §7 Form-builder binding failures** (commit `7ba01a6`) New top-level section, placed after §6 Audit trail to preserve existing cross-references. Five subsections: - **§7.1** — `failure_response_code` triage matrix (4 tokens × triage path) - **§7.2** — `form_schema.has_public_token` tag distinguishing customer-facing vs organizer-driven failures - **§7.3** — Retry vs dismiss decision matrix with `php artisan form-failures:retry` examples + `DismissalReasonType` enum cases - **§7.4** — Severe-failure escalation (>10 events/hour on single schema = P1, indicates publish-guard gap) - **§7.5** — Cross-references to RFC, ARCH-BINDINGS, and the erasure runbook Companion to the operational GlitchTip alert rule (configured separately in the GlitchTip web UI on `monitoring.hausdesign.nl`). **2. RFC-WS-6 v1.3.1 — fully implemented marker** (commit `5ac6b41`) - §1 Status gains an "Implementation status: v1.3.1 fully implemented in main as of 2026-05-08 (D1: PR #10 `c6f4d1b`, D2: PR #11 `23a5696`)" line - §10 Document history gains a v1.3-delta closure entry summarising what each PR delivered + what remains as separate operational task No spec changes — purely lifecycle marker update. **3. BACKLOG.md updates — initial closure pass** (commit `ce552ec`) - Appended `WS-6 v1.3-delta — closure (mei 2026)` bullet under `## Opgeloste items (mei 2026)`, following the existing single-bullet/strikethrough/✅ convention - Surgical correction to FORM-05 Stub-status paragraph: pre-D2 description claimed `TriggerPersonIdentityMatchOnFormSubmit` writes the initial `'pending'`; post-D2 that's `ApplyBindingsOnFormSubmit::handle`'s job per RFC §Q1 v1.3 add 1. The underlying ticket (`detectMatchesByValues` extension) stays open. **No pre-existing BACKLOG entries resolved.** D1 + D2 implemented RFC §Q3 v1.3 changes that pre-existing tickets didn't anticipate. **4. BACKLOG.md updates — no-compromises gap closure** (commit `c5682f1`) Chat review of commit 3 surfaced three concessies that were too softly handled. This commit closes them: - **FORM-05 'Resterend werk' sub-paragraph**: surgical replacement of TWO obsolete references (not just one): the `TriggerPersonIdentityMatchOnFormSubmit::resolveStatus` method (D2 inlined the status derivation into `handle()`) AND the "altijd 'pending'" framing (failsafe-pad behaviour from v1.0/v1.2; failsafe-pad is gone post-D2). Updated to describe the actual post-D2 gap: self-registered public submitters whose exact-email matcher comes back empty get `'none'` because `PersonIdentityService` skips fuzzy-name fallback for `registration_source='self'`. Includes concrete PHP fenced blocks showing the new `detectMatchesByValues()` method on `PersonIdentityService` and the new match-arm in `handle()`'s status-derivation. Cross-reference at the close to `FRONTEND-ECHO-IDENTITY-MATCH-SUBSCRIPTION`. Ticket stays open (description correction, not resolution). - **`FRONTEND-ECHO-IDENTITY-MATCH-SUBSCRIPTION`** (NEW): tracks the frontend follow-up where the portal IdentityMatchBanner subscribes to the `submission.{id}` private channel via Laravel Echo for live banner updates. Previously documented in PR #11 body and RFC §Q1 v1.3 add 2 commentary but without an actionable BACKLOG ticket. Trigger condition: bring forward when (a) TanStack refetch-on-focus UX produces customer complaints, OR (b) the next form-builder frontend sprint lands so all Echo-wiring lands together. Estimate: 0.5–1 day. - **`HARD-DEADLINE-QUERY-TIMEOUT`** (NEW): tracks the upgrade from soft post-call microtime deadline to a hard deadline that can interrupt hanging MySQL queries. The current `FormBindingApplicator::withDeadline()` works for "applicator runs slow over many bindings" (the long tail) but cannot interrupt during a hanging query or lock-for-update wait. Three potential implementation paths sketched: MySQL connection-level timeouts, per-query `MAX_EXECUTION_TIME` hints (MySQL 5.7+ only), or `pcntl_alarm` + signal handler in queue-worker context. Trigger condition: first production incident where soft deadline proves insufficient, OR enterprise SLO requirements demanding stricter response-time guarantees. Estimate: 2–3 days. --- ### BACKLOG entries that stay open (intentional follow-up) | Entry | Status | Trigger / why open | |---|---|---| | `TECH-CHANNEL-AUTH-ORG-ADMIN` | Open | Extend `submission.{id}` channel auth to organisation admins after Spatie Permission helper-pattern audit | | `FRONTEND-ECHO-IDENTITY-MATCH-SUBSCRIPTION` (new) | Open | Frontend portal IdentityMatchBanner Echo subscription; pairs with TECH-CHANNEL-AUTH-ORG-ADMIN | | `HARD-DEADLINE-QUERY-TIMEOUT` (new) | Open | Hard query-level deadline; trigger condition (production incident OR enterprise SLO) not fired | | `PARTIAL-BINDING-SUCCESS` | Open | Granular per-binding success-state — trigger condition (first enterprise customer complaint) not fired | | `FORM-SCHEMA-DRIFT-DETECTION` | Open | Migration-listener for binding drift — trigger condition (first prod incident) not fired | | `FORM-05` | Open | `detectMatchesByValues` extension for public submissions — Stub-status AND Resterend werk paragraphs corrected in this PR; underlying work still open | | `FORM-BINDING-SNAPSHOT-MULTI` | Open | Out of scope, untouched | | `FORM-BUILDER-LIBRARY-AUDIT-LOG` | Open | Out of scope, untouched | --- ### Operational follow-up (NOT in this PR) - **GlitchTip alert rule** for `apply_status=failed AND form_schema.has_public_token=true` — configured manually in the GlitchTip web UI on `monitoring.hausdesign.nl`. The runbook procedure that the alert will trigger is documented in §7 of this PR. --- ### Audit findings (Phase A — initial pass) - Section placement chosen as new `## §7` after `§6 Audit trail` (rather than mid-document) to avoid renumbering existing sections and preserve internal cross-refs. - BACKLOG `## Opgeloste items (mei 2026)` convention followed: single-bullet, strikethrough, ✅ format. - FORM-05 audit initially identified only `resolveStatus` as obsolete; second audit (commit 4) caught the additional "altijd pending" framing as also obsolete. Both corrected in commit 4. ### Audit findings (Phase A — review pass) Chat review caught two BACKLOG gaps in commit 3 that were too softly handled: - Frontend Echo subscription was documented in PR #11 body and RFC commentary but had no actionable BACKLOG ticket — closed in commit 4 as `FRONTEND-ECHO-IDENTITY-MATCH-SUBSCRIPTION`. - Soft-deadline limitation in `FormBindingApplicator::withDeadline()` was documented as a code comment but had no actionable BACKLOG ticket — closed in commit 4 as `HARD-DEADLINE-QUERY-TIMEOUT`. Both new entries follow the established BACKLOG convention: explicit trigger conditions (not "ooit eens een keer"), three potential implementation paths sketched where applicable, estimates included. --- ### Commits 1. `7ba01a6` — docs(runbooks): add form-builder binding failures section 2. `5ac6b41` — docs(rfc-ws-6): mark v1.3.1 as fully implemented 3. `ce552ec` — docs(backlog): WS-6 v1.3-delta closure entry + FORM-05 stub-status touch-up 4. `c5682f1` — docs(backlog): close no-compromises gaps from WS-6 v1.3-delta review --- ### Review hints - **The four commits are sequenced by intent**, not by file. Commits 1–3 are the initial closure pass (runbook + RFC + BACKLOG). Commit 4 closes gaps surfaced during chat review of commits 1–3 — strict no-compromises hygiene applied retroactively to the same PR rather than punted to a separate follow-up. - **One `resolveStatus` reference remains in BACKLOG** but it's deliberate — the new FORM-05 text mentions it explanatorily ("D2 inlinete de status-derivation in handle() zelf — er is geen aparte resolveStatus methode meer") to anchor future readers in the post-D2 reality. Not a stale reference. - **No code or test changes.** This is pure markdown. The repo's binary state (1621 backend tests passing, 0 Larastan errors) is unchanged. - **WS-6 v1.3-delta closes with this PR**, except for the GlitchTip alert rule (operational, configured separately in the GlitchTip web UI). Three new BACKLOG entries (`FRONTEND-ECHO-IDENTITY-MATCH-SUBSCRIPTION`, `HARD-DEADLINE-QUERY-TIMEOUT`, plus pre-existing `TECH-CHANNEL-AUTH-ORG-ADMIN`) carry the small remaining surface area. 🤖 Co-Authored-By: Claude Opus 4.7
bert.hausmans added 4 commits 2026-05-08 10:30:06 +02:00
docs(runbooks): add form-builder binding failures section 7ba01a6dfa 
Per RFC-WS-6 §Q3 v1.3 + ARCH-BINDINGS §11.

Nieuwe runbook-sectie §7 (na §6 Audit trail) die de triage-flow
documenteert wanneer GlitchTip een FormBindingApplicatorException
event opbrengt:

- §7.1 failure_response_code classificatie (schema_config_error /
  temporary_error / data_integrity_error / unknown_error) drijft het
  initiële triage-pad
- §7.2 form_schema.has_public_token tag onderscheidt klant-zichtbare
  failures (alert-waardig) van organizer-driven failures (admin-UI only)
- §7.3 retry/dismiss decision-matrix met form-failures:retry artisan
  command + DismissalReasonType enum cases
- §7.4 severe-failure escalatie criteria (>10/uur op één schema = P1)
- §7.5 cross-references naar RFC, ARCH-BINDINGS, en erasure-runbook

Companion van de operationele GlitchTip alert-rule (apart geconfigureerd
in de GlitchTip web UI op monitoring.hausdesign.nl).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
docs(rfc-ws-6): mark v1.3.1 as fully implemented 5ac6b4168d 
§1 Status: add Implementation status line citing D1 (PR #10 c6f4d1b)
and D2 (PR #11 23a5696), both 2026-05-08.

§10 Document history: append v1.3-delta closure entry summarising what
D1 and D2 each delivered + what remains as separate operational task
(GlitchTip alert rule configuration in the web UI) and frontend
follow-up (Echo subscription).

No spec changes — purely lifecycle marker update.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
docs(backlog): WS-6 v1.3-delta closure entry + FORM-05 stub-status touch-up ce552ec7be 
Append WS-6-V1.3-DELTA closure bullet under "Opgeloste items (mei 2026)"
summarising D1 (PR #10 c6f4d1b) + D2 (PR #11 23a5696) deliverables and
open follow-ups.

Surgical correction to FORM-05 Stub-status paragraph: pre-D2 description
claimed TriggerPersonIdentityMatchOnFormSubmit writes initial 'pending';
post-D2 that's ApplyBindingsOnFormSubmit's job per RFC §Q1 v1.3 add 1.
The underlying ticket (detectMatchesByValues extension) stays open.

No other BACKLOG entries resolved — D1+D2 implemented RFC §Q3 v1.3
changes that pre-existing tickets didn't anticipate.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
docs(backlog): close no-compromises gaps from WS-6 v1.3-delta review c5682f181f 
Three edits closing concessies surfaced in chat review of the closure
docs-PR:

1. FORM-05 'Resterend werk' sub-paragraph: surgical replacement of
   resolveStatus references (method removed in D2, PR #11 23a5696).
   Updated to describe post-D2 reality: gate + invariant +
   handle()-internal status derivation. Ticket stays open (the
   detectMatchesByValues extension is unbuilt).

2. FRONTEND-ECHO-IDENTITY-MATCH-SUBSCRIPTION (NEW): tracks the frontend
   follow-up where the portal IdentityMatchBanner subscribes to the
   submission.{id} channel for live banner updates. Previously
   documented in PR #11 body and RFC §Q1 v1.3 add 2 commentary but
   without an actionable BACKLOG ticket.

3. HARD-DEADLINE-QUERY-TIMEOUT (NEW): tracks the upgrade from soft
   post-call microtime deadline to a hard deadline that can interrupt
   hanging MySQL queries (connection-level timeouts, MAX_EXECUTION_TIME
   hints, or pcntl_alarm). Previously documented as 'soft deadline
   limitation' inline in code comments without an actionable BACKLOG
   ticket.

No spec changes; no code changes. Closes the chat-identified gaps so
WS-6 v1.3-delta closure has zero un-anchored mental TODOs.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
bert.hausmans merged commit 39de4d5753 into main 2026-05-08 10:30:20 +02:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
bert.hausmans
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: bert.hausmans/crewli#12
Delete Branch "docs/ws-6-v1.3-delta-closure"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?