kayg/infraternal-v0
Archived
Watch
1
0
Fork
You've already forked infraternal-v0
 0
Code Issues 92 Pull requests Projects Releases Packages Wiki Activity Actions

Make contracts and architecture docs match settled behavior #55

Open
opened 2026-10-04 17:41:57 +00:00 by kayg · 0 comments
kayg commented 2026-10-04 17:41:57 +00:00
Owner
Copy link

Problem and evidence

Current documentation repeats superseded or stale statements:

  • docs/DESIGN.md:22-26 still depicts OIDC, Postgres and an outbound port-443 tunnel, while DECISIONS §§24 and 29 defer OIDC, settle on SQLite and describe the direct port-7443 tunnel.
  • docs/contracts.md:2477 says the generic-to-v1 failure adapter is not connected; crates/server/src/resources.rs:2095,2240,2325,2422 now call and implement it.
  • docs/contracts.md:2705 points installation idempotency at §1.3; the relevant section is §1.5.
  • crates/agent/PROVIDERS.md:75 says generic network RPC remains disabled. Current provider RPC code and contracts include negotiated list/detail/action calls, while production defaults still start through LegacyProvider. The same document says collection-time bounds are unfinished; that remains true for the legacy Engine list path, while provider-bollard has a bounded factory path. The docs need to distinguish those states.
  • docs/PLAN.md retains a long, superseded pre-approval step table in addition to the active plan.

Recommendation

Shrink docs/contracts.md to wire/security invariants as the owner decided. Correct stale status and references, accurately separate legacy-default and factory-path status, remove or relocate the superseded plan/handoff text, and make the current entry point obvious. Keep behavior requirements in code and tests; do not add a second prose requirement-to-test system.

Payoff and estimate

Reduces contradictory instructions and repeated reconstruction of current behavior. Estimate: 0.5–1 engineering day for the initial cleanup.

Priority: Now (≤1 day).

2026-10-04 owner decisions: The recommendation to add a requirements-to-tests index conflicts with the owner's decision that code and tests are the spec and contracts should contain invariants. This issue follows the owner's direction while keeping durable decision reasoning in DECISIONS.md.

Report: arch-review report
Source: arch-review 2026-10-04

## Problem and evidence Current documentation repeats superseded or stale statements: - `docs/DESIGN.md:22-26` still depicts OIDC, Postgres and an outbound port-443 tunnel, while DECISIONS §§24 and 29 defer OIDC, settle on SQLite and describe the direct port-7443 tunnel. - `docs/contracts.md:2477` says the generic-to-v1 failure adapter is not connected; `crates/server/src/resources.rs:2095,2240,2325,2422` now call and implement it. - `docs/contracts.md:2705` points installation idempotency at §1.3; the relevant section is §1.5. - `crates/agent/PROVIDERS.md:75` says generic network RPC remains disabled. Current provider RPC code and contracts include negotiated list/detail/action calls, while production defaults still start through `LegacyProvider`. The same document says collection-time bounds are unfinished; that remains true for the legacy `Engine` list path, while `provider-bollard` has a bounded factory path. The docs need to distinguish those states. - `docs/PLAN.md` retains a long, superseded pre-approval step table in addition to the active plan. ## Recommendation Shrink `docs/contracts.md` to wire/security invariants as the owner decided. Correct stale status and references, accurately separate legacy-default and factory-path status, remove or relocate the superseded plan/handoff text, and make the current entry point obvious. Keep behavior requirements in code and tests; do not add a second prose requirement-to-test system. ## Payoff and estimate Reduces contradictory instructions and repeated reconstruction of current behavior. Estimate: 0.5–1 engineering day for the initial cleanup. **Priority:** Now (≤1 day). **2026-10-04 owner decisions:** The recommendation to add a requirements-to-tests index conflicts with the owner's decision that code and tests are the spec and contracts should contain invariants. This issue follows the owner's direction while keeping durable decision reasoning in DECISIONS.md. **Report:** [arch-review report](/mnt/hdd/infraternal/jobs/arch-review/report.md) **Source: arch-review 2026-10-04**
Commenting is not possible because the repository is archived.
No Branch/Tag specified
Branches Tags
main
dev
perf-gates
provider-docker-podman
fix-networkidle
fix-apierror-panics
fix-revoke-panic
wal-race
fix-private-storage
provider-runtime
plugin-design
server-channels
scope-v01
deploy-git-fix
sec-hardening
gates-tiering
sidebar-sync
multi-tab
cli-eof
podman-flake
ssh-reattach
agent-tunnel
process-boundary
shadcn
stream-params
cli-ssh
ssh-product
container-live
flaky-tests
s1-e2e
ssh-test-isolation
cli-stream
research-lxc
container-live-agent
ui-apis
grant-shrink
deploy-o2
ui-redesign
migration-fix
cli
stream
No results found.
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
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
kayg/infraternal-v0#55
No description provided.