pdurlej/platform

Fork 0

Add Vistula Forgejo-native flow reporting v0 #532

Merged

pdurlej merged 1 commit from codex/vistula-v0-forgejo-flow into main

2026-05-28 01:19:49 +02:00

codex commented

2026-05-28 01:04:27 +02:00

Collaborator

Canary status: missing — full canary not run in this local session; rely on Forgejo required checks and reviewer judgment before merge.

Summary

This PR adds Vistula v0: a Forgejo-native flow-control layer for agentic work across platform, patchwarden, and iskra-openclaw.

Vistula turns voice-note-driven work and agent execution into structured, measurable delivery flow using Forgejo artifacts instead of introducing a new service or database.

What changed

Added Vistula SpecKit and project history under docs/vistula/.
Added Vistula JSON schemas under schema/.
Added structured comment parser/renderer for vistula.*.v0 comments.
Added CLI:
- platformctl vistula comments validate
- platformctl vistula comments render
- platformctl vistula report
- platformctl vistula export forgejo
- platformctl vistula plan-bootstrap
- platformctl vistula apply-labels
Added read-only Forgejo export collector.
Added offline report engine for flow labels, PR links, merge ratio, missing labels, dependencies, top blockers, and operator actions.
Added repository label bootstrap with --dry-run default and --yes required for live repo-label creation.
Added tests and sanitized fixtures.

Key decisions

Forgejo Projects are non-canonical.
Canonical v0 state is Forgejo issues, PRs, labels, structured comments, dependencies, and merge metadata.
No Postgres index in v0.
No long-running Vistula service in v0.
No webhooks in v0.
No issue mutation or issue comment writer in this PR.
Patchwarden remains the PR safety/automerge layer.
Vistula owns flow state/reporting.
Hermes Upstream owns refinement/PRD.
Iskra owns readiness/value review and possible merge orchestration.
Raw voice transcripts are not stored by default.

Validation

uv run pytest platformctl/tests/test_vistula_comments.py platformctl/tests/test_vistula_report.py platformctl/tests/test_vistula_forgejo_export.py platformctl/tests/test_vistula_labels.py — pass, 49 passed.
uv run python -m platformctl.cli validate all --json — pass, exit code 0.
Live Forgejo export/report was run against platform, patchwarden, and iskra-openclaw.
Label bootstrap dry-run was run: 57 planned repo labels per repo, 171 total planned, no writes.
Operator-approved live label bootstrap was run: 57 repository labels created in each repo, 171 total created, no issue/comment mutation.
Post-bootstrap export confirmed all three repos expose 57 Vistula labels each.

Dogfooding plan

After this PR:

Dogfood 5–10 real flows manually or semi-manually.
Use Vistula reports to inspect:
- ready/refining/blocked issues
- linked/unlinked PRs
- manual vs auto merge ratio
- missing labels
- dependency/top blocker gaps
Do not add issue/comment writers until real flows prove the exact repeated mutations.

Non-goals

No Postgres index yet.
No webhook receiver.
No service runtime.
No Forgejo Projects sync.
No issue-label mutation.
No issue-comment writer.
No Hermes automation.
No dependency writer.
No auto-merge implementation.

Spec sources read

docs/vistula/
schema/vistula.*.schema.json
control-plane/platformctl/vistula/
control-plane/platformctl/cli.py
control-plane/platformctl/tests/fixtures/vistula/
runbooks/vistula.md

