RVV Miniputt

RVV Miniputt is Region Viken Vest's repository for miniputt administration across season planning, promoted-season operations, audit/export and publication. It takes controlled team/configuration data plus calendar evidence, produces a verified tournament plan and review material, maintains the promoted operational season, and can publish a sanitized public snapshot to GitHub Pages.

The repository also owns two related public-data workflows: Påmeldte lag and the regional aktivitetskalender. These share publication machinery but are not part of the four-stage season-planning pipeline.

What the system does

1. Team and configuration intake — validate/rebuild the planner roster from reviewed registrations while keeping planning settings controlled in input.xlsx.
2. Season planning — collect calendar evidence, build candidates, verify hard rules, measure quality and export reviewable artifacts.
3. Promoted-season maintenance — preserve a stable Git-backed baseline while reconciling accepted real-world booking facts, approvals, moves, cancellations, participant changes and bounded repairs.
4. Public supporting views — generate registered-team and activity-calendar views from their own controlled inputs.
5. Publication — build a privacy-checked static bundle and publish an explicitly approved snapshot to GitHub Pages.

Python code is authoritative for facts, hard constraints, verification, persistence, export and publication safety. The active agent may choose among validated actions and soft trade-offs. Humans remain responsible for credentials/MFA, explicit policy exceptions and public publication/rollback approval.

Inputs

Season planning

Input	Role
input.xlsx	Canonical controlled planning workbook.
Reviewed registration export	Optional CSV/XLSX used to rebuild only Lag through the controlled import path.
External club/hall calendars	Availability evidence collected in Stage 2.
Browser/session credentials when genuinely required	Runtime recovery input only; never planner data/public output.

See docs/rvv-miniputt-input-formats.md.

Other public workflows

Input	Role
Årshjul for aktiviteter.xlsx	Regional activity-calendar source.
Reviewed team export	Public Påmeldte lag source.

Season lifecycle

reviewed registrations + controlled settings
                  │
                  ▼
              input.xlsx
                  │
                  ▼
Stage 1 config → Stage 2 evidence → Stage 3 plan/search → verify → Stage 4 export
                                                               │
                                                               ▼
                                                  explicit season promote
                                                               │
                                                               ▼
                                                canonical season state
                                                               │
                         approvals / moves / bounded replan / diff / apply
                                                               │
                                                               ▼
                                                    season export + audit
                                                               │
                                                               ▼
                                                     explicit publication
                                                               │
                                                               ▼
                                                        GitHub Pages

Before promotion, .pipeline/ is transient run state. After promotion, season/<season>/schedule.json and season/<season>/decisions.json are the machine-readable operational truth. GitHub Pages is the official published view, not the planning database.

Main outputs

A Stage 4/canonical export writes review artifacts under export/, including the season-plan HTML/report, optional manual follow-up view, Excel/CSV/iCal, Spond workbooks and per-club review packets. The exact output_files map in the Stage 4 checkpoint is authoritative for what a run produced.

Generated files are derived data. Correct source/config/code/canonical state and regenerate rather than permanently patching generated output.

Publication builds a separate allowlisted public bundle. Spond exports, review packets, validation metadata and unknown/private files are not public by default.

Working state

Path	Meaning
.pipeline/	Transient checkpoints, cache, manifest, logs and run decisions.
season/<season>/	Canonical promoted schedule plus approval/lock workflow state.
export/	Generated review/export bundles with lifecycle metadata.
gh-pages branch	Published static snapshots.

Session handover

Run make handover (optionally ARGS='--issue N --json') for a bounded, read-only view of Git, CI, the real public revision and current canonical lifecycle. It never publishes or changes the season. Fresh agents should read the shared handover procedure and recheck the live GitHub issue/PR rather than treating old chat summaries as current state. Missing evidence is reported as REVIEW_REQUIRED.

Normal operator workflow

The normal interface is an agent harness, but all harnesses use the same repository-owned instructions and command procedures:

AGENTS.md
  ↓
.agents/skills/rvv/SKILL.md
  ↓
