sasa/wireguard-admin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add integration tests based on testcontainers

Browse Source
This commit is contained in:
sasa
2026-10-25 19:47:25 +02:00
parent 2ccd67d64c
commit f4a6540df9
24 changed files with 8693 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/EXECUTION_RECORDS.md
+111
View File
@@ -0,0 +1,111 @@
# Execution records and diagnostic workflow
This document governs development records, not application logging. It supplements
[the implementation order](IMPLEMENTATION.md) and [agent instructions](../AGENTS.md).
Product requirements, independent review and acceptance gates are unchanged.
## Record boundaries
| Record | Purpose | Contents |
| --- | --- | --- |
| [PLANS.md](../PLANS.md) | Current execution contract and resume point | Scope, acceptance checklist, task state/owner, open findings, concise closed-finding disposition, latest applicable evidence, limitations and next action. |
| `docs/diagnostics/milestone-N.md` | Investigation notebook, created only when needed | Failed attempts, hypotheses, bounded diagnostics, observations, cause and repair verification. |
| `docs/evidence/milestone-N.md` | Reproducible evidence report, created when evidence no longer fits a concise plan table | Exact commands, source/build identity, environment, outcomes, review disposition and acceptance mapping. |
| `docs/history/` | Preserved superseded records | Historical snapshots with an explicit non-current notice and a link back to the plan. |
The plan is a current snapshot, not an append-only diary. Do not copy worker
reports or full diagnostic sequences into it. Keep the detailed report in one
place and link it. Evidence and diagnostic reports never override the plan's
scope or the specification. Read only the relevant investigation/report when
resuming; reading all historical logs is not a prerequisite for implementation.
## Updating the plan
The coordinator updates a task row in place when its result, owner, next action,
review disposition or blocker changes, and before handoff. A failed command alone
does not need a plan entry unless it changes current status or invalidates evidence.
For an active failure keep one concise entry: affected behavior, known facts,
owner, next discriminating check and acceptance impact. Replace it as facts change.
Keep the milestone register, milestone status/outcome and top-level resume point
consistent in the same edit. Use the existing lifecycle states; distinguish a
repairable defect (`needs_changes`) from an unavailable prerequisite (`blocked`).
Task completion does not imply milestone acceptance. Closed findings retain their
stable ID, effect, final resolution and review/evidence reference; intermediate
repair attempts belong in diagnostics. Superseded passing runs are historical,
not additional proof for the current revision.
Aim for at most one short paragraph per task/finding and one row per evidence
scope. This is a readability target, not permission to omit acceptance criteria,
required evidence, unresolved findings or safety constraints. If detail exceeds
that target, move the detail to the appropriate linked report.
## Investigating failures
1. Classify the failure: prerequisite, fixture/transport, application behavior,
assertion, or currently unknown. Do not assume the application or fixture is
correct before checking.
2. Record a concrete hypothesis and the smallest bounded check that distinguishes
it from alternatives. Reuse the same task/finding ID across attempts.
3. Run that check and record the observation. Retry unchanged commands only for
an evidenced transient condition or deliberate repeatability check; record why.
4. After two failed repair attempts for the same symptom, reassess the cause and
task boundary before another expensive full run. Obtain a focused independent
review or reduce to a minimal reproduction when useful. This is an escalation
of investigation, not an arbitrary acceptance cutoff or a reason to ask the
user to resolve routine implementation choices.
5. Repair the cause, run focused checks, then rerun affected integration behavior.
Rebuild the container driver when its inputs changed; reuse a compatible pinned
builder/cache. Do not run the full Rust gates for every diagnostic edit. Run
them at the required completion gates and again if subsequent changes invalidate
them, following [TESTING.md](TESTING.md).
6. Review the actual repair and affected behavior independently. Consolidate the
plan to the final result, remaining uncertainty and next action.
A diagnostic entry contains: ISO timestamp with offset; task/finding ID; symptom;
hypothesis; exact safe command or reproduction reference; observed result; cause
if established; next action or closure/evidence reference. Record only useful
redacted excerpts. Raw logs, secrets, configuration payloads, private keys and
working backups must not be committed. An agent stall or usage limit needs a
brief handoff note only when it affects ownership or the next action.
## Evidence and handoff
An evidence entry identifies:
- Task/criterion and run timestamp with offset.
- Tested commit plus dirty-state description, or a reproducible fingerprint of
relevant tracked/untracked source inputs; identify the built artifact and its
source inputs when a separate container binary is used. A commit alone does
not identify a dirty working tree. Never fingerprint secret-bearing data into
a report or claim a source identity that was not captured.
- Exact command, toolchain/target and required environment or immutable image
identity, excluding secrets. Mark missing historical identity as unavailable.
- Actual outcome: exit/result counts, fixture versus Alpine versus VM scope,
cleanup outcome, limitations and which later edits invalidate the evidence.
- Independent reviewer disposition and remaining findings where applicable.
Do not manufacture missing evidence when migrating old records. Carry forward
reported results as historical evidence and state whether they were rerun.
Before accepting a milestone, verify the integrated files, close actionable
findings, run required gates on that revision and update the acceptance mapping.
A handoff consists of current task/state/owner, open issue, latest applicable
checks, environment prerequisites and one concrete next action. Link diagnostics
only if needed to avoid repeating an investigation. It must be possible to resume
from the current plan without reconstructing chronology.
## Migration and ownership
Preserve the old record in `docs/history/` before compacting existing diagnostic
history. Keep scope, acceptance criteria, stable finding IDs, final outcomes,
limitations and source links. Clearly label contradictory historical statuses as
superseded. Migrate older accepted milestones when they need maintenance; do not
rewrite their acceptance merely for uniform formatting.
The coordinator owns PLANS.md and evidence consolidation. Assign a diagnostics
file to one writer at a time, or have workers return concise entries for the
coordinator to integrate. Include these record boundaries in dispatch briefs;
workers still report actual checks and unresolved issues. New agent configuration
may not affect an existing session: supply this document explicitly at its next
authorized dispatch/handoff. Do not message other chats without user authorization.