docs(architecture): phase 1 bootstrap — specs, 9 ADRs, OQ tracker

Architecture documentation structure per sdd_process phase 1:

- README index (doc table, ADR table, lifecycle), overview with crate
  map, dependency rules, and security invariants
- Component specs: storage, transport, http, ssh, alkgitd (all draft)
- ADRs 001-009: crate decomposition, front-door-blind core, V2-first
  protocol, pack pipeline (data::output generation / data::input
  ingestion), session substrate types, http adapter composition
  (proposed, OQ-01), ACL-before-advertisement, registry-resolved repo
  identity, bounded-resources budgets
- open-questions.md: OQ-01..08 with two deferred(scope), one
  deferred(unclear), door-type definitions, blocker tracker tasks in
  tasks/architecture/
- v1 ssh-door decision recorded: russh terminates wire SSH in alkgitd;
  alkcall channels stay the internal substrate (OQ-03 partially
  resolved)

Two review rounds (fresh-context subagent): 4 critical + 17 warnings
fixed in round one; zero critical + 4 warnings + 5 suggestions fixed in
round two. All ADR/OQ cross-references verified resolving.
This commit is contained in:
glm-5.3-flash committed 2026-09-21 03:55:33 +00:00
1 parent 70815e22a0
commit 8f73da5d12
21 files changed
+1669

No files matched your search

+35
View File
@@ -0,0 +1,35 @@
---
id: architecture/oq-03-embedder
name: OQ-03 unblock — downstream embedder use case arrives
status: pending
depends_on: []
scope: narrow
risk: trivial
impact: component
level: research
tags: [external-trigger, deferred-oq]
---
## Description
Tracker for OQ-03 (`deferred(scope)`): downstream embedding surface. Not
actionable work — tracks whether a concrete downstream embedder use case
has arrived (a real app or harness wanting to embed core + transport, or
ask for a russh-flavored ssh adapter). On trigger: mark completed, OQ-03
transitions to `open`.
## Work
None by default.
## Verification
- OQ-03 status matches `docs/architecture/open-questions.md`.
## Out of scope
- Designing the embedding seam.
## Summary
> Filled on completion.
+42
View File
@@ -0,0 +1,42 @@
---
id: architecture/oq-04-receive-pack
name: OQ-04 unblock — receive-pack walkthrough/POC arrives
status: pending
depends_on: []
scope: narrow
risk: trivial
impact: component
level: research
tags: [external-trigger, deferred-oq]
---
## Description
Tracker for OQ-04 (`deferred(unclear)`): receive-pack (push) design
validation. This task is not actionable work — it tracks whether the
investigation has arrived. When a receive-pack design walkthrough (against
real `git push` captures) or a validation push POC is scheduled, mark this
completed; OQ-04 transitions to `open`. The investigation scope is in
`docs/architecture/open-questions.md` (OQ-04): capability advertisement
set, request-line parsing + shallow policy, thin-pack acceptance, CAS
timing, status report, http framing.
## Work
None by default. On trigger: set OQ-04 to `open` in
`docs/architecture/open-questions.md` and spawn the focused session that
works through the push state machine.
## Verification
- OQ-04 status matches this task's state in
`docs/architecture/open-questions.md`.
## Out of scope
- Actually designing/implementing receive-pack (that is the follow-on
session's work).
## Summary
> Filled on completion.
+34
View File
@@ -0,0 +1,34 @@
---
id: architecture/oq-05-sha256
name: OQ-05 unblock — sha256 ecosystem need arrives
status: pending
depends_on: []
scope: narrow
risk: trivial
impact: component
level: research
tags: [external-trigger, deferred-oq]
---
## Description
Tracker for OQ-05 (`deferred(scope)`): sha256 support policy. Not
actionable work — tracks whether ecosystem need arrives (a real
client/repo requiring sha256, or upstream gix sha256 maturity worth
testing). On trigger: mark completed, OQ-05 transitions to `open`.
## Work
None by default.
## Verification
- OQ-05 status matches `docs/architecture/open-questions.md`.
## Out of scope
- sha256 implementation.
## Summary
> Filled on completion.
@@ -0,0 +1,37 @@
---
id: architecture/oq-06-metadata-backing
name: OQ-06 unblock — metadata-scale requirements arrive
status: pending
depends_on: []
scope: narrow
risk: trivial
impact: component
level: research
tags: [external-trigger, deferred-oq]
---
## Description
Tracker for OQ-06 (`deferred(scope)`): registry/metadata backing store.
This task is not actionable work — it tracks whether the blocking
condition has arrived: concrete metadata-scale requirements (repo count,
metadata fields beyond id/root/visibility/ACL scope, alkcall-hub
integration scope). When they exist, mark completed; OQ-06 transitions to
`open`.
## Work
None by default. On trigger: set OQ-06 to `open` and schedule the backing
decision session.
## Verification
- OQ-06 status matches `docs/architecture/open-questions.md`.
## Out of scope
- Choosing the backing store.
## Summary
> Filled on completion.