docs(M19): DOCS_AUDIT-job — spec (rev2) + approved implementatieplan (v9) #103

Merged

janpeter merged 11 commits from claude/keen-khayyam-3edfee into main 2026-07-04 23:43:57 +02:00

Conversation 0 Commits 11 Files changed 3 +1656

janpeter commented 2026-07-04 23:30:51 +02:00

Owner

Copy link

Docs-only: ontwerp + implementatieplan voor een nieuwe dagelijkse DOCS_AUDIT-job die documentatie synchroon houdt met wat gemergde PR's daadwerkelijk deden. Geen code in deze PR.

Wat

Een systemd-timer op scrum4me-server (05:30 UTC) curlt /api/cron/enqueue-docs-audit, dat per product met repo_url een DOCS_AUDIT-job enqueued. Een dedicated worker-docs-service (capability docs_audit) op de 154 vergelijkt de sinds de vorige run gemergde Forgejo-PR's met de docs, fixt drift, en rapporteert via job-summary + web-push.

Kernontwerp: nieuw ClaudeJobKind.DOCS_AUDIT, géén nieuwe kolommen (enum + source-agnostische constraint-tak + twee partial indexen). De doc-push is runner-owned: de agent commit lokaal en schrijft een handoff, waarna de runner de diff valideert (alleen-markdown) en pusht naar de default branch met een push-token dat niet in de agent-env zit.

Bestanden

• docs/superpowers/specs/2026-07-04-docs-audit-job-design.md (rev 2)
• docs/plans/M19-docs-audit-job.md (v9, status: approved)
• docs/INDEX.md (gegenereerd)

Review

Brainstorm → spec → plan → multi-model review. Het plan is approved na een Haiku/Sonnet/Opus-panel plus 6 codex-rondes (r1–r5 NO-GO → r6 GO, geen blockers). Belangrijkste vondsten die het ontwerp hardden: het claim-filter-gat (jobs zouden anders eeuwig QUEUED blijven), de omzeilbare client-side pre-push-hook (→ runner-gevalideerde push met credential-scheiding), en het ontbrekende callable pad voor runner-terminalisatie (→ gedeelde applyDocsAuditTerminalUpdate-helper met atomaire status-guard).

Preconditie voor de bouw

repo_url-backfill voor scrum4me-workers (staat op NULL ondanks een echte repo).

🤖 Generated with Claude Code

Docs-only: ontwerp + implementatieplan voor een nieuwe dagelijkse `DOCS_AUDIT`-job die documentatie synchroon houdt met wat gemergde PR's daadwerkelijk deden. **Geen code** in deze PR. ## Wat Een systemd-timer op scrum4me-server (05:30 UTC) curlt `/api/cron/enqueue-docs-audit`, dat per product met `repo_url` een `DOCS_AUDIT`-job enqueued. Een dedicated `worker-docs`-service (capability `docs_audit`) op de 154 vergelijkt de sinds de vorige run gemergde Forgejo-PR's met de docs, fixt drift, en rapporteert via job-summary + web-push. Kernontwerp: nieuw `ClaudeJobKind.DOCS_AUDIT`, géén nieuwe kolommen (enum + source-agnostische constraint-tak + twee partial indexen). De doc-push is **runner-owned**: de agent commit lokaal en schrijft een handoff, waarna de runner de diff valideert (alleen-markdown) en pusht naar de default branch met een push-token dat niet in de agent-env zit. ## Bestanden - `docs/superpowers/specs/2026-07-04-docs-audit-job-design.md` (rev 2) - `docs/plans/M19-docs-audit-job.md` (v9, `status: approved`) - `docs/INDEX.md` (gegenereerd) ## Review Brainstorm → spec → plan → multi-model review. Het plan is **approved** na een Haiku/Sonnet/Opus-panel plus **6 codex-rondes** (r1–r5 NO-GO → r6 GO, geen blockers). Belangrijkste vondsten die het ontwerp hardden: het claim-filter-gat (jobs zouden anders eeuwig QUEUED blijven), de omzeilbare client-side pre-push-hook (→ runner-gevalideerde push met credential-scheiding), en het ontbrekende callable pad voor runner-terminalisatie (→ gedeelde `applyDocsAuditTerminalUpdate`-helper met atomaire status-guard). ## Preconditie voor de bouw `repo_url`-backfill voor scrum4me-workers (staat op NULL ondanks een echte repo). 🤖 Generated with [Claude Code](https://claude.com/claude-code)

janpeter added 11 commits 2026-07-04 23:30:51 +02:00

docs(spec): DOCS_AUDIT-job design — dagelijkse docs-drift-audit per product-repo ... b8c9a94725

Brainstorm-besluiten JP 2026-07-04: alle producten met repo_url, mandaat
direct bijwerken zonder review, volwaardige job-kind (aanpak A) met
worker-docs op scrum4me-server + systemd-timer 05:30 UTC.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs(spec): DOCS_AUDIT — scrum4me-workers repo_url-backfill als precondition ... 42872df6ea

scrum4me-workers (en agent-rules) hebben repo_url=NULL in de product-tabel;
de repo_url-keyed loop zou scrum4me-workers stil overslaan. Backfill als
harde rollout-precondition vóór de timer; agent-rules blijft open beslissing.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs(plan): M19 DOCS_AUDIT-job implementatieplan ... 72c76d9e36

4-repo-fasering (shared→web→mcp→server→E2E) gespiegeld op M17. Geen nieuwe
kolommen: enum-waarde + source-agnostische constraint-tak + partial dedup-index.
Cron-endpoint enqueued per product met repo_url; worker-docs op 154 fixt drift
direct (doc-commits + Scrum4Me DB-mirror). Cursor-helper in shared, prompt-hardstop
alleen-markdown. Open punten uit spec §11 opgelost in Inputs.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs(plan): M19 v2 — multi-model review-hardening verwerkt ... ee6a992b12

