Skip to content

Commit c958e2c

Browse files
rupurtrupurt
committed
planning: specify mission request ingress replay
• [MSN] 2 missions driving 2 epics forward • [EXC] Board idle, no stories queued or active • [HLT] 2 warnings, no structural errors detected
1 parent 6f41eec commit c958e2c

12 files changed

Lines changed: 140 additions & 10 deletions

File tree

‎.keel/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -449,5 +449,5 @@
449449

450450
| Voyage | Status |
451451
|--------|--------|
452-
| [Define Mission Request Ingress Replay And Acknowledgement](epics/VG6ggSPFR/voyages/VG7sCmWrK/) | planned |
452+
| [Define Mission Request Ingress Replay And Acknowledgement](epics/VG6ggSPFR/voyages/VG7sCmWrK/) | in-progress |
453453

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,5 +26,5 @@ mission: VG6d7m4m9
2626
**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 |
29+
| [Define Mission Request Ingress Replay And Acknowledgement](voyages/VG7sCmWrK/) | in-progress | 0/1 |
3030
<!-- END GENERATED -->

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

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# GitHub Mission Request Ingress Contract
2+
3+
## Purpose
4+
5+
Define the replayable Keeper ingress policy for formal mission requests sourced
6+
from GitHub issues.
7+
8+
## Activation Rule
9+
10+
A GitHub issue becomes a formal mission request candidate only when:
11+
12+
- the title begins with `Keel Mission Request:`
13+
- the body conforms to the canonical mission request template
14+
- Keeper can read the issue and its current revision through the configured
15+
provider credentials
16+
17+
Anything that fails these checks remains ordinary issue traffic and must not be
18+
lowered into a Keel mission request.
19+
20+
## Normalized Ingress Record
21+
22+
Every accepted GitHub candidate lowers into a canonical ingress record with:
23+
24+
- the provider-neutral mission request envelope
25+
- repository and issue identity
26+
- an explicit provider revision value
27+
- a replay identity used to distinguish new revisions from duplicate deliveries
28+
29+
## Revision Rules
30+
31+
- Keeper must treat the tuple `(provider kind, repository, issue number,
32+
provider revision)` as the canonical replay identity for the normalized
33+
request.
34+
- A provider event that resolves to the same replay identity is a duplicate
35+
delivery and must not create a second planning mutation.
36+
- An issue edit that changes the provider revision creates a new normalized
37+
revision and triggers a fresh Keel evaluation.
38+
- Re-fetching the same revision is a retry path, not a semantic change.
39+
40+
## Invocation Boundary
41+
42+
Keeper is responsible for:
43+
44+
- polling or receiving GitHub issue changes
45+
- detecting the mission request activation rule
46+
- normalizing issue content and provider metadata into the canonical request
47+
- deciding whether the current event is a new revision or a duplicate retry
48+
- invoking native `keel mission request` stages
49+
- delivering provider-facing acknowledgements
50+
51+
Keel is responsible for:
52+
53+
- the canonical request schema
54+
- validation and diagnostics
55+
- planning mutation semantics
56+
- acknowledgement payload rendering
57+
58+
## Acknowledgement Rules
59+
60+
- Acknowledgements must refer to the exact issue identity and revision that
61+
produced the current Keel outcome.
62+
- Keeper owns posting or retrying provider-facing acknowledgements.
63+
- Keel owns rendering the canonical acknowledgement payload from the validated
64+
request and planning result.
65+
- A failed acknowledgement retry must not cause Keeper to replay the planning
66+
mutation when the replay identity is unchanged.
67+
68+
## Failure Modes
69+
70+
| Failure | Classification | Response |
71+
|---------|----------------|----------|
72+
| Title/body do not satisfy activation rule | non-request traffic | ignore as ordinary issue activity |
73+
| Required mission request sections are missing | validation failure | retain issue identity and surface repairable diagnostics |
74+
| Duplicate delivery for unchanged revision | replay duplicate | reuse the prior normalized result, no new planning mutation |
75+
| Provider edit races with fetch | revision change | normalize the latest revision and re-evaluate once |
76+
| Keel rejects a normalized request | execution or validation failure | preserve diagnostics and bind them to the triggering revision |
77+
| Provider acknowledgement fails after Keel succeeds | transport failure | retry acknowledgement only, not planning mutation |

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

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,14 @@
11
---
22
# system-managed
33
id: VG7sCmWrK
4-
status: planned
4+
status: in-progress
55
epic: VG6ggSPFR
66
created_at: 2026-04-07T10:09:41
77
# authored
88
title: Define Mission Request Ingress Replay And Acknowledgement
99
index: 1
1010
updated_at: 2026-04-07T10:11:19
11+
started_at: 2026-04-07T10:16:15
1112
---
1213

1314
# Define Mission Request Ingress Replay And Acknowledgement
@@ -30,5 +31,5 @@ updated_at: 2026-04-07T10:11:19
3031