Canary status: missing — full canary not run in this local session; rely on Forgejo required checks and reviewer judgment before merge. ## Summary This PR adds Vistula v0: a Forgejo-native flow-control layer for agentic work across `platform`, `patchwarden`, and `iskra-openclaw`. Vistula turns voice-note-driven work and agent execution into structured, measurable delivery flow using Forgejo artifacts instead of introducing a new service or database. ## What changed - Added Vistula SpecKit and project history under `docs/vistula/`. - Added Vistula JSON schemas under `schema/`. - Added structured comment parser/renderer for `vistula.*.v0` comments. - Added CLI: - `platformctl vistula comments validate` - `platformctl vistula comments render` - `platformctl vistula report` - `platformctl vistula export forgejo` - `platformctl vistula plan-bootstrap` - `platformctl vistula apply-labels` - Added read-only Forgejo export collector. - Added offline report engine for flow labels, PR links, merge ratio, missing labels, dependencies, top blockers, and operator actions. - Added repository label bootstrap with `--dry-run` default and `--yes` required for live repo-label creation. - Added tests and sanitized fixtures. ## Key decisions - Forgejo Projects are non-canonical. - Canonical v0 state is Forgejo issues, PRs, labels, structured comments, dependencies, and merge metadata. - No Postgres index in v0. - No long-running Vistula service in v0. - No webhooks in v0. - No issue mutation or issue comment writer in this PR. - Patchwarden remains the PR safety/automerge layer. - Vistula owns flow state/reporting. - Hermes Upstream owns refinement/PRD. - Iskra owns readiness/value review and possible merge orchestration. - Raw voice transcripts are not stored by default. ## Validation - `uv run pytest platformctl/tests/test_vistula_comments.py platformctl/tests/test_vistula_report.py platformctl/tests/test_vistula_forgejo_export.py platformctl/tests/test_vistula_labels.py` — pass, `49 passed`. - `uv run python -m platformctl.cli validate all --json` — pass, exit code 0. - Live Forgejo export/report was run against `platform`, `patchwarden`, and `iskra-openclaw`. - Label bootstrap dry-run was run: 57 planned repo labels per repo, 171 total planned, no writes. - Operator-approved live label bootstrap was run: 57 repository labels created in each repo, 171 total created, no issue/comment mutation. - Post-bootstrap export confirmed all three repos expose 57 Vistula labels each. ## Dogfooding plan After this PR: 1. Dogfood 5–10 real flows manually or semi-manually. 2. Use Vistula reports to inspect: - ready/refining/blocked issues - linked/unlinked PRs - manual vs auto merge ratio - missing labels - dependency/top blocker gaps 3. Do not add issue/comment writers until real flows prove the exact repeated mutations. ## Non-goals - No Postgres index yet. - No webhook receiver. - No service runtime. - No Forgejo Projects sync. - No issue-label mutation. - No issue-comment writer. - No Hermes automation. - No dependency writer. - No auto-merge implementation. ## Spec sources read - `docs/vistula/` - `schema/vistula.*.schema.json` - `control-plane/platformctl/vistula/` - `control-plane/platformctl/cli.py` - `control-plane/platformctl/tests/fixtures/vistula/` - `runbooks/vistula.md`

codex added 4 commits

2026-05-28 01:04:27 +02:00

decisions(0023): replace noreply email with actual gemini Forgejo identity 3e81cd022a

Operator registered cousin gemini in Forgejo on 2026-05-24 with email
p+gemini@durlej.me (following the existing claude/codex/glm/iskra/ollama
pattern of p+<cousin>@durlej.me, NOT the noreply.git.pdurlej.com pattern
I had proposed in v1 of this ADR).

Verified live 2026-05-24:
- Keychain: security find-internet-password -s git.pdurlej.com -a gemini
  returns 40-char PAT
- Forgejo: GET /api/v1/user returns {login: "gemini",
  email: "p+gemini@durlej.me", is_admin: false}
