Skip to content

Commit b1eb857

Browse files
rupurtrupurt
committed
planning: decompose mission request epics
• [MSN] 2 missions driving 2 epics forward • [EXC] 2 stories queued, none actively executing • [HLT] 1 warnings, no structural errors detected
1 parent 5d25da8 commit b1eb857

11 files changed

Lines changed: 386 additions & 4 deletions

File tree

‎.keel/README.md‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -439,7 +439,15 @@
439439
|--------|--------|
440440
| [Define Keeper Trust Boundaries And Audit Checkpoints](epics/VDupml7OG/voyages/VG73OljA2/) | done |
441441

442-
### [Mission Request Command Surface](epics/VG6ggE3ud/) (draft)
442+
### [Mission Request Command Surface](epics/VG6ggE3ud/) (active)
443443

444-
### [Keeper Provider Mission Request Ingress](epics/VG6ggSPFR/) (draft)
444+
| Voyage | Status |
445+
|--------|--------|
446+
| [Stabilize Mission Request Command Semantics](epics/VG6ggE3ud/voyages/VG7sBGWN6/) | planned |
447+
448+
### [Keeper Provider Mission Request Ingress](epics/VG6ggSPFR/) (active)
449+
450+
| Voyage | Status |
451+
|--------|--------|
452+
| [Define Mission Request Ingress Replay And Acknowledgement](epics/VG6ggSPFR/voyages/VG7sCmWrK/) | planned |
445453

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,8 @@ mission: VG6d7gjkx
2323
## Voyages
2424

2525
<!-- BEGIN GENERATED -->
26-
**Progress:** 0/0 voyages complete, 0/0 stories done
26+
**Progress:** 0/1 voyages complete, 0/1 stories done
2727
| Voyage | Status | Stories |
2828
|--------|--------|---------|
29+
| [Stabilize Mission Request Command Semantics](voyages/VG7sBGWN6/) | planned | 0/1 |
2930
<!-- END GENERATED -->

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

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
# system-managed
3+
id: VG7sBGWN6
4+
status: planned
5+
epic: VG6ggE3ud
6+
created_at: 2026-04-07T10:09:35
7+
# authored
8+
title: Stabilize Mission Request Command Semantics
9+
index: 1
10+
updated_at: 2026-04-07T10:11:18
11+
---
12+
13+
# Stabilize Mission Request Command Semantics
14+
15+
> Stabilize the mission request command contract for automation callers
16+
17+
## Documents
18+
19+
<!-- BEGIN DOCUMENTS -->
20+
| Document | Description |
21+
|----------|-------------|
22+
| [SRS.md](SRS.md) | Requirements and verification criteria |
23+
| [SDD.md](SDD.md) | Architecture and implementation details |
24+
<!-- END DOCUMENTS -->
25+
26+
## Stories
27+
28+
<!-- BEGIN GENERATED -->
29+
**Progress:** 0/1 stories complete
30+
31+
| Title | Type | Status |
32+
|-------|------|--------|
33+
| [Specify Mission Request IO And Failure Semantics](../../../../stories/VG7sCeakR/README.md) | feat | backlog |
34+
<!-- END GENERATED -->