3132
| Title | Type | Status |
3233
|-------|------|--------|
33-
| [Specify GitHub Request Revision And Acknowledgement Rules](../../../../stories/VG7sFBnRR/README.md) | feat | backlog |
34+
| [Specify GitHub Request Revision And Acknowledgement Rules](../../../../stories/VG7sFBnRR/README.md) | feat | needs-human-verification |
3435
<!-- END GENERATED -->

‎.keel/stories/VG7sFBnRR/EVIDENCE/ac-1.log‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
GitHub ingress activation evidence
2+
3+
- Authored `.keel/epics/VG6ggSPFR/voyages/VG7sCmWrK/GITHUB_INGRESS_CONTRACT.md`
4+
- Defined GitHub activation preconditions and the normalized ingress record
5+
- Updated protocol and public foundation docs to preserve the same ingress boundary

‎.keel/stories/VG7sFBnRR/EVIDENCE/ac-2.log‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
Ingress replay evidence
2+
3+
- Defined replay identity using provider kind, source identity, and revision
4+
- Specified duplicate-delivery, retry, and edited-request behavior
5+
- Updated protocol guidance so provider retries do not replay planning mutations

‎.keel/stories/VG7sFBnRR/EVIDENCE/ac-3.log‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
Acknowledgement ownership evidence
2+
3+
- Defined Keeper-owned acknowledgement delivery and retry behavior
4+
- Defined Keel-owned acknowledgement payload rendering
5+
- Bound acknowledgements to the exact issue identity and revision that produced the outcome

‎.keel/stories/VG7sFBnRR/EVIDENCE/ac-4.log‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
Ingress determinism evidence
2+
3+
- Defined canonical replay identity and duplicate suppression
4+
- Required edited requests to produce new normalized revisions
5+
- Required acknowledgement retry failure to avoid replaying an already-applied planning mutation

‎.keel/stories/VG7sFBnRR/README.md‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,17 @@
11
---
22
# system-managed
33
id: VG7sFBnRR
4-
status: backlog
4+
status: needs-human-verification
55
created_at: 2026-04-07T10:09:50
6-
updated_at: 2026-04-07T10:11:19
6+
updated_at: 2026-04-07T10:16:58
77
# authored
88
title: Specify GitHub Request Revision And Acknowledgement Rules
99
type: feat
1010
operator-signal:
1111
scope: VG6ggSPFR/VG7sCmWrK
1212
index: 1
13+
started_at: 2026-04-07T10:16:15
14+
submitted_at: 2026-04-07T10:16:58
1315
---
1416

1517
# Specify GitHub Request Revision And Acknowledgement Rules
@@ -22,7 +24,7 @@ Keeper and native Keel mission-request commands.
2224

2325
## Acceptance Criteria
2426

25-
- [ ] [SRS-01/AC-01] GitHub activation and canonical ingress revision rules are specified for formal mission requests. <!-- verify: manual, SRS-01:start:end -->
26-
- [ ] [SRS-02/AC-01] Replay, duplicate delivery, and retry semantics are specified so repeated provider events do not create ambiguous planning mutations. <!-- verify: manual, SRS-02:start:end -->
27-
- [ ] [SRS-03/AC-01] The ownership boundary between Keeper acknowledgements and native Keel mission-request command outputs is explicitly defined. <!-- verify: manual, SRS-03:start:end -->
28-
- [ ] [SRS-NFR-01/AC-01] The ingress lifecycle preserves deterministic replay and audit semantics across revisions and retries. <!-- verify: manual, SRS-NFR-01:start:end -->
27+
- [x] [SRS-01/AC-01] GitHub activation and canonical ingress revision rules are specified for formal mission requests. <!-- verify: manual, SRS-01:start:end, proof: ac-1.log -->
28+
- [x] [SRS-02/AC-01] Replay, duplicate delivery, and retry semantics are specified so repeated provider events do not create ambiguous planning mutations. <!-- verify: manual, SRS-02:start:end, proof: ac-2.log -->
29+
- [x] [SRS-03/AC-01] The ownership boundary between Keeper acknowledgements and native Keel mission-request command outputs is explicitly defined. <!-- verify: manual, SRS-03:start:end, proof: ac-3.log -->
30+
- [x] [SRS-NFR-01/AC-01] The ingress lifecycle preserves deterministic replay and audit semantics across revisions and retries. <!-- verify: manual, SRS-NFR-01:start:end, proof: ac-4.log -->

‎.keel/stories/VG7sFBnRR/manifest.yaml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
id: VG7sFBnRR
2+
git_sha: 6f41eecde6a2f5fc900f6413a3831c6fb5586e57
3+
evidence:
4+
EVIDENCE/ac-1.log: 691ef627e4320d7746913fb9d47c24c21fbcdda602aaf2905dc9201d7a5c6041
5+
EVIDENCE/ac-2.log: f9ac78ba0bc297475b29405160f9155cd3ef84931d03023c92aa1433646ef3e1
6+
EVIDENCE/ac-3.log: a607f2b2f366caac2cd98c76f2ae6835371f503b3dc75fdb1f2d27c0e3ce4968
7+
EVIDENCE/ac-4.log: 68699546b437e2e605b09519c2e88e307d75b4634ec07c08bce267c1d78dcb45

0 commit comments

Comments
 (0)