Skip to content

Commit 5d25da8

Browse files
rupurtrupurt
committed
planning: lay mission request bearings
• [MSN] 2 missions driving 2 epics forward • [EXC] Board idle, no stories queued or active • [HLT] 2 warnings, no structural errors detected
1 parent 923356f commit 5d25da8

10 files changed

Lines changed: 497 additions & 22 deletions

File tree

‎.keel/README.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,8 @@
1111
| [Simulation Kernel Architecture Research](bearings/VDeRKA7fo/) | laid | ✓ | ✓ | decision-ready | 3.36 | ✓ |
1212
| [TUI Compact Layout Research](bearings/VDmdk1uib/) | laid | ✓ | ✓ | decision-ready | 7.50 | ✓ |
1313
| [Collaborative Cryptographic Primitives Over Adversarial Transport](bearings/VDupml7OG/) | laid | ✓ | ✓ | decision-ready | 3.41 | ✓ |
14-
| [Mission Request Command Surface Research](bearings/VG6ggE3ud/) | exploring | ✓ | ✓ | repair citations | - | - |
15-
| [Keeper Provider Mission Request Ingress Research](bearings/VG6ggSPFR/) | exploring | ✓ | ✓ | repair citations | - | - |
14+
| [Mission Request Command Surface Research](bearings/VG6ggE3ud/) | laid | ✓ | ✓ | decision-ready | 3.46 | ✓ |
15+
| [Keeper Provider Mission Request Ingress Research](bearings/VG6ggSPFR/) | laid | ✓ | ✓ | decision-ready | 3.67 | ✓ |
1616

1717
<details>
1818
<summary>Archived Bearings</summary>
@@ -439,3 +439,7 @@
439439
|--------|--------|
440440
| [Define Keeper Trust Boundaries And Audit Checkpoints](epics/VDupml7OG/voyages/VG73OljA2/) | done |
441441

442+
### [Mission Request Command Surface](epics/VG6ggE3ud/) (draft)
443+
444+
### [Keeper Provider Mission Request Ingress](epics/VG6ggSPFR/) (draft)
445+

‎.keel/bearings/VG6ggE3ud/ASSESSMENT.md‎

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,10 @@ id: VG6ggE3ud
88

99
| Factor | Score | Rationale |
1010
|--------|-------|-----------|
11-
| Impact | 3 | Expected value delivered if successful |
12-
| Confidence | 3 | Certainty we can achieve the outcome |
13-
| Effort | 3 | Resources and time required |
14-
| Risk | 3 | Probability of negative outcomes |
11+
| Impact | 4 | A stable mission-request CLI is the composition boundary for Keeper and any external provider automation. [SRC-01][SRC-02] |
12+
| Confidence | 4 | The request envelope and command family are already framed in the existing security and mission-request research. [SRC-01] |
13+
| Effort | 3 | The main work is contract definition, validation semantics, and acknowledgement behavior, not new distributed runtime machinery. [SRC-01][SRC-02] |
14+
| Risk | 2 | The main risks are surface-shape churn and overloading the first command family, both of which are containable with a provider-neutral contract. [SRC-01][SRC-02] |
1515

1616
*Scores range from 1-5:*
1717
- 1 = Very Low
@@ -22,22 +22,24 @@ id: VG6ggE3ud
2222

2323
## Findings
2424

25-
- Key finding with canonical support [SRC-01]
25+
- A canonical mission-request CLI surface is already specified strongly enough to promote from research into strategic delivery work. [SRC-01]
26+
- Keeper and other automation need a scriptable command boundary instead of embedding provider parsing and mutation rules ad hoc. [SRC-01][SRC-02]
2627

2728
## Opportunity Cost
2829

29-
What are we not doing by pursuing this? Cite the tradeoff, for example [SRC-01].
30+
- Delaying this work keeps mission intake coupled to manual operator steps and blocks consistent provider composition in Keeper. [SRC-01][SRC-02]
3031

3132
## Dependencies
3233