‎.keel/epics/VG6ggE3ud/voyages/VG7sBGWN6/SDD.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Stabilize Mission Request Command Semantics - Software Design Description
2+
3+
> Stabilize the mission request command contract for automation callers
4+
5+
**SRS:** [SRS.md](SRS.md)
6+
7+
## Overview
8+
9+
This voyage defines the machine-facing contract for the `keel mission request`
10+
command family. The design treats the request envelope as the stable interface
11+
and keeps provider transport details outside the command surface so Keeper and
12+
non-Keeper automation can invoke the same semantics.
13+
14+
## Context & Boundaries
15+
16+
### In Scope
17+
18+
- the request envelope shape
19+
- stdin/file loading behavior
20+
- validation semantics
21+
- output/result contract
22+
23+
### Out of Scope
24+
25+
- provider polling
26+
- GitHub issue revision rules
27+
- Keeper runtime scheduling
28+
29+
### External Actors
30+
31+
- Keeper workers
32+
- local automation or scripts
33+
- future provider adapters that emit canonical envelopes
34+
35+
## Dependencies
36+
37+
| Dependency | Type | Purpose | Version/API |
38+
|------------|------|---------|-------------|
39+
| Mission request envelope | Internal contract | Shared request payload across commands | CLI contract |
40+
| Keel planning commands | Internal surface | Apply validated requests into board mutations | Existing CLI |
41+
42+
## Key Decisions
43+
44+
| Decision | Choice | Rationale |
45+
|----------|--------|-----------|
46+
| Provider neutrality | Keep provider-specific transport metadata optional and non-authoritative | Prevents GitHub-first behavior from becoming the core API |
47+
| Single envelope | Use one canonical request envelope across all mission-request subcommands | Keeps piping and replay behavior stable |
48+
| Explicit result modes | Separate success, validation failure, and execution failure semantics | Lets automation decide retry, repair, or escalate behavior deterministically |
49+
50+
## Architecture
51+
52+
The command family is modeled in three layers:
53+
- input normalization: read stdin/file payloads into the canonical envelope
54+
- validation and drafting semantics: determine whether the request is structurally and operationally ready
55+
- execution surface: expose `apply` and `ack` contracts without embedding provider adapters
56+
57+
## Components
58+
59+
- Envelope parser: accepts stdin/file input and produces the canonical request model.
60+
- Validator: checks required fields, derivable fields, and readiness constraints.
61+
- Result renderer: emits stable human and machine outcomes for success and failure cases.
62+
- Apply bridge: translates validated requests into native planning mutations.
63+
64+
## Interfaces
65+
66+
- `template`: emits a canonical request scaffold.
67+
- `parse`: loads raw input and returns normalized request content.
68+
- `validate`: returns readiness plus actionable errors.
69+
- `draft`: returns a proposed planning slice without mutating the board.
70+
- `apply`: performs native Keel mutations from a valid request.
71+
- `ack`: emits canonical acknowledgement content for upstream transport owners.
72+
73+
## Data Flow
74+
75+
1. Caller submits a mission request payload.
76+
2. The parser normalizes the payload into the canonical envelope.
77+
3. Validation checks required fields, derivations, and readiness state.
78+
4. `draft` or `apply` consumes the validated envelope.
79+
5. The result renderer returns deterministic success or failure output.
80+
81+
## Error Handling
82+
83+
| Error Condition | Detection | Response | Recovery |
84+
|-----------------|-----------|----------|----------|
85+
| Missing required mission fields | Envelope validation | Return structured validation failure | Caller repairs payload and retries |
86+
| Provider-only data supplied without canonical fields | Parse/validate mismatch | Return actionable normalization error | Provider adapter supplies canonical fields or derivations |
87+
| Request is structurally valid but not execution-ready | Draft/apply readiness check | Return non-terminal validation failure | Caller uses `draft` or requests more detail |
88+
| Native mutation fails after validation | Apply execution path | Return execution failure separate from validation | Caller can retry or escalate without redefining the contract |