Haiku/Sonnet/Opus review. HIGH-fixes: claim-filter + docs_audit-only
worker-isolatie (Task 3.5, nieuw); deterministische pre-push markdown-guard;
DOCS_AUDIT_ENABLED kill-switch als uitrol-gate; expliciete pg_notify.
MEDIUM: npm ci + soft-fail DB-mirror, active-job-guard + single-replica,
source=MANUAL, cursor laatste-regel/laatste-match, harde repo_url-backfill.
LOW: restart-uitsluiting, finished_at-filter, byte-gelijk constraint-test.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs(plan): M19 v3 — codex r1 HIGH#1/#2/MEDIUM#4 verwerkt ... 17c41976ff

- Task 3.6 (nieuw): DOCS_AUDIT terminal-lifecycle in update_job_status
  (mcp-stable weigerde skipped/done voor SYSTEM-jobs) + server-afgedwongen
  cap-cursor via processed_until/capped (fix voor de vrije-tekst-lekkage).
- Task 1.3: DB-harde active-job-index claude_jobs_docs_audit_active sluit
  de timer+handmatig-race; cron + dispatch vangen P2002.
- Task 3.5: fragment-builder-assert toegevoegd.

Open: codex HIGH#3 (pre-push-hook omzeilbaar door de agent) — mandaatkeuze
voor de gebruiker.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs(plan): M19 v4 — codex HIGH#3 opgelost via runner-gevalideerde push ... 19a8c1cb9c

User-keuze: Task 4.0 (scrum4me-docker) — agent commit maar pusht niet;
read-only token voor de agent, push-token + isMarkdownOnlyDiff-validatie bij
de runner. Deterministische markdown-only-grens buiten de LLM. Prompt/payload/
worker-env/E2E-6 daarop aangepast; skip-vóór-clone behouden. Fase-4-header +
volgorde + matrix bijgewerkt; Fase 5 (E2E)-header hersteld.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs(plan+spec): M19 v5 — codex r2 HIGH#1/#2/#3 opgelost ... d1374a1db1

- HIGH#1 terminalisatie-ordening: agent zet geen status meer (update_job_status
  uit allowlist, Task 0.2); schrijft handoff naar $RESULT_PATH; runner
  valideert→pusht→terminaliseert terwijl job nog CLAIMED/RUNNING (Task 3.2/3.6/4.0).
- HIGH#2 credential-scheiding: concrete DOCS_AUDIT_READ_TOKEN/PUSH_TOKEN +
  testbare buildDocsAuditChildEnv-redactie + env-test (Task 4.0/4.3/E2E-6).
- HIGH#3 default-branch: runner resolvet default branch, origin/<default>...HEAD
  + push HEAD:<default>; E2E-6 test master-based scrum4me-docker.
- Task 3.6 cursor-integratietest (step 3c); spec rev2 verzoend (runner-push,
  twee tokens, geen agent-push).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs(plan+spec): M19 v6 — codex r3 HIGH#1/#2 + MED#3 opgelost ... a765a7f80a

- HIGH#1: spec §3.1 grantte de agent nog update_job_status → verwijderd; spec
  §4 stap 1 = skipped-handoff + runner-SKIPPED. Task 0.2-test = bron van waarheid.
- HIGH#2: Task 3.6 exporteert herbruikbare applyDocsAuditTerminalUpdate-helper
  (tool + runner delen 'm; runner importeert uit update-job-status.ts zoals
  runDeferredWorktreeCleanup). Task 4.0 roept die aan i.p.v. 'update_job_status'.
- MED#3: route DOCS_AUDIT vóór de skipped-gate (:786) én MANUAL-done-shortcut
  (:839); integratietests SYSTEM/MANUAL skipped + MANUAL done capped.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs(plan): M19 v7 — codex r4 HIGH#1 + MED#2 + LOW#3 opgelost ... 2b21fb7617

- HIGH#1: Task 4.0 geeft processedUntil+capped door op ELK done-pad (lege diff,
  push, zero-commit) — gecapte run zonder commits behoudt nu de cursor.
- MED#2: applyDocsAuditTerminalUpdate dwingt status IN (CLAIMED,RUNNING) af via
  conditionele update; tests voor al-DONE/CANCELLED.
- LOW#3: skipReason in checkDocsAuditTerminal + negatieve test.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs(plan): M19 v8 — codex r5 MED#1 (TOCTOU) + LOW#2 opgelost ... 8c4d971e54

- MED#1: applyDocsAuditTerminalUpdate doet één atomaire conditionele update met
  alle invarianten in de WHERE (id + kind + claimed_by_token_id + status IN
  CLAIMED/RUNNING) i.p.v. read-then-update; stale-lease-race dicht + regressietest.
- LOW#2: parseDocsAuditCursor-comment gecorrigeerd (server-side marker).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs(plan): M19 v9 — codex GO (r6); status approved ... b31a4471f9

Codex-loop afgerond: r1-r5 NO-GO -> r6 GO, geen blockers. Laatste LOW
(module-comment) opgeruimd. Plan approved 2026-07-04 na Haiku/Sonnet/Opus-panel
+ 6 codex-rondes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

janpeter merged commit 016426d4e7 into main 2026-07-04 23:43:57 +02:00

janpeter referenced this pull request from a commit 2026-07-04 23:43:58 +02:00

Merge pull request 'docs(M19): DOCS_AUDIT-job — spec (rev2) + approved implementatieplan (v9)' (#103) from claude/keen-khayyam-3edfee into main

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels

No items

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

janpeter/Scrum4Me!103

No description provided.