- Repo visibility: pdurlej/* org including bdmax, bohemian-sidecar,
  fallow-py and more

Plus Infisical entry created at /home-platform/forgejo_accounts/
p+gemini@durlej.me (production environment populated; dev/staging
intentionally empty, matching existing cousin pattern).

Plus Bitwarden vault entry git.pdurlej.com (gemini) with username +
password + PAT custom field, cross-machine backup pattern.

No semantic change — just bringing the ADR in sync with the actual
identity values. Tier: Trivial (docs-only string replace).

state(L3): add refreshed JOURNEY + OPEN_LOOPS dated 2026-05-23

canary-required / collect-diff (pull_request) Successful in 5s

Details

infra-docs-drift / docs-drift (pull_request) Successful in 5s

Details

patchwarden-pr-sanity / collect-diff (pull_request) Successful in 4s

Details

platformctl plan / auto-apply scope (pull_request) Successful in 21s

Details

pyfallow / Pyfallow gate (control-plane) (pull_request) Successful in 19s

Details

python-ci / Python 3.11 (pull_request) Successful in 41s

Details

base-is-main / guard (pull_request) Successful in 1s

Details

python-ci / Python 3.12 (pull_request) Successful in 41s

Details

patchwarden-pr-sanity / sanity (pull_request) Successful in 22s

Details

python-ci / Python 3.13 (pull_request) Successful in 37s

Details

workflow-lint / lint (pull_request) Successful in 5s

Details

canary-required / canary (pull_request) Successful in 14s

Details

0051c78d09

Original state/L3/JOURNEY.md and state/L3/OPEN_LOOPS.md were written
2026-04-30 during F1/F2/F3 era and went stale through 24 days of
milestone-train discovery, ADR-0017/0018/0020/0021/0022 merges, and
new subsystems (Things, Wloczykij, OpenClaw-mail, Honcho v2).

Refreshed dated copies preserve originals as historical reference and
add coverage for the May arc:

JOURNEY-2026-05-23.md (~22 KB, 205 lines):
- Preserves original 8 Feb-Apr inflections verbatim
- Adds Inflections 9-12 covering the May arc:
  - 9 (May 3-9): strategic stop + ADR 0001/0002 + Phase 02 cataloging
  - 10 (May 11-14): stacked-PR incident → ADR-0017/ADR-0018
  - 11 (May 17-20): RS2000 cutoff + ADR 0020/0021/0022 trio +
    milestone train (PR #386) + cousin-onboarding rollout +
    Things/Wloczykij/OpenClaw-mail subsystems
  - 12 (now, May 23): soak ACTIVE, W1 starting, Honcho LLM closeout,
    modularity preconditioning M08-M09
- New 4th pattern: "Crystallize the rule the moment it's costly
  enough"

OPEN_LOOPS-2026-05-23.md (~16 KB, 188 lines):
- New categories: blocked_on_precondition (soak/PAT/Vault/embedding
  gating) + meta (L3 staleness)
- Retains unresolved_active with refreshed M01-M08 items
- Adds closed_since_apr30 enumerating ~9 items that landed in May
- Reframes vps-home-platform-infra from "policy gap" to "ADR-0020
  reclassified, M01-gated cleanup"
- Each item has OL-2026-05-* id, status, blocker, owner, evidence

Contradictions spotted during refresh:
- ADR-0020/0021/0022 carry Status: Proposed in front-matter despite
  being merged on main; ADR-0017 "Accepted-on-merge" convention not
  uniformly applied. Filed as follow-up (see OPEN_LOOPS-2026-05-23).
- W-wave naming (Codex's plan) vs M-milestone numbering don't have
  1:1 mapping in any committed doc — flagged.

Sub-agent synthesis verified against actual git log
(git log --since="2026-05-01" main), STATUS_NOW (2026-05-18),
state/cutover/{rs2000-control-plane-cutoff,honcho-closeout-plan}.md,
state/roadmap/current-platform-roadmap.md (PR #386), AGENTS.md § 0
(PR #397).

Per operator choice 2026-05-23: dated artifacts running parallel to
originals; promote to undated only after operator review (this PR is
that review surface).

Tier: Trivial per ADR-0007 (docs-only, two new files, no schema/
code/runtime mutation; no concurrent file editing — Codex's active
W1 work on other paths is unaffected).

state(L3): path (b) — promote dated refresh to canonical, archive originals

pyfallow / Pyfallow gate (control-plane) (pull_request) Successful in 19s

Details

python-ci / Python 3.11 (pull_request) Successful in 40s

Details

base-is-main / guard (pull_request) Successful in 2s

Details

canary-required / collect-diff (pull_request) Successful in 5s

Details

infra-docs-drift / docs-drift (pull_request) Successful in 4s

Details

patchwarden-pr-sanity / collect-diff (pull_request) Successful in 4s

Details

platformctl plan / auto-apply scope (pull_request) Successful in 21s

Details

python-ci / Python 3.13 (pull_request) Successful in 38s

Details

workflow-lint / lint (pull_request) Successful in 4s

Details

canary-required / canary (pull_request) Successful in 13s

Details

patchwarden-pr-sanity / sanity (pull_request) Successful in 21s

Details

python-ci / Python 3.12 (pull_request) Successful in 40s

Details

009d5d0381

Per operator decision (głosówka 2026-05-24, "ty dokończ"): finalize the
L3 refresh PR with path (b) rather than path (a) running-parallel.

Result:
- state/L3/JOURNEY.md and state/L3/OPEN_LOOPS.md are now the refreshed
  2026-05-23 content (canonical names — no dated suffix cluttering
  future cousin reads).
- Original 2026-04-30 content preserved as
  state/L3/archive/2026-04-30-JOURNEY.md and
  state/L3/archive/2026-04-30-OPEN_LOOPS.md (historical chain
  explicit, no information lost).
- CONTRADICTIONS.md, ORPHANS.md, SUMMARY.md, entities.json remain
  at canonical paths — they were not refreshed in this pass (still
  reflect 2026-04-30 synthesis); next refresh can dated-then-promote
  using the same archive pattern.

Future refresh convention (informal, document if it stabilizes):
1. Write JOURNEY-YYYY-MM-DD.md and OPEN_LOOPS-YYYY-MM-DD.md as new
   dated files
2. Review (claude+codex canary, or operator alone for trivial)
3. Promote: git mv current canonical → archive/YYYY-MM-DD-* and git mv
   dated → canonical
4. Next cousin always reads state/L3/JOURNEY.md (no need to know
   which is "latest dated")

Tier per ADR-0007: Trivial (file moves only, no content edit).

Add Vistula Forgejo-native flow reporting v0

patchwarden-pr-sanity / collect-diff (pull_request) Successful in 4s

Details

python-ci / Python 3.11 (pull_request) Successful in 40s

Details

python-ci / Python 3.12 (pull_request) Successful in 42s

Details

python-ci / Python 3.13 (pull_request) Successful in 42s

Details

base-is-main / guard (pull_request) Successful in 2s

Details

canary-required / collect-diff (pull_request) Successful in 5s

Details

infra-docs-drift / docs-drift (pull_request) Successful in 4s

Details

platformctl plan / auto-apply scope (pull_request) Successful in 25s

Details

pyfallow / Pyfallow gate (control-plane) (pull_request) Successful in 21s

Details

workflow-lint / lint (pull_request) Successful in 5s

Details

canary-required / canary (pull_request) Successful in 15s

Details

patchwarden-pr-sanity / sanity (pull_request) Failing after 24s

Details

8e98203406

Adds Vistula SpecKit and project history.

Adds structured comments and schemas.

Adds comments validate/render CLI.

Adds read-only Forgejo export and offline report engine.

Adds repository label bootstrap planner/applier.

Keeps v0 artifact-first: no DB, no service, no webhooks, no issue/comment mutation.

Documents dogfooding plan before further automation.

codex referenced this pull request

2026-05-28 01:13:28 +02:00

chore(w9): milestone archaeology packet for stale open issues #535

codex referenced this pull request

2026-05-28 01:13:28 +02:00

chore(vistula): dogfood labels on 5-10 pilot issues after v0 merge #537

codex force-pushed codex/vistula-v0-forgejo-flow from 8e98203406

patchwarden-pr-sanity / collect-diff (pull_request) Successful in 4s

Details

python-ci / Python 3.11 (pull_request) Successful in 40s

Details

python-ci / Python 3.12 (pull_request) Successful in 42s