Renames the written-usage rule into practice across the contract surface:
docs/ (architecture, research, plans, sdd), tasks/ (all 43 task files,
taskgraph validate passes), AGENTS.md, README.md, CHANGELOG.md, and the
.opencode/agents/ prompts. Every replacement is a sense-preserving
rewrite (colons, semicolons, commas, parentheses, sentence splits, varied),
never a mechanical swap; no spaced hyphens were substituted. Enum fields,
frontmatter, tables, wire data, and cited identifiers survive verbatim;
en dashes inside numeric ranges keep their meaning.
Verification: taskgraph validate (43 tasks), repo grep clean (single
exempt hit: the verification command's own search pattern in AGENTS.md),
cargo test, clippy --all-targets -D warnings, fmt --check, doc all green.
- ADR-005 decision 3 amended (the gap is closed upstream: alkvault
0.2.0's Zeroizing<String> return on every path incl. the error one;
the adapter wrap dropped — the double wrap would be dead posture);
the Negative consequence amended; the vault-surface note updated.
- mapping.md: the forwarded-tcpip row rides the gate shape (typed
call-plane miss, residual race re-scoped); derivation-contract
rule 5 amended (the PTY flattening constraint retired, alktty
0.8.2 — no contract change); the exit_signal row + OQ anchors
updated.
- open-questions.md: OQ-07 + OQ-10 amended with the upstream
closures; the two closed watch items struck with pointers.
- client.md: the OQ-07 anchor updated.
- OQ-10 is not resolved: the mapping-contract derivation details (name
table, core-dumped disposition, −1 disposition) are working
dispositions on mapping.md's exit rows until formalized there / as an
ADR-006 amendment. The 1a40bfb commit prematurely closed them and left
ADR-006's reference (OQ-10 open) stale.
- Premise correction integrated into the seed, not argued after the
fact; the portable-pty 0.9.0 source now cited as verified
(From<std::process::ExitStatus> maps signal-terminated → code 1 +
locale-dependent strsignal string; the number is unrecoverable).
- mapping.md: exit_signal row and the Open Questions entry updated to
open OQ-10 with the working-draft framing.
Verification: cargo test (2/2 targets ok), cargo clippy --all-targets -- -D warnings, cargo fmt --check (docs-only change)
- OQ-10 resolved: alkssh derives SSH exit-signal from the alktty exit
chunk's negative code (−N = signal N, pipe path) server-side; −1
(alktty's could-not-determine sentinel) → exit-status(255), never a
signal claim; core_dumped never asserted in v1; no alktty wire change
- new verified backend finding recorded: portable-pty 0.9 reduces
PTY-mode signal termination to a plain exit code 1 (signal number
unrecoverable through its trait surface) — faithful exit-signal on
the PTY row is an alktty/portable-pty upstream ask, not an alkssh one
- research docs (poc-3 §D.2, pocs.md, mapping-table rows) restated
accurately instead of carrying inline correction scaffolding
Verification: cargo doc --no-deps earlier this session (docs-only change)
- OQ-10's seed overstated alktty's exit-chunk design as a 'signal-identity
gap': the negative code is the documented signal encoding (alktty ADR-004,
ported from alknet ADR-055; src/local/pipe.rs::exit_code_from — Unix
ExitStatus::signal() → -sig), a tty/pty-grounded convention
- 'alktty widens the chunk' demoted from co-equal candidate to gated
exception: it would widen ControlMessage::Exit's one-way parsed shape,
the backend-wide exit_code API, and the alknet ADR-055 lineage — requires
an alktty ADR with explicit tty/pty-grounded justification, never an
alkssh convenience ask
- OQ-10 re-scoped to the real remaining detail: −1 (wait failure vs SIGHUP)
collision, core-dumped disposition, non-Unix semantics, name derivation
- correction notes added in place: poc-3 §D.2, pocs.md, mapping-table.md
(both rows); mapping.md exit_signal row updated
Verification: cargo doc --no-deps (docs-only change)
- the alkssh-level contract is the adapter-side Zeroizing wrap
(ADR-005 decision 3, POC-2-proven); the vault-side fix (Zeroizing-out
API) is filed in alkvault's own tracker — not carried, not gated on
here; ADR-005 §3 wording updated accordingly
Review untangle (three layers: local door / wire protocol / fabric):
- vanilla ssh -D binds its SOCKS5 proxy client-side (the local door —
alksocks' local-door shape) and opens plain direct-tcpip per
connection: the server needs nothing SOCKS-shaped (tunnel row +
route-1 bridge cover the leg; POC-3 correction 2 already said this)
- the family-native SOCKS5-in-channel server row served no consumer
of ours: family apps compose alksocks' local door locally over the
alkssh client's direct-tcpip DialFn — alkssh doesn't depend on
alksocks on this path
- amendments: ADR-003 §1a (feature removed), ADR-006 point 3 (SOCKS-
detect retired; session dispatch is parse-only; request-less
session channels decline), OQ-02 resolution updated with the
simplification, mapping-table.md rows annotated (research doc keeps
POC-3 stage B as the re-add feasibility record)
- ADR-006 (Accepted): direct-tcpip rides the adapter-side bridge
(alktunnels route 1; registry-side bridging rejected as door-posture
inversion; absence note resolved); git over SSH is exec-only with
subsystem declining (vanilla git's connection model is exec of
git-{upload,receive}-pack — POC-3 grammar table); session dispatch:
request-driven parse wins, request-less channels get the bounded
SOCKS-detect (first-byte 0x05, 500 ms default, assembly-configurable);
spawn-and-return recorded as a structural constraint
- OQ-02 resolved by ADR-006; README doc/ADr tables + OQ summary updated
- OQ-05 resolved: known-beforehand hosts (assembly-minted/family runners)
-> pinned, hard-decline on mismatch; unknown-beforehand hosts (rental
fleets) -> assembly-provided HostKeyPolicy the crate calls — prompt-
record, provider-metadata match, or learn-and-record. Crate default
stays fail-closed reject-unknown; crate never decides trust; storage
of learned pins is assembly detail
- auth-bridge.md: refinement postscript — no-TOFU is a no-trust-decisions-
-in-crate rule, not pin-everything; alkminer's accept-all was the fleet-
churn collapse, and the real anchor for ephemeral fleets is hub-held
key material, not host pins
- reverse-runner.md §5 rewritten with the same nuance
glm-5.3-flash