33-
- Dependency or prerequisite with support [SRC-01]
34+
- The command surface should stay aligned with the provider-neutral mission request envelope already captured in the foundational bearing package. [SRC-01]
35+
- Keeper’s current CLI and runtime surface provide the execution context, but not yet the native request commands this mission is defining. [SRC-02]
3436

3537
## Alternatives Considered
3638

37-
- Alternative path with support [SRC-01]
39+
- Keep mission-request handling inside Keeper-specific provider code. This was rejected because it would make GitHub-first ingress harder to generalize and would weaken the native Keel contract. [SRC-01][SRC-02]
3840

3941
## Recommendation
4042

41-
[ ] Proceed → convert to epic [SRC-01]
43+
[x] Proceed → convert to epic [SRC-01][SRC-02]
4244
[ ] Park → revisit later [SRC-01]
4345
[ ] Decline → document learnings [SRC-01]

‎.keel/bearings/VG6ggE3ud/README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,15 @@
11
---
22
# system-managed
33
id: VG6ggE3ud
4-
status: exploring
4+
status: laid
55
created_at: 2026-04-07T05:17:38
66
# authored
77
title: Mission Request Command Surface Research
88
index: 5
99
mission: VG6d7gjkx
1010
updated_at: 2026-04-07T05:17:38
11+
laid_at: 2026-04-07T08:26:22
12+
epic: VG6ggE3ud
1113
---
1214

1315
# Mission Request Command Surface Research

‎.keel/bearings/VG6ggSPFR/ASSESSMENT.md‎

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,10 @@ id: VG6ggSPFR
88

99
| Factor | Score | Rationale |
1010
|--------|-------|-----------|
11-
| Impact | 3 | Expected value delivered if successful |
12-
| Confidence | 3 | Certainty we can achieve the outcome |
13-
| Effort | 3 | Resources and time required |
14-
| Risk | 3 | Probability of negative outcomes |
11+
| Impact | 4 | Provider ingress is the operational bridge between external requests and native Keel planning state. [SRC-01][SRC-03] |
12+
| Confidence | 4 | Keeper already owns provider routing and the GitHub-first mission-request envelope is defined. [SRC-01][SRC-03] |
13+
| Effort | 3 | The work is to normalize, validate, and acknowledge inbound requests through Keeper rather than inventing a new runtime role. [SRC-01][SRC-02][SRC-03] |
14+
| Risk | 2 | The main risk is overfitting the first provider, which is manageable by enforcing the provider-neutral request envelope. [SRC-01][SRC-03] |
1515

1616
*Scores range from 1-5:*
1717
- 1 = Very Low
@@ -22,22 +22,24 @@ id: VG6ggSPFR
2222

2323
## Findings
2424

25-
- Key finding with canonical support [SRC-01]
25+
- Keeper is the correct owner for provider polling, normalization, and acknowledgement in the Keel/Keeper boundary. [SRC-01][SRC-02]
26+
- GitHub issues are a strong first ingress provider, but the normalization path must stay provider-neutral and lower into native Keel commands. [SRC-01][SRC-03]
2627

2728
## Opportunity Cost
2829

29-
What are we not doing by pursuing this? Cite the tradeoff, for example [SRC-01].
30+
- Delaying this work leaves external mission intake informal and prevents Keeper from acting as a controlled multiplayer ingress boundary. [SRC-01][SRC-03]
3031

3132
## Dependencies
3233

33-
- Dependency or prerequisite with support [SRC-01]
34+
- The mission-request command surface needs to exist so Keeper can target a native Keel contract instead of mutating board state directly. [SRC-02][SRC-03]
35+
- The ingress path should align with Keeper’s existing architecture for provider routing and envelope handling. [SRC-01]
3436

3537
## Alternatives Considered
3638

37-
- Alternative path with support [SRC-01]
39+
- Let each provider mutate planning state directly. This was rejected because it bypasses a stable Keel contract and makes auditability and provider parity weaker. [SRC-01][SRC-03]
3840

3941
## Recommendation
4042

41-
[ ] Proceed → convert to epic [SRC-01]
43+
[x] Proceed → convert to epic [SRC-01][SRC-03]
4244
[ ] Park → revisit later [SRC-01]
4345
[ ] Decline → document learnings [SRC-01]