‎.keel/epics/VG6ggE3ud/voyages/VG7sBGWN6/SRS.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Stabilize Mission Request Command Semantics - SRS
2+
3+
## Summary
4+
5+
Epic: VG6ggE3ud
6+
Goal: Stabilize the mission request command contract for automation callers
7+
8+
## Scope
9+
10+
### In Scope
11+
12+
- [SCOPE-01] Define the canonical stdin/stdout request envelope for `template`, `parse`, `validate`, `draft`, `apply`, and `ack`.
13+
- [SCOPE-02] Define deterministic machine-facing success, validation-failure, and execution-failure semantics for the command family.
14+
- [SCOPE-03] Define the minimum provider metadata and mission fields automation callers must supply or can derive.
15+
16+
### Out of Scope
17+
18+
- [SCOPE-90] Keeper-side polling or provider webhook execution.
19+
- [SCOPE-91] GitHub-specific revision tracking and acknowledgement policy.
20+
21+
## Functional Requirements
22+
23+
<!-- BEGIN FUNCTIONAL_REQUIREMENTS -->
24+
| ID | Requirement | Scope | Source | Verification |
25+
|----|-------------|-------|--------|--------------|
26+
| SRS-01 | `keel mission request parse` and `validate` must consume a canonical mission request envelope that can be passed over stdin or loaded from a file without provider-specific fields becoming required. | SCOPE-01 | FR-01 | manual |
27+
| SRS-02 | The command family must define stable machine-facing results for success, validation failure, and command failure, including which conditions are recoverable by the caller. | SCOPE-02 | FR-01 | manual |
28+
| SRS-03 | The contract must define which fields are required from callers, which can be derived from provider metadata, and which are optional hints for downstream planning behavior. | SCOPE-03 | FR-01 | manual |
29+
<!-- END FUNCTIONAL_REQUIREMENTS -->
30+
31+
## Non-Functional Requirements
32+
33+
<!-- BEGIN NON_FUNCTIONAL_REQUIREMENTS -->
34+
| ID | Requirement | Scope | Source | Verification |
35+
|----|-------------|-------|--------|--------------|
36+
| SRS-NFR-01 | The command contract must be deterministic and replayable so the same mission request payload produces the same semantic result across automation callers. | SCOPE-02 | NFR-01 | manual |
37+
<!-- END NON_FUNCTIONAL_REQUIREMENTS -->

‎.keel/epics/VG6ggSPFR/README.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,8 @@ mission: VG6d7m4m9
2323
## Voyages
2424

2525
<!-- BEGIN GENERATED -->
26-
**Progress:** 0/0 voyages complete, 0/0 stories done
26+
**Progress:** 0/1 voyages complete, 0/1 stories done
2727
| Voyage | Status | Stories |
2828
|--------|--------|---------|
29+
| [Define Mission Request Ingress Replay And Acknowledgement](voyages/VG7sCmWrK/) | planned | 0/1 |
2930
<!-- END GENERATED -->

‎.keel/epics/VG6ggSPFR/voyages/VG7sCmWrK/README.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
# system-managed
3+
id: VG7sCmWrK
4+
status: planned
5+
epic: VG6ggSPFR
6+
created_at: 2026-04-07T10:09:41
7+
# authored
8+
title: Define Mission Request Ingress Replay And Acknowledgement
9+
index: 1
10+
updated_at: 2026-04-07T10:11:19
11+
---
12+
13+
# Define Mission Request Ingress Replay And Acknowledgement
14+
15+
> Define Keeper replayable ingress and acknowledgement behavior for formal mission requests
16+
17+
## Documents
18+
19+
<!-- BEGIN DOCUMENTS -->
20+
| Document | Description |
21+
|----------|-------------|
22+
| [SRS.md](SRS.md) | Requirements and verification criteria |
23+
| [SDD.md](SDD.md) | Architecture and implementation details |
24+
<!-- END DOCUMENTS -->
25+
26+
## Stories
27+
28+
<!-- BEGIN GENERATED -->
29+
**Progress:** 0/1 stories complete
30+
31+
| Title | Type | Status |
32+
|-------|------|--------|
33+
| [Specify GitHub Request Revision And Acknowledgement Rules](../../../../stories/VG7sFBnRR/README.md) | feat | backlog |
34+
<!-- END GENERATED -->

