Repository navigation
docs: make RedisForge hardening plan agent-executable - #4
Merged
Merged
Conversation
Reviewer's GuideThis documentation-only PR converts RedisForge’s two hardening notes into a bounded, dependency-aware Agent Zero execution system: one establishes the current guarantees, target invariants, guardrails, and verification contract, while the other provides executable milestones, acceptance gates, evidence requirements, and human-controlled Git/CI workflow. Sequence diagram for human-controlled review and merge workflowsequenceDiagram
participant Agent as Agent Zero
participant Branch as Local branch
participant User as Human reviewer
participant CI as GitHub CI
participant Master as master
Agent->>Branch: create local commit
Agent-->>User: evidence report and commit SHA
User->>Branch: inspect diff and correct if needed
User->>CI: push branch
CI-->>User: verification result
alt CI passes
User->>Master: merge reviewed branch
else CI fails
User->>Branch: fix and rerun verification
end
Flow diagram for daily Agent Zero task executionflowchart TD
START[Read baseline and execution queue] --> INSPECT[Inspect current master and recent history]
INSPECT --> SELECT[Select first incomplete task with satisfied dependencies]
SELECT --> IMPLEMENT[Implement one bounded task]
IMPLEMENT --> VERIFY[Run targeted and applicable repository verification]
VERIFY --> DECIDE{Verification and scope acceptable?}
DECIDE -->|No| REPORT_BLOCKED[Report failure or blocked status]
DECIDE -->|Yes| COMMIT[Create local commit]
COMMIT --> REPORT_READY[Produce evidence report for user review]
REPORT_BLOCKED --> STOP[Stop]
REPORT_READY --> STOP
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
SShogun
marked this pull request as ready for review
October 5, 2026 17:41
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've found 8 issues
Prompt for AI Agents
Please address the comments from this code review:
## Individual Comments
### Comment 1
<location path="notes/architecture-limitations.md" line_range="21" />
<code_context>
+
+| Area | Current guarantee | Current limitation |
+| --- | --- | --- |
+| Item durability | CRUD succeeds against the in-process repository and may populate RedisJSON | The authoritative fallback is memory and is recreated on startup; RedisJSON can outlive memory, so GET/List/search can diverge after restart |
+| Search | RediSearch indexes RedisJSON keys | Update invalidates the cache key, so an item can disappear from search until a later read backfills it; there is no authoritative fallback scan |
+| Idempotency | Bloom may reject a previously seen key | Bloom false positives can reject valid requests; errors fail open; there is no durable request/response receipt |
</code_context>
<issue_to_address>
**Pre-cutover items disappear or diverge**
When redisJSON contains items absent from PostgreSQL when RF-M1-P03 makes PostgreSQL authoritative, production reads switch to PostgreSQL without specifying how to handle Redis-only items or stale cache entries. Those items disappear from durable reads, or `CacheItemRepo.GetByID` continues serving entries that `List` omits.
Specify how cutover imports or discards Redis-only items and invalidates stale Redis cache entries.
Also at `notes/redisforge-principal-engineer-hardening-plan.md:266-273`, `notes/architecture-limitations.md:22`.
</issue_to_address>
### Comment 2
<location path="notes/redisforge-principal-engineer-hardening-plan.md" line_range="318" />
<code_context>
+ - item;
+ - idempotency receipt when supplied;
+ - outbox event with stable `event_id`, aggregate/item ID, item version, schema version, correlation/request ID where available.
+- Eliminate best-effort asynchronous audit emission from the create correctness path.
+
+**Acceptance**
</code_context>
<issue_to_address>
**Out-of-order updates lose search changes**
When outbox delivery reorders events that contain deltas, the projector applies version N+1 and rejects version N as stale, permanently omitting changes carried only by N from the search projection.
Require full-snapshot events or sequential processing with gap repair before the projector skips older versions.
Also at `notes/redisforge-principal-engineer-hardening-plan.md:316`, `notes/redisforge-principal-engineer-hardening-plan.md:544`.
</issue_to_address>
### Comment 3
<location path="notes/redisforge-principal-engineer-hardening-plan.md" line_range="340" />
<code_context>
+
+**Scope**
+
+- Update/delete create outbox events in the same item transaction.
+- Implement the previously documented optimistic-concurrency contract.
+- Ensure item versions advance monotonically.
</code_context>
<issue_to_address>
**Updates and deletes emit duplicate audit events**
When RF-M1-P06 is implemented by adding update/delete outbox events while retaining the existing handler emits, when RF-M1-P06 adds outbox events without removing the existing handler emits, update and delete requests publish both a best-effort `EmitAsync` event and an outbox event. They have distinct event IDs, so downstream deduplication does not prevent duplicate audit effects.
Add to RF-M1-P06 scope that update/delete must stop publishing directly through `EmitAsync` once their durable outbox events are in place.
</issue_to_address>
### Comment 4
<location path="notes/architecture-limitations.md" line_range="94" />
<code_context>
+- the selected task's prerequisite is not satisfied on the current base branch;
+- implementation requires a product/architecture decision not already made in these notes;
+- a required dependency, Docker service, credential, or local capability is unavailable;
+- a failing test appears unrelated to the task and the root cause is not safely attributable;
+- completing the task would require broadening scope beyond its stated acceptance criteria.
+
</code_context>
<issue_to_address>
**Docker checks have conflicting instructions**
When docker is unavailable for an integration check but runnable targeted checks pass, the stop rule requires halting when a Docker service is unavailable, while the verification policy permits committing when Docker prevents a CI-equivalent check. The agent cannot determine whether to stop or proceed with an unverified check.
Clarify that the Docker environment-limitation exception permits proceeding when runnable targeted checks pass, consistent with the verification policy.
Also at `notes/redisforge-principal-engineer-hardening-plan.md:77`, `notes/architecture-limitations.md:93`.
</issue_to_address>
### Comment 5
<location path="notes/redisforge-principal-engineer-hardening-plan.md" line_range="84" />
<code_context>
+A task is complete only when:
+
+- its acceptance criteria are demonstrably satisfied;
+- directly relevant tests exist and pass;
+- no known regression remains;
+- changed behavior is documented where necessary;
</code_context>
<issue_to_address>
**Documentation tasks cannot advance**
When A documentation-only task satisfies its acceptance criteria without adding tests, the global completion rule still requires directly relevant tests to exist and pass, so the agent cannot mark the task complete or advance the queue without adding irrelevant tests.
Make the test requirement conditional on the task and define applicable verification for documentation-only tasks.
Also at `notes/redisforge-principal-engineer-hardening-plan.md:83`, `notes/redisforge-principal-engineer-hardening-plan.md:122-124`.
</issue_to_address>
### Comment 6
<location path="notes/redisforge-principal-engineer-hardening-plan.md" line_range="41-46" />
<code_context>
+2. Inspect the current `master` branch and recent history.
+3. Starting from the first task in queue order, evaluate whether its acceptance criteria are already satisfied by the current repository.
+4. Skip already-satisfied tasks, recording the evidence used.
+5. Select the first incomplete task whose dependencies are satisfied.
+6. Implement only that task.
+7. Run targeted verification, then the applicable repository verification baseline.
+8. Create a local commit only when there is no known failing verification.
+9. Stop and produce the required report.
+
+The agent must **not** continue into the next task during the same scheduled run, even if the selected task finishes quickly.
+
</code_context>
<issue_to_address>
**Exhausted queue has no valid report**
When A scheduled run finds that all queue tasks are complete, the selection workflow has no terminal outcome, while the mandatory report requires a task ID and title and defines no queue-complete status. The agent cannot produce a valid report for the finished queue.
Define a queue-complete selection outcome and a matching report status that does not require a task ID or title.
Also at `notes/redisforge-principal-engineer-hardening-plan.md:888-889`.
</issue_to_address>
### Comment 7
<location path="notes/architecture-limitations.md" line_range="129" />
<code_context>
+| Base | Base branch and starting commit |
+| Changed files | Exact paths |
+| Behavior changed | Concise before/after explanation |
+| Tests added/changed | What property they prove |
+| Verification | Each command and PASS / FAIL / UNVERIFIED |
+| Risks | Remaining uncertainty or follow-up |
</code_context>
<issue_to_address>
**Required report evidence is omitted**
When an agent follows the hardening plan’s exact report template, the template omits required test-property evidence and the diff summary, so the resulting report does not provide all the evidence the architecture contract requires.
Align the exact report template with the required report contents, including tests added or changed and the properties they prove, plus the diff summary.
Also at `notes/redisforge-principal-engineer-hardening-plan.md:886-929`.
</issue_to_address>
### Comment 8
<location path="notes/architecture-limitations.md" line_range="19-27" />
<code_context>
+| Area | Current guarantee | Current limitation |
</code_context>
<issue_to_address>
**Guarantee matrix is undiscoverable**
When a visitor uses the README or docs index to find RedisForge’s guarantees, the README and docs index link to `docs/failure-semantics.md`, not this matrix or the current-state baseline. Visitors following the documented entry points therefore miss the new guarantee matrix, leaving RF-M0-P01’s requirement for a README- or docs-index-linked matrix unmet.
Link the baseline or its guarantee matrix from the README or docs index.
</issue_to_address>Sourcery assessment
Approval pending. 7 findings to address first.
Blocking findings: notes/architecture-limitations.md:21, notes/redisforge-principal-engineer-hardening-plan.md:318, notes/redisforge-principal-engineer-hardening-plan.md:340, notes/architecture-limitations.md:94, notes/redisforge-principal-engineer-hardening-plan.md:84, and 2 more
|
|
||
| | Area | Current guarantee | Current limitation | | ||
| | --- | --- | --- | | ||
| | Item durability | CRUD succeeds against the in-process repository and may populate RedisJSON | The authoritative fallback is memory and is recreated on startup; RedisJSON can outlive memory, so GET/List/search can diverge after restart | |
There was a problem hiding this comment.
🟡 Medium · Pre-cutover items disappear or diverge
When redisJSON contains items absent from PostgreSQL when RF-M1-P03 makes PostgreSQL authoritative, production reads switch to PostgreSQL without specifying how to handle Redis-only items or stale cache entries. Those items disappear from durable reads, or CacheItemRepo.GetByID continues serving entries that List omits.
Specify how cutover imports or discards Redis-only items and invalidates stale Redis cache entries.
Also at notes/redisforge-principal-engineer-hardening-plan.md:266-273, notes/architecture-limitations.md:22.
Prompt for AI agents
In `notes/architecture-limitations.md` at line 21:
**Pre-cutover items disappear or diverge**
When redisJSON contains items absent from PostgreSQL when RF-M1-P03 makes PostgreSQL authoritative, production reads switch to PostgreSQL without specifying how to handle Redis-only items or stale cache entries. Those items disappear from durable reads, or `CacheItemRepo.GetByID` continues serving entries that `List` omits.
Specify how cutover imports or discards Redis-only items and invalidates stale Redis cache entries.
Also at `notes/redisforge-principal-engineer-hardening-plan.md:266-273`, `notes/architecture-limitations.md:22`.| - item; | ||
| - idempotency receipt when supplied; | ||
| - outbox event with stable `event_id`, aggregate/item ID, item version, schema version, correlation/request ID where available. | ||
| - Eliminate best-effort asynchronous audit emission from the create correctness path. |
There was a problem hiding this comment.
🟡 Medium · Out-of-order updates lose search changes
When outbox delivery reorders events that contain deltas, the projector applies version N+1 and rejects version N as stale, permanently omitting changes carried only by N from the search projection.
Require full-snapshot events or sequential processing with gap repair before the projector skips older versions.
Also at notes/redisforge-principal-engineer-hardening-plan.md:316, notes/redisforge-principal-engineer-hardening-plan.md:544.
Prompt for AI agents
In `notes/redisforge-principal-engineer-hardening-plan.md` at line 318:
**Out-of-order updates lose search changes**
When outbox delivery reorders events that contain deltas, the projector applies version N+1 and rejects version N as stale, permanently omitting changes carried only by N from the search projection.
Require full-snapshot events or sequential processing with gap repair before the projector skips older versions.
Also at `notes/redisforge-principal-engineer-hardening-plan.md:316`, `notes/redisforge-principal-engineer-hardening-plan.md:544`.|
|
||
| **Scope** | ||
|
|
||
| - Update/delete create outbox events in the same item transaction. |
There was a problem hiding this comment.
🟡 Medium · Updates and deletes emit duplicate audit events
When RF-M1-P06 is implemented by adding update/delete outbox events while retaining the existing handler emits, when RF-M1-P06 adds outbox events without removing the existing handler emits, update and delete requests publish both a best-effort EmitAsync event and an outbox event. They have distinct event IDs, so downstream deduplication does not prevent duplicate audit effects.
Add to RF-M1-P06 scope that update/delete must stop publishing directly through EmitAsync once their durable outbox events are in place.
Prompt for AI agents
In `notes/redisforge-principal-engineer-hardening-plan.md` at line 340:
**Updates and deletes emit duplicate audit events**
When RF-M1-P06 is implemented by adding update/delete outbox events while retaining the existing handler emits, when RF-M1-P06 adds outbox events without removing the existing handler emits, update and delete requests publish both a best-effort `EmitAsync` event and an outbox event. They have distinct event IDs, so downstream deduplication does not prevent duplicate audit effects.
Add to RF-M1-P06 scope that update/delete must stop publishing directly through `EmitAsync` once their durable outbox events are in place.| - the selected task's prerequisite is not satisfied on the current base branch; | ||
| - implementation requires a product/architecture decision not already made in these notes; | ||
| - a required dependency, Docker service, credential, or local capability is unavailable; | ||
| - a failing test appears unrelated to the task and the root cause is not safely attributable; |
There was a problem hiding this comment.
🟡 Medium · Docker checks have conflicting instructions
When docker is unavailable for an integration check but runnable targeted checks pass, the stop rule requires halting when a Docker service is unavailable, while the verification policy permits committing when Docker prevents a CI-equivalent check. The agent cannot determine whether to stop or proceed with an unverified check.
Clarify that the Docker environment-limitation exception permits proceeding when runnable targeted checks pass, consistent with the verification policy.
Also at notes/redisforge-principal-engineer-hardening-plan.md:77, notes/architecture-limitations.md:93.
Prompt for AI agents
In `notes/architecture-limitations.md` at line 94:
**Docker checks have conflicting instructions**
When docker is unavailable for an integration check but runnable targeted checks pass, the stop rule requires halting when a Docker service is unavailable, while the verification policy permits committing when Docker prevents a CI-equivalent check. The agent cannot determine whether to stop or proceed with an unverified check.
Clarify that the Docker environment-limitation exception permits proceeding when runnable targeted checks pass, consistent with the verification policy.
Also at `notes/redisforge-principal-engineer-hardening-plan.md:77`, `notes/architecture-limitations.md:93`.| A task is complete only when: | ||
|
|
||
| - its acceptance criteria are demonstrably satisfied; | ||
| - directly relevant tests exist and pass; |
There was a problem hiding this comment.
🟡 Medium · Documentation tasks cannot advance
When A documentation-only task satisfies its acceptance criteria without adding tests, the global completion rule still requires directly relevant tests to exist and pass, so the agent cannot mark the task complete or advance the queue without adding irrelevant tests.
Make the test requirement conditional on the task and define applicable verification for documentation-only tasks.
Also at notes/redisforge-principal-engineer-hardening-plan.md:83, notes/redisforge-principal-engineer-hardening-plan.md:122-124.
Prompt for AI agents
In `notes/redisforge-principal-engineer-hardening-plan.md` at line 84:
**Documentation tasks cannot advance**
When A documentation-only task satisfies its acceptance criteria without adding tests, the global completion rule still requires directly relevant tests to exist and pass, so the agent cannot mark the task complete or advance the queue without adding irrelevant tests.
Make the test requirement conditional on the task and define applicable verification for documentation-only tasks.
Also at `notes/redisforge-principal-engineer-hardening-plan.md:83`, `notes/redisforge-principal-engineer-hardening-plan.md:122-124`.
Comment on lines
+41
to
+46
| 5. Select the first incomplete task whose dependencies are satisfied. | ||
| 6. Implement only that task. | ||
| 7. Run targeted verification, then the applicable repository verification baseline. | ||
| 8. Create a local commit only when there is no known failing verification. | ||
| 9. Stop and produce the required report. | ||
|
|
There was a problem hiding this comment.
🟡 Medium · Exhausted queue has no valid report
When A scheduled run finds that all queue tasks are complete, the selection workflow has no terminal outcome, while the mandatory report requires a task ID and title and defines no queue-complete status. The agent cannot produce a valid report for the finished queue.
Define a queue-complete selection outcome and a matching report status that does not require a task ID or title.
Also at notes/redisforge-principal-engineer-hardening-plan.md:888-889.
Prompt for AI agents
In `notes/redisforge-principal-engineer-hardening-plan.md` at lines 41-46:
**Exhausted queue has no valid report**
When A scheduled run finds that all queue tasks are complete, the selection workflow has no terminal outcome, while the mandatory report requires a task ID and title and defines no queue-complete status. The agent cannot produce a valid report for the finished queue.
Define a queue-complete selection outcome and a matching report status that does not require a task ID or title.
Also at `notes/redisforge-principal-engineer-hardening-plan.md:888-889`.| | Base | Base branch and starting commit | | ||
| | Changed files | Exact paths | | ||
| | Behavior changed | Concise before/after explanation | | ||
| | Tests added/changed | What property they prove | |
There was a problem hiding this comment.
🟡 Medium · Required report evidence is omitted
When an agent follows the hardening plan’s exact report template, the template omits required test-property evidence and the diff summary, so the resulting report does not provide all the evidence the architecture contract requires.
Align the exact report template with the required report contents, including tests added or changed and the properties they prove, plus the diff summary.
Also at notes/redisforge-principal-engineer-hardening-plan.md:886-929.
Prompt for AI agents
In `notes/architecture-limitations.md` at line 129:
**Required report evidence is omitted**
When an agent follows the hardening plan’s exact report template, the template omits required test-property evidence and the diff summary, so the resulting report does not provide all the evidence the architecture contract requires.
Align the exact report template with the required report contents, including tests added or changed and the properties they prove, plus the diff summary.
Also at `notes/redisforge-principal-engineer-hardening-plan.md:886-929`.
Comment on lines
+19
to
+27
| | Area | Current guarantee | Current limitation | | ||
| | --- | --- | --- | | ||
| | Item durability | CRUD succeeds against the in-process repository and may populate RedisJSON | The authoritative fallback is memory and is recreated on startup; RedisJSON can outlive memory, so GET/List/search can diverge after restart | | ||
| | Search | RediSearch indexes RedisJSON keys | Update invalidates the cache key, so an item can disappear from search until a later read backfills it; there is no authoritative fallback scan | | ||
| | Idempotency | Bloom may reject a previously seen key | Bloom false positives can reject valid requests; errors fail open; there is no durable request/response receipt | | ||
| | Audit publication | Successful `XADD` gives a recoverable stream entry while retained | Producer failure or shutdown can lose best-effort emits; bounded trimming is not permanent retention | | ||
| | Audit processing | Consumer-group recovery can redeliver retained pending entries | The worker logs and ACKs only; it has no durable audit sink or exactly-once guarantee | | ||
| | Health | `/healthz` proves the HTTP process can answer | It does not prove Redis or any future database dependency is ready | | ||
| | Redis topology | Standalone, Sentinel, and Cluster clients are configurable | Startup also depends on RedisJSON, RedisBloom, and RediSearch module availability | |
There was a problem hiding this comment.
⚪ Low · Guarantee matrix is undiscoverable
When a visitor uses the README or docs index to find RedisForge’s guarantees, the README and docs index link to docs/failure-semantics.md, not this matrix or the current-state baseline. Visitors following the documented entry points therefore miss the new guarantee matrix, leaving RF-M0-P01’s requirement for a README- or docs-index-linked matrix unmet.
Link the baseline or its guarantee matrix from the README or docs index.
Prompt for AI agents
In `notes/architecture-limitations.md` at lines 19-27:
**Guarantee matrix is undiscoverable**
When a visitor uses the README or docs index to find RedisForge’s guarantees, the README and docs index link to `docs/failure-semantics.md`, not this matrix or the current-state baseline. Visitors following the documented entry points therefore miss the new guarantee matrix, leaving RF-M0-P01’s requirement for a README- or docs-index-linked matrix unmet.
Link the baseline or its guarantee matrix from the README or docs index.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Reworks the two RedisForge notes into an automation-safe execution system for daily Agent Zero runs.
No production code is changed.
Summary by Sourcery
Make RedisForge’s documentation safe for incremental automated hardening by defining its architectural contract, executable task queue, verification evidence, and human-controlled merge workflow.
Enhancements:
Documentation: