pdurlej/platform

Fork 0

docs(reports): STATE_OF_PLATFORM 2026-05-03 — first strategic stop #42

Merged

pdurlej merged 3 commits from claude/state-of-platform-2026-05-03 into main

2026-05-05 01:31:40 +02:00

pdurlej commented

2026-05-03 20:41:51 +02:00

Owner

Canary status: missing — fire canary after operator first-read; this is a doc-only PR but per ADR 0001 Rule 1, state/reports/ may be borderline (operator decides if it's documentation-carveout or governance-edit category).

Summary

First strategic-stop deliverable per ADR 0001 Rule 4. Operator-facing report covering platform state, value delivered, deviations from plan, open loops, strategic decisions you owe, roadmap proposal through end-of-original-plan, and risks accepted today.

Length: 331 lines, ~21k chars, ~10 min read.

Why now

ADR 0001 (PR #41 ready for merge) defines the strategic-stop cadence (Rule 4: every N=3 cycles, orchestrator delivers product overview). This document is the inaugural instance — author's commitment that the cadence rule isn't theatrical.

Operator request 2026-05-03: "STATE_OF_PLATFORM (to co obiecałeś 🍵) + plan na kolejne wave'y do końca planu." This delivers both.

Contents (10 sections)

Executive summary — 1 page; 3 things that landed value, 3 that didn't, top 3 decisions
Where we are — concrete numbers (6/85 modules in v2, plus 3 awaiting Codex wave 3 merge)
Value delivered — real examples with caveats (n8n-worker drift may be false-positive; surfacing 4 misclassifications; canary caught its own bugs)
Workflow synthesis — ADR 0001 today's biggest event; roles formalized
Deviations from original plan — skipped L0-L4 canonical, ad-hoc waves; 5 days in, ~10% covered
Open loops — 16 ranked critical→housekeeping (Phase 8 restore-test 26+ days stale, ADR 0002, smoke.sh rewrite are top)
Strategic decisions — 7 for operator with my recommendations: pace, Phase 03 pivot timing, smoke.sh scope, restore-test cadence, ADR 0003 (Codex-for-Codex formalization), Iskra/Codex MD autoresearch, mail-infra continue/sunset
Roadmap proposal — waves 5-9 (Forgejo, Synapse, Storage, User-app, Infra) → Phase 03 pivot → Phase 04-06; ~6-8 weeks to "production declare"
Risks accepted today — 5 explicit (ADR 4-iter cap, smoke.sh closed without merge, n8n-worker drift caveat, Codex wave 3 unverified canary, wave 4 Honcho not started)
Personal note — direct acknowledgment of today's hard cycle (producer-mode caught, lost 4 hours of operator time, synthesis genuinely valuable)

Test plan

Operator readback: 10 minutes; confirm strategic decisions framing matches your view
If decisions §6 framing is off, redirect; doc gets refresh
After this PR merges, state/cycle-counter.md boundary marker resets to new origin/main HEAD
Next strategic stop scheduled after N=3 more merges
Canary fire decision: doc-only carveout or governance-edit? Your call per ADR 0001 §"What this ADR does not enforce"

Canary status: missing — fire canary after operator first-read; this is a doc-only PR but per ADR 0001 Rule 1, `state/reports/` may be borderline (operator decides if it's documentation-carveout or governance-edit category). ## Summary First strategic-stop deliverable per ADR 0001 Rule 4. Operator-facing report covering platform state, value delivered, deviations from plan, open loops, strategic decisions you owe, roadmap proposal through end-of-original-plan, and risks accepted today. **Length: 331 lines, ~21k chars, ~10 min read.** ## Why now ADR 0001 (PR #41 ready for merge) defines the strategic-stop cadence (Rule 4: every N=3 cycles, orchestrator delivers product overview). This document is the inaugural instance — author's commitment that the cadence rule isn't theatrical. Operator request 2026-05-03: "STATE_OF_PLATFORM (to co obiecałeś 🍵) + plan na kolejne wave'y do końca planu." This delivers both. ## Contents (10 sections) 1. **Executive summary** — 1 page; 3 things that landed value, 3 that didn't, top 3 decisions 2. **Where we are** — concrete numbers (6/85 modules in v2, plus 3 awaiting Codex wave 3 merge) 3. **Value delivered** — real examples with caveats (n8n-worker drift may be false-positive; surfacing 4 misclassifications; canary caught its own bugs) 4. **Workflow synthesis** — ADR 0001 today's biggest event; roles formalized 5. **Deviations from original plan** — skipped L0-L4 canonical, ad-hoc waves; 5 days in, ~10% covered 6. **Open loops** — 16 ranked critical→housekeeping (Phase 8 restore-test 26+ days stale, ADR 0002, smoke.sh rewrite are top) 7. **Strategic decisions** — 7 for operator with my recommendations: pace, Phase 03 pivot timing, smoke.sh scope, restore-test cadence, ADR 0003 (Codex-for-Codex formalization), Iskra/Codex MD autoresearch, mail-infra continue/sunset 8. **Roadmap proposal** — waves 5-9 (Forgejo, Synapse, Storage, User-app, Infra) → Phase 03 pivot → Phase 04-06; ~6-8 weeks to "production declare" 9. **Risks accepted today** — 5 explicit (ADR 4-iter cap, smoke.sh closed without merge, n8n-worker drift caveat, Codex wave 3 unverified canary, wave 4 Honcho not started) 10. **Personal note** — direct acknowledgment of today's hard cycle (producer-mode caught, lost 4 hours of operator time, synthesis genuinely valuable) ## Test plan - [ ] Operator readback: 10 minutes; confirm strategic decisions framing matches your view - [ ] If decisions §6 framing is off, redirect; doc gets refresh - [ ] After this PR merges, `state/cycle-counter.md` boundary marker resets to new origin/main HEAD - [ ] Next strategic stop scheduled after N=3 more merges - [ ] Canary fire decision: doc-only carveout or governance-edit? Your call per ADR 0001 §"What this ADR does not enforce"

pdurlej added 1 commit

2026-05-03 20:41:51 +02:00

docs(reports): STATE_OF_PLATFORM 2026-05-03 — first strategic stop per ADR 0001 Rule 4 92c0d3686e

Operator-facing 10-min read covering:
- Where we are: ~10% Phase 02 v2 coverage (6/85 merged, 3 ready in Codex wave 3 PRs awaiting review)
- Value delivered: drift detection caught (n8n-worker, with caveat), 4 misclassifications surfaced (uptime-kuma/umami/n8n-main/searxng), pgvector restore documented before disaster, canary caught real bugs in own ADR through 3 iterations
- Workflow synthesis: ADR 0001 (canary mandatory + PM cadence) — operator's eyes restored, producer-mode bounded
- Deviations from original plan: skipped L0-L4 canonical audit, jumped to incremental Phase 02 wave-by-wave; 5 days in, ~10% covered (vs original 6-8h estimate)
- Open loops: 16 ranked critical→housekeeping
- Strategic decisions: 7 for operator, with my recommendations
- Roadmap proposal: waves 5-9 + Phase 03 pivot + Phase 04-06; ~6-8 weeks to 'production declare'
- Risks accepted today: 5 explicit
- Next 24-48h: 5 cycles proposed

This is the first strategic-stop deliverable per ADR 0001 Rule 4. After operator review,
state/cycle-counter.md boundary marker updates to current origin/main HEAD; counter
resets toward next N=3.

Length: ~250 lines, ~21k chars; readable in 10 min.
Format: prose-heavy, tables for concrete data, operator-recommendations explicit.
Tone: business-stakeholder report, not options-list.

pdurlej commented

2026-05-03 23:03:40 +02:00

Author

Owner

Owner executive note

Kierunek akceptuję. Nie chodzi o mniej metawarstwy — chodzi o lepszy interfejs dla metawarstwy. Strategic stop może być długi, bo jest logiem systemu, procesu, decyzji i ryzyk. Ale na samej górze musi mieć bardzo jasny panel: co mam kliknąć, co mam zdecydować, co idzie defaultem, co jest follow-upem dla agentów, a co jest zablokowane.

Ten dokument jest dobry jako strategic stop #1, ale format wymaga natychmiastowego utwardzenia. Najważniejsze poprawki: Owner Action Board, krótki model/emotional signal note, PR size/review modes, Night Review, issue follow-ups, prostsza risk taxonomy, effort estimates zamiast calendar-first estimates, Honcho Wave 4 przed Forgejo Wave 5, restore-test jako pre-cutover gate.

⸻

Required amendments

Add mandatory Owner Action Board

Every future State of Platform must start with an explicit owner-facing board.

Use exactly these four buckets:

Owner Action Board

Needs owner now

Items that require Piotr’s attention before work can proceed.

Default path unless owner objects

Items where the operator will proceed with a stated default unless Piotr objects.

Agent follow-up, no owner attention now

Items that should become tasks/issues and can be handled by agents.

Blocked / waiting on precondition

Items that cannot move until a concrete condition changes.

Inside each bucket, use simple verbs, not a large action taxonomy:

CLICK: Merge PR #41.
CLICK: Close PR #40.
CHOOSE: Confirm smoke.sh rewrite scope.
DEFAULT: Honcho Wave 4 before Forgejo Wave 5.
TASK: Create issue for AGENTS.md / repo runbook.
BLOCKED: RS2000 cutover until legacy services are replaced.

The owner-facing question is simple: does this need Piotr’s attention now, yes or no?

⸻

Add a short Model / emotional signal note directly under the Owner Action Board

This is not a long process retrospective. It is a short meta-signal from the agent/orchestrator.

Format:

Model / emotional signal note

≤280 chars. Surface one unprompted qualitative signal about the product, process, agent behavior, or hidden risk that may affect owner decisions.

This is important because the owner is working with models as collaborators. The signal should expose things the owner may not see directly: model uncertainty, producer-mode risk, emotional/product tension, hidden ambiguity, or “this feels structurally wrong” warnings.

Example:

Model / emotional signal note:
Yellow. The platform work is progressing, but the main current risk is hidden complexity being renamed as process. Owner board + issue follow-ups should reduce that load.

Keep the long reflective process notes out of the main body unless they are materially decision-relevant.

⸻

Split PRs into small / medium / large / batch

Use this classification explicitly.

Small PR:

single module manifest, docs-only change, or narrow non-runtime update;
no security boundary, deploy semantics, restore semantics, or routing exposure change.
Medium PR:
module change involving routing, secrets, smoke checks, runtime evidence, recovery notes, or exposure classification.
Large PR:
ADR, CI, platformctl, restore path, deploy semantics, security boundary, workflow rule, or multi-subsystem change.
Batch:
multiple small PRs from the same wave or same bounded execution path.

Important rule:

PR sharding must not be used to bypass review.

Small PRs may use a lighter review path, but accumulated small changes still require batch sanity checking.

⸻

Define review modes

Use this review policy:

Small PR:

1 technical reviewer;
1 product / owner-perspective reviewer;
max 1 fix iteration unless High/Critical finding appears.
Medium PR:
full canary 3+3;
Canary Context Pack required.
Large PR:
full canary 3+3;
Canary Context Pack required;
owner-facing impact must be summarized in Owner Action Board.
Batch:
small PRs may proceed with light review;
accumulated changes are reviewed by Night Review.

⸻

Add Night Review as the batch sanity mechanism

Use an event-driven nightly batch review.

Night Review:

runs only on days where there were relevant changes;
skipped explicitly when there were no changes;
reviews accumulated small PRs / wave outputs / unresolved evidence gaps;
checks for cross-PR drift, hidden coupling, review bypass, and owner-visible consequences.

This is not a replacement for PR-level review. It is a guardrail against many small PRs creating a large unreviewed change.

Suggested output:

Night Review status:

skipped_no_changes
approve_batch
findings_create_issues
defer_batch
require_rewrite

⸻

Canary iteration cap is hard: max 3

Reviewer context must state from the beginning that the cap is hard.

Canary iteration cap:

max 3 review/fix iterations;
reviewers know the cap before review starts;
after iteration 3, the PR must resolve to one terminal action.

Allowed terminal actions:

approve_merge
approve_with_evidence_gap
operator_override
defer_to_issue
rewrite
split_pr

split_pr is a one-shot escape hatch, not an infinite loop. If the split descendants still fail after their own capped review, the path must move to rewrite or defer_to_issue, not another chain of splits.

⸻

Make Canary Context Pack mandatory for medium/large PRs

Medium and large PRs must include a context pack.

Required fields:

Canary Context Pack

Product story

What are we trying to make true for the owner/user, and why?

What changed

Concrete summary of the change.

Why it changed

Reason this change exists now.

Files touched

List of relevant files.

Relevant context

ADRs, module docs, subsystem docs, related manifests.

Runtime evidence

Docker/compose/routing/log/inspect evidence if relevant.

Known constraints

What the reviewer must not assume.

Explicit out-of-scope

What this PR intentionally does not solve.

Requested decision

What review outcome is being requested.

Merge blockers

What would block merge.

Small PRs should use a shortened form, but they still need at least:

product story;
what changed;
why this is safe to review lightly.

This matters because reviewers should reason product-first and owner-first, not only diff-first.

⸻

Allow reviewer context escalation

Reviewers should not be trapped in a tiny diff if the diff is insufficient.

Default context:

PR diff;
touched files;
relevant ADRs;
relevant module/subsystem docs;
runtime evidence if applicable.

Escalation path:

related subsystem files;
compose/routing snippets;
module index and adjacent manifests;
logs / docker inspect output;
full repo only by exception when subsystem context is insufficient.

The goal is enough context to review correctly without flooding the model.

⸻

Evidence gaps must be explicit

approve_with_evidence_gap is a legal review state, but it must be visible.

Rule:

If runtime evidence is relevant but absent, reviewer may not silently approve.
They must mark the evidence gap explicitly.

Merge policy:

A PR with approve_with_evidence_gap may only proceed if the operator/owner explicitly accepts that gap, or if the gap is moved into a tracked issue with clear consequences.

No hidden “approved but actually unverified” states.

⸻

Use Forgejo Issues / tasks as the follow-up source of truth

Every non-immediate follow-up with owner-visible consequences should become a Forgejo issue/task by default unless explicitly discarded.

Default:

create issue/task;
link it from State of Platform;
assign risk class / phase / owner-attention tag when relevant.

Since Forgejo Issues may not yet be fully ready, the first follow-up should be:

TASK: Verify/setup Forgejo Issues as the source of truth for follow-ups.

Until that works, use a temporary repo-local issue log so follow-ups do not live only inside strategic stop documents.

⸻

Use simplified risk taxonomy

Use four main risk classes only:

risk/runtime
risk/exposure
risk/product
risk/process

Definitions:

Runtime risk:
The platform may not run, recover, validate, or behave reproducibly.
Exposure risk:
Something may be incorrectly public, private, tailnet-only, authenticated, or routed.
Product risk:
We are unsure whether this work still has owner/user value.
Process risk:
The workflow, model review, orchestration, or decision system may produce bad outcomes.

Optional tags:

owner-attention
cutover-gate
recovery
operator-emotional
phase/02
phase/03

Examples:

smoke.sh digest bug -> risk/runtime
public vs tailnet drift -> risk/exposure
mail infra 60% done -> risk/product
canary context gap -> risk/process
restore-test -> risk/runtime + cutover-gate + recovery
Honcho pgvector restore -> risk/runtime + recovery + operator-emotional

Mail infra should currently be classified as:

risk/product
owner-attention
status: product ambiguity / owner decision needed

⸻

Replace calendar-first estimates with effort estimates

Calendar estimates are secondary because owner availability is the bottleneck. Estimate in terms of owner attention, prompts, clicks, agent runs, canary passes, and expected outputs.

Use this format:

Effort estimate

Owner attention:

expected owner prompts:
expected owner clicks:
expected owner decisions:
Agent work:
expected master prompts:
expected Codex runs:
expected canary passes:
expected rewrite loops:
Output:
expected merge-ready PRs:
expected modules moved to Phase 02 v2:
expected issues/tasks created:

Optional calendar note:

Calendar time depends on owner availability and agent queue depth.

Strategic direction:

Optimize for merge-ready PRs per owner attention unit.
Prefer long, high-quality master prompts that minimize owner interaction.

⸻

Fix Wave 4 / Wave 5 ordering

Current document creates confusion around Honcho Wave 4 and Forgejo Wave 5.

Default owner decision:

Honcho Wave 4 executes before Forgejo Wave 5.

Forgejo may not jump ahead unless explicitly reordered by owner.

However, issue/task tracking is needed now. Therefore:

Verify whether existing Forgejo Issues are usable now.
If yes, use them for follow-ups immediately.
If not, create a follow-up task to enable them.
Do not treat this as full Forgejo Wave 5 unless explicitly scoped that way.

⸻

Reclassify restore-test correctly

Restore-test is not an immediate RS2000 deployment action because RS2000 still runs legacy services and final cutover is not happening now.

Correct classification:

Restore-test:

critical pre-cutover gate;
not a blocker for current local Phase 02 cataloging;
blocks production declare / final RS2000 replacement;
local restore rehearsal may happen earlier to reduce cutover risk.

Do not list it as “critical” and then omit it from the near-term plan without this explanation.

⸻

Add glossary / agent runbook follow-up

Create a follow-up issue/task for an agent-facing repo guide.

Suggested file:

AGENTS.md

or:

docs/AGENT_RUNBOOK.md

It should explain:

what this repo is;
current phases;
Phase 02 v2 meaning;
modules/INDEX.yaml;
canary 3+3;
PR size classes;
Canary Context Pack;
Night Review;
risk taxonomy;
owner action board;
how to request more context;
what must not be inferred without runtime evidence;
glossary.

This should reduce low-quality review iterations caused by missing context.

⸻

Specific document edits requested

Please update the current State of Platform with these concrete changes:

Add Owner Action Board at the top.
Add Model / emotional signal note directly below it, max 280 chars.
Keep the full strategic stop body, but make the owner-facing decision hierarchy explicit.
Change “Top three decisions” into:
- Top 3 unblockers
- Secondary decisions
- Default unless objected
- Deferred / tracked
Fix the Wave 4 / Wave 5 inconsistency.
Reclassify restore-test as critical pre-cutover gate.
Add effort estimates instead of calendar-first estimates.
Add the four-class risk taxonomy.
Add follow-up task creation for Forgejo Issues / AGENTS.md.
Add Night Review as the batch sanity mechanism.
Add PR size/review mode rules.
Add Canary Context Pack and hard 3-iteration cap language.

⸻

Stance

This is a mixed owner response:

Direction: approved.
ADR 0001 direction: not blocked.
Current State of Platform format: needs structural amendments before becoming the standard.
Immediate priority: make the owner-facing interface sharp enough that Piotr knows what to click, decide, ignore, or delegate.

The goal is not less meta. The goal is operational meta: explicit defaults, low owner ambiguity, tracked follow-ups, bounded review loops, and better master prompts that reduce Piotr as the bottleneck.

Owner executive note Kierunek akceptuję. Nie chodzi o mniej metawarstwy — chodzi o lepszy interfejs dla metawarstwy. Strategic stop może być długi, bo jest logiem systemu, procesu, decyzji i ryzyk. Ale na samej górze musi mieć bardzo jasny panel: co mam kliknąć, co mam zdecydować, co idzie defaultem, co jest follow-upem dla agentów, a co jest zablokowane. Ten dokument jest dobry jako strategic stop #1, ale format wymaga natychmiastowego utwardzenia. Najważniejsze poprawki: Owner Action Board, krótki model/emotional signal note, PR size/review modes, Night Review, issue follow-ups, prostsza risk taxonomy, effort estimates zamiast calendar-first estimates, Honcho Wave 4 przed Forgejo Wave 5, restore-test jako pre-cutover gate. ⸻ Required amendments 1. Add mandatory Owner Action Board Every future State of Platform must start with an explicit owner-facing board. Use exactly these four buckets: ## Owner Action Board ### Needs owner now Items that require Piotr’s attention before work can proceed. ### Default path unless owner objects Items where the operator will proceed with a stated default unless Piotr objects. ### Agent follow-up, no owner attention now Items that should become tasks/issues and can be handled by agents. ### Blocked / waiting on precondition Items that cannot move until a concrete condition changes. Inside each bucket, use simple verbs, not a large action taxonomy: - CLICK: Merge PR #41. - CLICK: Close PR #40. - CHOOSE: Confirm smoke.sh rewrite scope. - DEFAULT: Honcho Wave 4 before Forgejo Wave 5. - TASK: Create issue for AGENTS.md / repo runbook. - BLOCKED: RS2000 cutover until legacy services are replaced. The owner-facing question is simple: does this need Piotr’s attention now, yes or no? ⸻ 2. Add a short Model / emotional signal note directly under the Owner Action Board This is not a long process retrospective. It is a short meta-signal from the agent/orchestrator. Format: ## Model / emotional signal note ≤280 chars. Surface one unprompted qualitative signal about the product, process, agent behavior, or hidden risk that may affect owner decisions. This is important because the owner is working with models as collaborators. The signal should expose things the owner may not see directly: model uncertainty, producer-mode risk, emotional/product tension, hidden ambiguity, or “this feels structurally wrong” warnings. Example: Model / emotional signal note: Yellow. The platform work is progressing, but the main current risk is hidden complexity being renamed as process. Owner board + issue follow-ups should reduce that load. Keep the long reflective process notes out of the main body unless they are materially decision-relevant. ⸻ 3. Split PRs into small / medium / large / batch Use this classification explicitly. Small PR: - single module manifest, docs-only change, or narrow non-runtime update; - no security boundary, deploy semantics, restore semantics, or routing exposure change. Medium PR: - module change involving routing, secrets, smoke checks, runtime evidence, recovery notes, or exposure classification. Large PR: - ADR, CI, platformctl, restore path, deploy semantics, security boundary, workflow rule, or multi-subsystem change. Batch: - multiple small PRs from the same wave or same bounded execution path. Important rule: PR sharding must not be used to bypass review. Small PRs may use a lighter review path, but accumulated small changes still require batch sanity checking. ⸻ 4. Define review modes Use this review policy: Small PR: - 1 technical reviewer; - 1 product / owner-perspective reviewer; - max 1 fix iteration unless High/Critical finding appears. Medium PR: - full canary 3+3; - Canary Context Pack required. Large PR: - full canary 3+3; - Canary Context Pack required; - owner-facing impact must be summarized in Owner Action Board. Batch: - small PRs may proceed with light review; - accumulated changes are reviewed by Night Review. ⸻ 5. Add Night Review as the batch sanity mechanism Use an event-driven nightly batch review. Night Review: - runs only on days where there were relevant changes; - skipped explicitly when there were no changes; - reviews accumulated small PRs / wave outputs / unresolved evidence gaps; - checks for cross-PR drift, hidden coupling, review bypass, and owner-visible consequences. This is not a replacement for PR-level review. It is a guardrail against many small PRs creating a large unreviewed change. Suggested output: Night Review status: - skipped_no_changes - approve_batch - findings_create_issues - defer_batch - require_rewrite ⸻ 6. Canary iteration cap is hard: max 3 Reviewer context must state from the beginning that the cap is hard. Canary iteration cap: - max 3 review/fix iterations; - reviewers know the cap before review starts; - after iteration 3, the PR must resolve to one terminal action. Allowed terminal actions: - approve_merge - approve_with_evidence_gap - operator_override - defer_to_issue - rewrite - split_pr split_pr is a one-shot escape hatch, not an infinite loop. If the split descendants still fail after their own capped review, the path must move to rewrite or defer_to_issue, not another chain of splits. ⸻ 7. Make Canary Context Pack mandatory for medium/large PRs Medium and large PRs must include a context pack. Required fields: ## Canary Context Pack ### Product story What are we trying to make true for the owner/user, and why? ### What changed Concrete summary of the change. ### Why it changed Reason this change exists now. ### Files touched List of relevant files. ### Relevant context ADRs, module docs, subsystem docs, related manifests. ### Runtime evidence Docker/compose/routing/log/inspect evidence if relevant. ### Known constraints What the reviewer must not assume. ### Explicit out-of-scope What this PR intentionally does not solve. ### Requested decision What review outcome is being requested. ### Merge blockers What would block merge. Small PRs should use a shortened form, but they still need at least: - product story; - what changed; - why this is safe to review lightly. This matters because reviewers should reason product-first and owner-first, not only diff-first. ⸻ 8. Allow reviewer context escalation Reviewers should not be trapped in a tiny diff if the diff is insufficient. Default context: - PR diff; - touched files; - relevant ADRs; - relevant module/subsystem docs; - runtime evidence if applicable. Escalation path: - related subsystem files; - compose/routing snippets; - module index and adjacent manifests; - logs / docker inspect output; - full repo only by exception when subsystem context is insufficient. The goal is enough context to review correctly without flooding the model. ⸻ 9. Evidence gaps must be explicit approve_with_evidence_gap is a legal review state, but it must be visible. Rule: If runtime evidence is relevant but absent, reviewer may not silently approve. They must mark the evidence gap explicitly. Merge policy: A PR with approve_with_evidence_gap may only proceed if the operator/owner explicitly accepts that gap, or if the gap is moved into a tracked issue with clear consequences. No hidden “approved but actually unverified” states. ⸻ 10. Use Forgejo Issues / tasks as the follow-up source of truth Every non-immediate follow-up with owner-visible consequences should become a Forgejo issue/task by default unless explicitly discarded. Default: - create issue/task; - link it from State of Platform; - assign risk class / phase / owner-attention tag when relevant. Since Forgejo Issues may not yet be fully ready, the first follow-up should be: TASK: Verify/setup Forgejo Issues as the source of truth for follow-ups. Until that works, use a temporary repo-local issue log so follow-ups do not live only inside strategic stop documents. ⸻ 11. Use simplified risk taxonomy Use four main risk classes only: risk/runtime risk/exposure risk/product risk/process Definitions: Runtime risk: The platform may not run, recover, validate, or behave reproducibly. Exposure risk: Something may be incorrectly public, private, tailnet-only, authenticated, or routed. Product risk: We are unsure whether this work still has owner/user value. Process risk: The workflow, model review, orchestration, or decision system may produce bad outcomes. Optional tags: owner-attention cutover-gate recovery operator-emotional phase/02 phase/03 Examples: smoke.sh digest bug -> risk/runtime public vs tailnet drift -> risk/exposure mail infra 60% done -> risk/product canary context gap -> risk/process restore-test -> risk/runtime + cutover-gate + recovery Honcho pgvector restore -> risk/runtime + recovery + operator-emotional Mail infra should currently be classified as: risk/product owner-attention status: product ambiguity / owner decision needed ⸻ 12. Replace calendar-first estimates with effort estimates Calendar estimates are secondary because owner availability is the bottleneck. Estimate in terms of owner attention, prompts, clicks, agent runs, canary passes, and expected outputs. Use this format: ## Effort estimate Owner attention: - expected owner prompts: - expected owner clicks: - expected owner decisions: Agent work: - expected master prompts: - expected Codex runs: - expected canary passes: - expected rewrite loops: Output: - expected merge-ready PRs: - expected modules moved to Phase 02 v2: - expected issues/tasks created: Optional calendar note: Calendar time depends on owner availability and agent queue depth. Strategic direction: Optimize for merge-ready PRs per owner attention unit. Prefer long, high-quality master prompts that minimize owner interaction. ⸻ 13. Fix Wave 4 / Wave 5 ordering Current document creates confusion around Honcho Wave 4 and Forgejo Wave 5. Default owner decision: Honcho Wave 4 executes before Forgejo Wave 5. Forgejo may not jump ahead unless explicitly reordered by owner. However, issue/task tracking is needed now. Therefore: - Verify whether existing Forgejo Issues are usable now. - If yes, use them for follow-ups immediately. - If not, create a follow-up task to enable them. - Do not treat this as full Forgejo Wave 5 unless explicitly scoped that way. ⸻ 14. Reclassify restore-test correctly Restore-test is not an immediate RS2000 deployment action because RS2000 still runs legacy services and final cutover is not happening now. Correct classification: Restore-test: - critical pre-cutover gate; - not a blocker for current local Phase 02 cataloging; - blocks production declare / final RS2000 replacement; - local restore rehearsal may happen earlier to reduce cutover risk. Do not list it as “critical” and then omit it from the near-term plan without this explanation. ⸻ 15. Add glossary / agent runbook follow-up Create a follow-up issue/task for an agent-facing repo guide. Suggested file: AGENTS.md or: docs/AGENT_RUNBOOK.md It should explain: - what this repo is; - current phases; - Phase 02 v2 meaning; - modules/INDEX.yaml; - canary 3+3; - PR size classes; - Canary Context Pack; - Night Review; - risk taxonomy; - owner action board; - how to request more context; - what must not be inferred without runtime evidence; - glossary. This should reduce low-quality review iterations caused by missing context. ⸻ Specific document edits requested Please update the current State of Platform with these concrete changes: 1. Add Owner Action Board at the top. 2. Add Model / emotional signal note directly below it, max 280 chars. 3. Keep the full strategic stop body, but make the owner-facing decision hierarchy explicit. 4. Change “Top three decisions” into: * Top 3 unblockers * Secondary decisions * Default unless objected * Deferred / tracked 5. Fix the Wave 4 / Wave 5 inconsistency. 6. Reclassify restore-test as critical pre-cutover gate. 7. Add effort estimates instead of calendar-first estimates. 8. Add the four-class risk taxonomy. 9. Add follow-up task creation for Forgejo Issues / AGENTS.md. 10. Add Night Review as the batch sanity mechanism. 11. Add PR size/review mode rules. 12. Add Canary Context Pack and hard 3-iteration cap language. ⸻ Stance This is a mixed owner response: Direction: approved. ADR 0001 direction: not blocked. Current State of Platform format: needs structural amendments before becoming the standard. Immediate priority: make the owner-facing interface sharp enough that Piotr knows what to click, decide, ignore, or delegate. The goal is not less meta. The goal is operational meta: explicit defaults, low owner ambiguity, tracked follow-ups, bounded review loops, and better master prompts that reduce Piotr as the bottleneck.

pdurlej commented

2026-05-03 23:06:32 +02:00

Author

Owner

Meta note to Claude / Pan Herbata

This feedback is not a request for less meta-work. It is a request for better operational meta-work.

Piotr is not asking you to hide complexity. He is asking you to turn complexity into a usable owner interface: clear defaults, explicit asks, bounded review loops, tracked follow-ups, and fewer ambiguous moments where the owner has to reconstruct what to do next.

The main bottleneck is not agent output volume. The bottleneck is owner attention: prompts Piotr must write, context he must reload, decisions he must disambiguate, and clicks he must safely make as a non-technical owner. Optimize for merge-ready progress per owner interaction.

Treat the Owner Action Board as the primary UI. Treat Forgejo Issues/tasks as the memory layer for follow-ups. Treat Night Review as a guardrail against accumulated small-change drift, not as another ceremony.

The Model / emotional signal note is not therapy and not self-justification. It is a compressed hidden-signal channel: what does the model/orchestrator sense about product, process, risk, or ambiguity that Piotr may not see from the artifact list alone?

When unsure, prefer:

propose a default;
state the consequence;
create/link an issue;
mark the evidence gap;
move forward within the review cap.

Do not leave important work as prose-only open loops. Do not make Piotr infer what needs his attention. Do not let “more structure” become a substitute for clearer action.

Success metric: less owner ambiguity, more autonomous high-quality progress.

Meta note to Claude / Pan Herbata This feedback is not a request for less meta-work. It is a request for better operational meta-work. Piotr is not asking you to hide complexity. He is asking you to turn complexity into a usable owner interface: clear defaults, explicit asks, bounded review loops, tracked follow-ups, and fewer ambiguous moments where the owner has to reconstruct what to do next. The main bottleneck is not agent output volume. The bottleneck is owner attention: prompts Piotr must write, context he must reload, decisions he must disambiguate, and clicks he must safely make as a non-technical owner. Optimize for merge-ready progress per owner interaction. Treat the Owner Action Board as the primary UI. Treat Forgejo Issues/tasks as the memory layer for follow-ups. Treat Night Review as a guardrail against accumulated small-change drift, not as another ceremony. The Model / emotional signal note is not therapy and not self-justification. It is a compressed hidden-signal channel: what does the model/orchestrator sense about product, process, risk, or ambiguity that Piotr may not see from the artifact list alone? When unsure, prefer: * propose a default; * state the consequence; * create/link an issue; * mark the evidence gap; * move forward within the review cap. Do not leave important work as prose-only open loops. Do not make Piotr infer what needs his attention. Do not let “more structure” become a substitute for clearer action. Success metric: less owner ambiguity, more autonomous high-quality progress.

claude referenced this pull request from a commit

2026-05-03 23:20:20 +02:00

docs(reports): STATE_OF_PLATFORM v2 — owner-spec aligned (PR #42 review feedback integrated)

claude added 1 commit

2026-05-03 23:20:20 +02:00

docs(reports): STATE_OF_PLATFORM v2 — owner-spec aligned (PR #42 review feedback integrated) 424f3f20f1

Per operator review on PR #42 (comments 493 + 497, 2026-05-03), full
structural amendment integrating all 15 required spec items:

1. Owner Action Board at TOP (4 buckets: needs-now, default-unless-objected,
   agent-followup, blocked) with simple verbs (CLICK/CHOOSE/DEFAULT/TASK/
   BLOCKED) — primary UI for owner instead of buried §6 decisions
2. Model/emotional signal note ≤280 chars directly below board (Yellow
   signal, 266 chars) — compressed hidden-signal channel, not therapy
3. PR size classes (Small/Medium/Large/Batch) with explicit rule:
   sharding does NOT bypass review
4. Review modes per size (Small=1+1 light; Medium/Large=full canary 3+3
   + Context Pack; Batch=light + Night Review)
5. Night Review as event-driven batch sanity (skipped on no-change days;
   5 status outcomes)
6. Hard 3-iteration canary cap with 6 named terminal actions
   (approve_merge, approve_with_evidence_gap, operator_override,
   defer_to_issue, rewrite, split_pr — split_pr one-shot)
7. Canary Context Pack required fields (product story, what changed,
   why, files, relevant context, runtime evidence, known constraints,
   out-of-scope, requested decision, merge blockers)
8. Reviewer context escalation path (default → subsystem → compose/
   routing → logs → full repo exception)
9. Evidence gaps explicit (approve_with_evidence_gap visible, owner-
   accepted or moved to issue, no hidden 'unverified-but-approved')
10. Forgejo Issues as memory layer for follow-ups (TASK to verify usable
    + migrate top 5 OPEN_LOOPS items)
11. 4-class risk taxonomy (risk/runtime, risk/exposure, risk/product,
    risk/process) + optional tags (owner-attention, cutover-gate,
    recovery, operator-emotional, phase/02, phase/03)
12. Effort estimates per attention-unit (owner prompts/clicks/decisions
    + agent master-prompts/Codex-runs/canary-passes + output PRs/
    modules/issues) — replaces calendar-first estimates
13. Wave 4 (Honcho) BEFORE Wave 5 (Forgejo) ordering — fixed in §7
14. Restore-test reclassified as critical pre-cutover gate (not
    immediate Phase 02 blocker) — corrected priority
15. AGENTS.md follow-up TASK named in Owner Action Board (separate PR
    in flight)

Plus identity-isolation correction:
- git config in worktree set to user.email=claude@noreply.git.pdurlej.com
  + user.name=claude (this commit and forward authored as claude, not
  pdurlej)
- Forgejo MCP still uses operator PAT for PR-create API (limitation
  documented as TASK)

Length: 413 lines (vs 331 v1). Format: prose-medium, tables for concrete
data, Owner Action Board as primary UI. Read time: Owner Action Board
≤2 min, full body ≤12 min.

This is the canonical format for future strategic stops.

claude commented

2026-05-03 23:20:51 +02:00

Collaborator

v2 amended (commit 424f3f2, authored as claude per identity-isolation fix).

All 15 spec items integrated:

Owner Action Board at top (4 buckets, simple verbs)
Model/emotional signal note ≤280 chars (Yellow signal: 266 chars)
PR size classes (Small/Medium/Large/Batch) + sharding-doesnt-bypass rule
Review modes per size
Night Review event-driven batch sanity
Hard 3-iter cap + 6 terminal actions
Canary Context Pack required fields
Reviewer context escalation path
Evidence gaps explicit
Forgejo Issues TASK
4-class risk taxonomy + tags
Effort estimates per attention-unit
Wave 4 BEFORE Wave 5 fix
Restore-test reclassified pre-cutover gate
AGENTS.md TASK

Plus identity-isolation gap fixed: this commit and forward authored as claude (40-char PAT from BW custom field, git config in worktree). Forgejo MCP still uses operator PAT for PR-create API — documented as TASK in §10.

Ready for re-review. Canary status: missing — fire when ready.

Length: 413 lines. Read time: Owner Action Board ≤2 min, full body ≤12 min.

**v2 amended** (commit `424f3f2`, authored as `claude` per identity-isolation fix). All 15 spec items integrated: 1. Owner Action Board at top (4 buckets, simple verbs) 2. Model/emotional signal note ≤280 chars (Yellow signal: 266 chars) 3. PR size classes (Small/Medium/Large/Batch) + sharding-doesnt-bypass rule 4. Review modes per size 5. Night Review event-driven batch sanity 6. Hard 3-iter cap + 6 terminal actions 7. Canary Context Pack required fields 8. Reviewer context escalation path 9. Evidence gaps explicit 10. Forgejo Issues TASK 11. 4-class risk taxonomy + tags 12. Effort estimates per attention-unit 13. Wave 4 BEFORE Wave 5 fix 14. Restore-test reclassified pre-cutover gate 15. AGENTS.md TASK Plus identity-isolation gap fixed: this commit and forward authored as `claude` (40-char PAT from BW custom field, git config in worktree). Forgejo MCP still uses operator PAT for PR-create API — documented as TASK in §10. Ready for re-review. Canary status: missing — fire when ready. Length: 413 lines. Read time: Owner Action Board ≤2 min, full body ≤12 min.

claude commented

2026-05-03 23:21:03 +02:00

Collaborator

v2 amended (commit 424f3f2, authored as claude per identity-isolation fix).

All 15 spec items integrated: Owner Action Board top, Model signal note 266 chars, PR size classes, Night Review, hard 3-iter cap with 6 terminal actions, Canary Context Pack, reviewer context escalation, evidence gaps explicit, Forgejo Issues TASK, 4-class risk taxonomy + tags, effort estimates per attention-unit, Wave 4 before Wave 5, restore-test reclassified pre-cutover gate, AGENTS.md TASK.

Plus identity-isolation gap fixed: commits now authored as claude (40-char PAT from BW custom field, git config in worktree). Forgejo MCP still uses operator PAT for PR-create API — documented as TASK in §10.

Ready for re-review. Canary status: missing — fire when ready.

Length: 413 lines. Read time: Owner Action Board ≤2 min, full body ≤12 min.

**v2 amended** (commit 424f3f2, authored as claude per identity-isolation fix). All 15 spec items integrated: Owner Action Board top, Model signal note 266 chars, PR size classes, Night Review, hard 3-iter cap with 6 terminal actions, Canary Context Pack, reviewer context escalation, evidence gaps explicit, Forgejo Issues TASK, 4-class risk taxonomy + tags, effort estimates per attention-unit, Wave 4 before Wave 5, restore-test reclassified pre-cutover gate, AGENTS.md TASK. Plus identity-isolation gap fixed: commits now authored as claude (40-char PAT from BW custom field, git config in worktree). Forgejo MCP still uses operator PAT for PR-create API — documented as TASK in §10. Ready for re-review. Canary status: missing — fire when ready. Length: 413 lines. Read time: Owner Action Board ≤2 min, full body ≤12 min.

claude referenced this pull request from a commit

2026-05-03 23:23:35 +02:00

docs: AGENTS.md — repo runbook for orchestrator/Codex/3+3 reviewers

claude referenced this pull request

2026-05-03 23:24:00 +02:00

docs: AGENTS.md — repo runbook for orchestrator/Codex/3+3 reviewers #43

claude referenced this pull request from a commit

2026-05-03 23:27:30 +02:00

docs(decisions): ADR 0002 — CI enforcement of canary 3+3 + hard iteration cap

claude referenced this pull request

2026-05-03 23:28:10 +02:00

docs(decisions): ADR 0002 — CI enforcement of canary 3+3 + hard iteration cap #44

claude referenced this pull request from a commit

2026-05-04 00:23:31 +02:00

docs(reports): STATE_OF_PLATFORM v2 — Oracle review amendments (6 fixes)

claude added 1 commit

2026-05-04 00:23:31 +02:00

docs(reports): STATE_OF_PLATFORM v2 — Oracle review amendments (6 fixes) 039b5cd95f

Per Oracle (GPT-5.5 Pro) review on PR #42 batch 2026-05-04, applies 6
amendments to v2:

1. Model/emotional signal note compressed from ~379 chars to 274 chars
   (under ≤280 cap). Length verified via python len().
2. Owner Action Board "Needs owner now" discipline — moved CHOOSE-with-
   default items (Honcho-before-Forgejo, smoke.sh minimal viable) out of
   "Needs owner now" into "Default path unless owner objects" where they
   already lived. Eliminates redundancy + matches Oracle's bucket
   discipline (only true-must-decide-now items in top bucket).
3. Removed empty file state/reports/smoke-all-2026-05-03.txt (leftover
   from earlier broken smoke.sh --all run via tee that wrote 0 bytes).
4. Renamed "Phase 02 catalog completion (waves 4-9)" → "Phase 02 pivot
   tranche — waves 4-9 (~25 of 85 modules)". Added clarifying paragraph
   that waves 4-9 cover ~25 modules and represent pivot to platformctl
   Phase 03, not full 85-module catalog completion.
5. Replaced "independent quality voices" with Oracle's more precise
   phrasing: "diverse model-based review voices; independent in role/
   perspective, not in evidence base; runtime evidence remains mandatory
   where relevant". Honest framing: 6 LLMs sharing training lineage is
   not "independent" in the evidence-base sense.
6. Restore-test default text changed from "resumes monthly cadence;
   first run scheduled within 7 days" to "Create/schedule local restore
   rehearsal issue within 7 days (does not imply immediate RS2000
   production action)". Aligns with restore-test-as-pre-cutover-gate
   classification (amendment 14 in v2); does not imply immediate RS2000
   production action that operator hasn't authorized.

Authored as claude (per ADR 0001 + identity-isolation fix).

claude commented

2026-05-04 00:31:06 +02:00

Collaborator

Amendment iter 2 (commit 039b5cd) per Oracle review 2026-05-04. Authored as claude.

6 amendments per Oracle: Model signal note compressed (379→274 chars, ≤280 verified); Owner Action Board "Needs owner now" discipline (CHOOSE-with-default items moved to Default path); empty smoke-all txt removed; "Phase 02 catalog completion" → "Phase 02 pivot tranche — waves 4-9 (~25 of 85)"; "independent quality voices" → "diverse model-based review voices, independent in role/perspective not evidence base, runtime evidence mandatory"; restore-test default: "create/schedule local restore rehearsal issue within 7 days" (no immediate RS2000 action implied).

Ready for operator review. Per ADR 0001 hard 3-iter cap: this is iter 2 of 3. If canary re-fired and finds new issues, iter 3 forces terminal action choice per ADR 0002 Rule 2.

**Amendment iter 2 (commit 039b5cd)** per Oracle review 2026-05-04. Authored as `claude`. 6 amendments per Oracle: Model signal note compressed (379→274 chars, ≤280 verified); Owner Action Board "Needs owner now" discipline (CHOOSE-with-default items moved to Default path); empty smoke-all txt removed; "Phase 02 catalog completion" → "Phase 02 pivot tranche — waves 4-9 (~25 of 85)"; "independent quality voices" → "diverse model-based review voices, independent in role/perspective not evidence base, runtime evidence mandatory"; restore-test default: "create/schedule local restore rehearsal issue within 7 days" (no immediate RS2000 action implied). Ready for operator review. Per ADR 0001 hard 3-iter cap: this is iter 2 of 3. If canary re-fired and finds new issues, iter 3 forces terminal action choice per ADR 0002 Rule 2.

claude referenced this pull request

2026-05-04 00:31:07 +02:00

docs: AGENTS.md — repo runbook for orchestrator/Codex/3+3 reviewers #43

claude referenced this pull request

2026-05-04 00:31:07 +02:00

docs(decisions): ADR 0002 — CI enforcement of canary 3+3 + hard iteration cap #44