‎.keel/epics/VG6ggSPFR/voyages/VG7sCmWrK/SDD.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# Define Mission Request Ingress Replay And Acknowledgement - Software Design Description
2+
3+
> Define Keeper replayable ingress and acknowledgement behavior for formal mission requests
4+
5+
**SRS:** [SRS.md](SRS.md)
6+
7+
## Overview
8+
9+
This voyage defines Keeper’s first provider-ingress lifecycle for formal mission
10+
requests. The design makes GitHub issue activation the first provider path while
11+
keeping the normalized ingress model replayable and cleanly separated from the
12+
native Keel command surface.
13+
14+
## Context & Boundaries
15+
16+
### In Scope
17+
18+
- GitHub issue activation detection
19+
- normalized ingress record and revision behavior
20+
- retry and acknowledgement ownership boundaries
21+
22+
### Out of Scope
23+
24+
- non-GitHub providers
25+
- cryptographic transport hardening
26+
- direct mutation of planning state by provider adapters
27+
28+
### External Actors
29+
30+
- GitHub issues as provider artifacts
31+
- Keeper ingress worker
32+
- native `keel mission request` commands
33+
34+
## Dependencies
35+
36+
| Dependency | Type | Purpose | Version/API |
37+
|------------|------|---------|-------------|
38+
| GitHub issue activation format | External contract | First provider activation signal | Title/body schema |
39+
| Canonical mission request commands | Internal contract | Native Keel mutation and validation surface | CLI contract |
40+
| Keeper ingress runtime | Internal service | Polling, normalization, retry, and acknowledgement orchestration | Keeper architecture |
41+
42+
## Key Decisions
43+
44+
| Decision | Choice | Rationale |
45+
|----------|--------|-----------|
46+
| Versioned ingress records | Represent provider edits and retries as canonical revisions | Keeps replay and deduplication explicit |
47+
| Provider-owned acknowledgements | Keeper owns transport-facing comments/status updates | Preserves the Keel/Keeper split |
48+
| GitHub-first, not GitHub-only | Use GitHub issue activation as the first adapter on top of a generic ingress model | Avoids locking the model to one provider |
49+
50+
## Architecture
51+
52+
The ingress design has three layers:
53+
- provider detection: recognize formal GitHub mission request activations
54+
- normalization and revisioning: convert provider payloads into canonical request revisions
55+
- acknowledgement orchestration: decide when Keeper emits provider-facing acknowledgements versus calling native Keel commands
56+
57+
## Components
58+
59+
- Activation detector: matches the formal title prefix and required body sections.
60+
- Revision normalizer: produces canonical request revisions and deduplicates retries.
61+
- Keel command bridge: calls native mission-request commands for validation, draft, and apply behavior.
62+
- Acknowledgement renderer: prepares provider-facing acknowledgement content from canonical outcomes.
63+
64+
## Interfaces
65+
66+
- Provider input: GitHub issue title, body, metadata, and edit history.
67+
- Normalized ingress record: canonical request plus revision metadata and replay identity.
68+
- Command bridge output: success, validation failure, or execution failure from native Keel commands.
69+
- Provider acknowledgement output: comment/status payloads owned by Keeper.
70+
71+
## Data Flow
72+
73+
1. Keeper reads a GitHub issue candidate.
74+
2. Activation detection validates the formal mission request prefix and body shape.
75+
3. The normalizer emits a canonical request revision and deduplicates retries.
76+
4. Keeper invokes native mission-request commands with the canonical payload.
77+
5. Keeper renders a provider-facing acknowledgement from the canonical result.
78+
79+
## Error Handling
80+
81+
| Error Condition | Detection | Response | Recovery |
82+
|-----------------|-----------|----------|----------|
83+
| Issue title/body do not satisfy activation format | Activation detector | Ignore or mark as invalid request candidate | Provider edits request into valid form |
84+
| Provider edit changes a previously ingested request | Revision normalizer | Emit a new canonical revision | Keeper re-runs validation/draft/apply as configured |
85+
| Duplicate delivery or retry arrives | Replay identity check | Reuse the existing canonical revision outcome | No duplicate planning mutation |
86+
| Provider acknowledgement fails after Keel processing | Transport response failure | Preserve canonical command outcome and surface retryable provider error | Keeper retries acknowledgement without replaying planning mutation |