‎.keel/bearings/VG6ggSPFR/README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,15 @@
11
---
22
# system-managed
33
id: VG6ggSPFR
4-
status: exploring
4+
status: laid
55
created_at: 2026-04-07T05:17:39
66
# authored
77
title: Keeper Provider Mission Request Ingress Research
88
index: 6
99
mission: VG6d7m4m9
1010
updated_at: 2026-04-07T05:17:39
11+
laid_at: 2026-04-07T08:26:22
12+
epic: VG6ggSPFR
1113
---
1214

1315
# Keeper Provider Mission Request Ingress Research

‎.keel/epics/VG6ggE3ud/PRD.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# Mission Request Command Surface - Product Requirements
2+
3+
> Keel should expose a native `mission request` command family so Keeper and other
4+
programs can compose mission-request parsing, validation, drafting, application,
5+
and acknowledgement without embedding provider-specific logic in Keel core.
6+
7+
## Problem Statement
8+
9+
The current Keeper and keeper-cli surfaces are too thin to ingest formal mission
10+
requests from external providers. Without a native Keel CLI surface, each
11+
provider worker would need to reimplement normalization, validation, and
12+
application behavior, which would fracture the planning contract and weaken
13+
replayability.
14+
15+
## Goals & Objectives
16+
17+
| ID | Goal | Success Metric | Target |
18+
|----|------|----------------|--------|
19+
| GOAL-01 | Validate bearing recommendation in delivery flow | Adoption signal | Initial rollout complete |
20+
21+
## Users
22+
23+
| Persona | Description | Primary Need |
24+
|---------|-------------|--------------|
25+
| Product/Delivery Owner | Coordinates planning and execution | Reliable strategic direction |
26+
27+
## Scope
28+
29+
### In Scope
30+
31+
- [SCOPE-01] Define the canonical `keel mission request template|parse|validate|draft|apply|ack` command family.
32+
- [SCOPE-02] Define the provider-neutral mission request envelope and its stdin/stdout contract.
33+
- [SCOPE-03] Define the validation and acknowledgement semantics automation callers rely on.
34+
35+
### Out of Scope
36+
37+
- [SCOPE-90] Provider-specific polling and ingress workers in Keeper.
38+
- [SCOPE-91] Unrelated workflow or planning refactors outside the mission-request contract.
39+
40+
## Requirements
41+
42+
### Functional Requirements
43+
44+
<!-- BEGIN FUNCTIONAL_REQUIREMENTS -->
45+
| ID | Requirement | Goals | Priority | Rationale |
46+
|----|-------------|-------|----------|-----------|
47+
| FR-01 | Implement the core user workflow identified in bearing research. | GOAL-01 | must | Converts research recommendation into executable product capability. |
48+
<!-- END FUNCTIONAL_REQUIREMENTS -->
49+
50+
### Non-Functional Requirements
51+
52+
<!-- BEGIN NON_FUNCTIONAL_REQUIREMENTS -->
53+
| ID | Requirement | Goals | Priority | Rationale |
54+
|----|-------------|-------|----------|-----------|
55+
| NFR-01 | Ensure deterministic behavior and operational visibility for the delivered workflow. | GOAL-01 | must | Keeps delivery safe and auditable during rollout. |
56+
<!-- END NON_FUNCTIONAL_REQUIREMENTS -->
57+
58+
## Verification Strategy
59+
60+
- Prove functional behavior through story-level verification evidence mapped to voyage requirements.
61+
- Validate non-functional posture with operational checks and documented artifacts.
62+
63+
## Assumptions
64+
65+
| Assumption | Impact if Wrong | Validation |
66+
|------------|-----------------|------------|
67+
| Bearing findings reflect current user needs | Scope may need re-planning | Re-check feedback during first voyage |
68+
69+
## Open Questions & Risks
70+
71+
| Question/Risk | Owner | Status |
72+
|---------------|-------|--------|
73+
| How should `keel mission request apply` behave when a request is exploratory rather than implementation-ready? | Planner | Open |
74+
| Which fields should be required on stdin versus derivable from provider metadata? | Planner | Open |
75+
| Should `ack` emit only provider-facing content or also a canonical audit record payload? | Planner | Open |
76+
77+
## Success Criteria
78+
79+
<!-- BEGIN SUCCESS_CRITERIA -->
80+
- [ ] Define the canonical `keel mission request template|parse|validate|draft|apply|ack` command family.
81+
- [ ] Define a provider-neutral request envelope that can be piped over stdin/stdout.
82+
- [ ] Define the minimum required inputs for GitHub issue activation and later provider expansion.
83+
- [ ] Define how Keeper and non-Keeper automation invoke the same Keel surface.
84+
<!-- END SUCCESS_CRITERIA -->
85+
86+
## Research Analysis
87+
88+
*From bearing assessment:*
89+
90+
## Findings
91+
92+
93+
- A canonical mission-request CLI surface is already specified strongly enough to promote from research into strategic delivery work. [SRC-01]
94+
- Keeper and other automation need a scriptable command boundary instead of embedding provider parsing and mutation rules ad hoc. [SRC-01][SRC-02]
95+
96+
97+
## Opportunity Cost
98+
99+
100+
- Delaying this work keeps mission intake coupled to manual operator steps and blocks consistent provider composition in Keeper. [SRC-01][SRC-02]
101+
102+
103+
## Dependencies
104+
105+
106+
- The command surface should stay aligned with the provider-neutral mission request envelope already captured in the foundational bearing package. [SRC-01]
107+
- Keeper’s current CLI and runtime surface provide the execution context, but not yet the native request commands this mission is defining. [SRC-02]
108+
109+
110+
## Alternatives Considered
111+
112+
113+
- Keep mission-request handling inside Keeper-specific provider code. This was rejected because it would make GitHub-first ingress harder to generalize and would weaken the native Keel contract. [SRC-01][SRC-02]
114+
115+
## Research Provenance
116+
117+
*Source records from bearing evidence:*
118+
119+
| ID | Class | Provenance | Location | Observed / Published | Retrieved | Authority | Freshness | Notes |
120+
|----|-------|------------|----------|----------------------|-----------|-----------|-----------|-------|
121+
| SRC-01 | manual | workspace | /home/alex/workspace/spoke-sh/keel/.keel/bearings/VDupml7OG/MISSION_REQUESTS.md | 2026-04-07 | 2026-04-07 | high | high | Existing research package already defines the candidate command family and normalized mission request envelope. |
122+
| SRC-02 | manual | workspace | /home/alex/workspace/spoke-sh/spoke/crates/keeper-cli/src/main.rs | 2026-04-07 | 2026-04-07 | medium | high | Current keeper-cli exposes only missions, start, and status commands, which leaves mission-request composition unimplemented. |
123+
124+
---
125+
126+
*This PRD was seeded from bearing `VG6ggE3ud`. See `bearings/VG6ggE3ud/` for original research.*

‎.keel/epics/VG6ggE3ud/README.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
# system-managed
3+
id: VG6ggE3ud
4+
created_at: 2026-04-07T08:26:22
5+
# authored
6+
title: Mission Request Command Surface
7+
mission: VG6d7gjkx
8+
---
9+
10+
# Mission Request Command Surface
11+
12+
> Define the native `keel mission request` command surface that Keeper and
13+
> other automation can compose without embedding provider-specific parsing or
14+
> planning mutation logic.
15+
16+
## Documents
17+
18+
| Document | Description |
19+
|----------|-------------|
20+
| [PRD.md](PRD.md) | Product requirements and success criteria |
21+
| `PRESS_RELEASE.md` (optional) | Working-backwards artifact for large user-facing launches; usually skip for incremental/refactor/architecture-only work |
22+
23+
## Voyages
24+
25+
<!-- BEGIN GENERATED -->
26+
**Progress:** 0/0 voyages complete, 0/0 stories done
27+
| Voyage | Status | Stories |
28+
|--------|--------|---------|
29+
<!-- END GENERATED -->

0 commit comments

Comments
 (0)