.agents/commands/rvv-miniputt/<command>.md
  ↓
scripts/rvv-miniputt ...

Claude, Codex, ChatGPT, Pi and future harnesses should follow that same path. Each interactive harness exposes the same single operate entry point as a thin transport adapter that forwards the complete operator request into the shared procedure — for example .pi/prompts/rvv-miniputt-operate.md for Pi (Pi turns the filename into the /rvv-miniputt-operate command) and .claude/commands/rvv-miniputt/operate.md for Claude. Harness-specific command files may exist as thin aliases where useful, but must not implement their own scheduler loop, decision prompt, semantic-audit judge, source-validity policy or browser scraper.

For a normal season run, use the shared run procedure and reason directly over each repository DecisionContext. For promoted-season work, use the shared season procedure. For publication, use the shared publish procedure.

If browser recovery is ever needed, any browser-capable harness may perform the navigation/extraction, then return recovered evidence through recovery-inject and scrape-merge. No Pi-specific or other harness-specific scraper is required.

Interactive semantic audit is also performed by the active harness itself from operator audit-context plus selective operator audit-evidence queries; do not spawn a second model conversation inside a harness adapter.

Generation never implies publication. Publication and rollback remain explicit operator decisions.

Command/transport surface

There is one Python command transport: tournament_scheduler.cli.rvv_cli.

• scripts/rvv-miniputt is the canonical repository launcher for agent operation and selects the repository environment.
• The installed rvv-miniputt console script targets the same module.
• python3 -m tournament_scheduler.cli.rvv_cli ... is the low-level developer/test fallback.

These are transport mechanisms, not independent products. Business rules, stage sequencing, defaults and verification must not be reimplemented in shell wrappers or harness adapters.

Developer setup and verification

For a new machine or fresh checkout, the normal setup path is one command:

make bootstrap

make bootstrap is a thin Makefile adapter over scripts/bootstrap. The bootstrap script installs a pinned repo-local uv when needed, provisions Python 3.12 to match CI, creates/recreates ./venv with that interpreter, installs the locked project dependencies, installs Playwright Chromium, and runs dependency-lock/lint/quick verification. It does not depend on whatever python3 version the operating system happens to provide.

After bootstrap:

make check            # quick/PR tier: fast, hermetic unit/component tests
scripts/check full    # comprehensive hermetic lane: quick + slow + integration

Use make install only when you already have a suitable Python environment and want to reinstall project dependencies. scripts/bootstrap is also available directly as the underlying setup entrypoint.

scripts/check is the canonical verification entrypoint. The default/quick tier deliberately excludes slow and integration tests for fast feedback. Use scripts/check full (nightly/manual, not required on every PR) to also run the real canonical workbook/planner tests and the hermetic subprocess/multi-stage integration tests, including the public CLI contract suite and the multi-process Stage 3 lifecycle. harness- and live-marked tests are separate non-blocking lanes (scripts/check harness, scripts/check live) and never run implicitly. See docs/ci.md for the full lane/check matrix and marker semantics.

The Makefile is a developer/CI convenience layer, not a separate source of scheduling behavior.

Repository map

Path	Purpose
input.xlsx	Controlled season-planning workbook.
Årshjul for aktiviteter.xlsx	Activity-calendar source workbook.
tournament_scheduler/	Planning, verification, persistence, export and publication implementation.
tournament_scheduler/cli/rvv_cli.py	Canonical Python command transport.
scripts/rvv-miniputt	Canonical repository launcher.
.agents/skills/rvv/	Canonical shared agent runbook.
.agents/commands/rvv-miniputt/	Shared harness-neutral command procedures.
.claude/, .chatgpt/, .codex/	Optional thin harness aliases only.
docs/	Maintained current documentation and ADRs.

Documentation and handover

Start with docs/README.md. Current behavior belongs in current docs/code, durable rationale belongs in ADRs, and unfinished work belongs in GitHub issues. Critical Microsoft 365, GitHub, WordPress, Spond and calendar-source assets should have club-controlled ownership and backup access; see docs/ownership-and-handover.md.