‎.keel/epics/VG6ggSPFR/voyages/VG7sCmWrK/SRS.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Define Mission Request Ingress Replay And Acknowledgement - SRS
2+
3+
## Summary
4+
5+
Epic: VG6ggSPFR
6+
Goal: Define Keeper replayable ingress and acknowledgement behavior for formal mission requests
7+
8+
## Scope
9+
10+
### In Scope
11+
12+
- [SCOPE-01] Define how Keeper detects and versions formal GitHub mission requests as canonical ingress events.
13+
- [SCOPE-02] Define how normalized request revisions, retries, and acknowledgements remain replayable.
14+
- [SCOPE-03] Define the split between provider-side acknowledgement behavior and native Keel mission-request command invocation.
15+
16+
### Out of Scope
17+
18+
- [SCOPE-90] Non-GitHub provider adapters.
19+
- [SCOPE-91] Low-level cryptographic attestation or backend audit proofs.
20+
21+
## Functional Requirements
22+
23+
<!-- BEGIN FUNCTIONAL_REQUIREMENTS -->
24+
| ID | Requirement | Scope | Source | Verification |
25+
|----|-------------|-------|--------|--------------|
26+
| SRS-01 | Keeper must define a canonical rule for recognizing an activated GitHub mission request and lowering the title/body plus provider metadata into a versioned canonical request record. | SCOPE-01 | FR-01 | manual |
27+
| SRS-02 | The ingress contract must define how edits, retries, and duplicate deliveries are represented so replay does not create ambiguous planning mutations. | SCOPE-02 | FR-01 | manual |
28+
| SRS-03 | The ingress contract must define which acknowledgement outputs belong to Keeper as provider-facing transport behavior and which belong to native Keel mission-request commands. | SCOPE-03 | FR-01 | manual |
29+
<!-- END FUNCTIONAL_REQUIREMENTS -->
30+
31+
## Non-Functional Requirements
32+
33+
<!-- BEGIN NON_FUNCTIONAL_REQUIREMENTS -->
34+
| ID | Requirement | Scope | Source | Verification |
35+
|----|-------------|-------|--------|--------------|
36+
| SRS-NFR-01 | Ingress normalization and acknowledgement behavior must remain deterministic enough to support audit, replay, and operator reasoning across repeated deliveries. | SCOPE-02 | NFR-01 | manual |
37+
<!-- END NON_FUNCTIONAL_REQUIREMENTS -->

‎.keel/stories/VG7sCeakR/README.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
# system-managed
3+
id: VG7sCeakR
4+
status: backlog
5+
created_at: 2026-04-07T10:09:41
6+
updated_at: 2026-04-07T10:11:18
7+
# authored
8+
title: Specify Mission Request IO And Failure Semantics
9+
type: feat
10+
operator-signal:
11+
scope: VG6ggE3ud/VG7sBGWN6
12+
index: 1
13+
---
14+
15+
# Specify Mission Request IO And Failure Semantics
16+
17+
## Summary
18+
19+
Author the first executable slice of the mission-request command contract by
20+
defining the canonical request envelope, caller input rules, and the stable
21+
success and failure semantics automation depends on.
22+
23+
## Acceptance Criteria
24+
25+
- [ ] [SRS-01/AC-01] Canonical request envelope fields and transport-neutral caller inputs are specified for `template`, `parse`, and `validate`. <!-- verify: manual, SRS-01:start:end -->
26+
- [ ] [SRS-02/AC-01] Stable caller-visible success, validation-failure, and execution-failure semantics are specified for the command family. <!-- verify: manual, SRS-02:start:end -->
27+
- [ ] [SRS-03/AC-01] Required, derivable, and optional mission request fields are explicitly defined for automation callers. <!-- verify: manual, SRS-03:start:end -->
28+
- [ ] [SRS-NFR-01/AC-01] The contract preserves deterministic and replayable semantics for identical request payloads. <!-- verify: manual, SRS-NFR-01:start:end -->

0 commit comments

Comments
 (0)