Merge pull request #84 from luohaha/codex/requirement-propose-update

feat: manage agent-proposed requirements

Author: luohaha

README.md

@@ -69,15 +69,15 @@ flowchart LR
 
 1. A human creates a Requirement and chooses Codex or Claude Code, optionally pinning a model and reasoning effort. Code Factory creates a dedicated, persistent RD session for it.
 2. Agent Manager starts or resumes that agent in the managed workspace. Messages sent during a run are queued; the human may explicitly interrupt when an immediate correction is needed.
-3. The RD agent edits and tests the repository, then uses the bundled `code-factory-cli` to register any pull request it creates, propose separate follow-up work (optionally starting it immediately), inspect its direct parent and child Requirements, message their RD Agents, or schedule a wake-up while a long external build or command continues. Related-Agent messages are persisted in the target Requirement conversation and start or queue its long-lived RD session.
+3. The RD agent edits and tests the repository, then uses the bundled `code-factory-cli` to register any pull request it creates, propose separate follow-up work, update, start, or delete its still-TODO proposals, inspect its direct parent and child Requirements, message their RD Agents, or schedule a wake-up while a long external build or command continues. Related-Agent messages are persisted in the target Requirement conversation and start or queue its long-lived RD session.
 4. Agent Triggers route normalized, deduplicated messages into the Requirement conversation. The timer trigger executes configurable one-time or recurring timers and sends their ID and follow-up description when due. The GitHub triggers poll registered PRs whose last stored state is Draft or Open, observing state, comments and reviews, CI failures, and merge conflicts. This lets the reconciler discover when a Draft PR becomes Open. Once a PR transitions to Closed or Merged, it is excluded from later polls. An idle RD session resumes immediately; a running session consumes the new messages after its current run.
 5. A human can request a short-lived AI review for an open PR with its own provider, model, and reasoning effort. Review results return to the same conversation and wake the original RD session to continue the loop.
 
 The Agent Trigger boundary is intentionally source-neutral, but its current message contract targets an existing Requirement. Scheduled wake-ups are natively configurable; dynamic discovery and configuration of third-party trigger implementations, Slack and Jira sources, and triggers that create new Requirements are future extensions rather than implemented behavior.
 
 Different Requirements can run concurrently, while each Requirement has at most one active RD run. Requirement state, conversations, runs, sessions, PR metadata, scheduled wake-ups, and Agent Trigger receipts are persisted in SQLite. Cancelled Requirements are retained for 7 days and completed Requirements for 365 days by default; both periods are runtime-configurable, and expiry atomically removes the Requirement and its related domain records while retaining retryable tombstones until attachment files are deleted.
 
-Agent Manager places `code-factory-cli` on every RD process's `PATH` and injects its API URL, Requirement ID, and Session ID through the environment. The RD prompt describes available capabilities and leaves command names and arguments to `code-factory-cli --help`; raw HTTP details remain an internal transport contract. Use `code-factory-cli pr register --from-github <PR-URL>` to read current metadata through `gh`, and `requirement propose --description-file <PATH> [--start]` for multiline follow-up descriptions with optional immediate execution. Resumed prompts retain the current Requirement context and instruct agents to check for already-completed actions before retrying.
+Agent Manager places `code-factory-cli` on every RD process's `PATH` and injects its API URL, Requirement ID, and Session ID through the environment. The RD prompt describes available capabilities and leaves command names and arguments to `code-factory-cli --help`; raw HTTP details remain an internal transport contract. Use `code-factory-cli pr register --from-github <PR-URL>` to read current metadata through `gh`, `requirement propose --description-file <PATH> [--start]` for multiline follow-up descriptions with optional immediate execution, and the `requirement update`, `requirement start`, or `requirement delete` command with `--requirement-id <ID>` to manage a proposal while it remains TODO. Resumed prompts retain the current Requirement context and instruct agents to check for already-completed actions before retrying.
 
 Agent context is scoped to the Requirement rather than copied from whichever interactive agent or terminal started Agent Manager. A Requirement's first RD Run creates a new native Codex thread or Claude Code session; later Runs resume that same native session, preserving its conversation context. Because the child CLI inherits Agent Manager's environment and starts in the managed workspace, it also discovers the provider's configured project/user instructions, Skills, plugins, and local memory features according to the CLI's own rules. Code Factory does not automatically copy another agent's live transcript or merge context from other Requirements. An explicit related-Agent message is new, durable input to the target Requirement rather than shared session context. Code Factory does not guarantee that every provider-managed memory entry is injected.
 

apps/web/lib/agent-manager-client.test.ts

@@ -5,4 +5,5 @@ import { MANAGER_EVENT_TYPES } from './manager-event-types.ts';
 
 void test('subscribes to live Agent trace events', () => {
   assert.ok(MANAGER_EVENT_TYPES.includes('run.trace.appended'));
+  assert.ok(MANAGER_EVENT_TYPES.includes('requirement.updated'));
 });

apps/web/lib/dashboard-state.test.ts

@@ -192,6 +192,9 @@ void test('does not apply an in-flight scoped response after its Requirement is
 });
 
 void test('routes legacy SSE payloads to precise resource refreshes', () => {
+  assert.deepEqual(refreshTargetsForManagerEvent(managerEvent('requirement.updated')), [
+    { scope: 'requirement', requirementId: 'requirement-1', includeRuns: false },
+  ]);
   assert.deepEqual(refreshTargetsForManagerEvent(managerEvent('message.created')), [
     { scope: 'messages', requirementId: 'requirement-1' },
     { scope: 'requirement', requirementId: 'requirement-1', includeRuns: false },
@@ -221,6 +224,7 @@ void test('routes legacy SSE payloads to precise resource refreshes', () => {
 void test('does not refresh when a common SSE event carries persisted resources', () => {
   const payloads: Array<[string, Record<string, unknown>]> = [
     ['requirement.created', { requirement: { id: 'requirement-1' } }],
+    ['requirement.updated', { requirement: { id: 'requirement-1' } }],
     ['message.created', { message: { id: 'message-1', requirementId: 'requirement-1' }, requirement: { id: 'requirement-1' } }],
     ['run.started', { run: { id: 'run-1', requirementId: 'requirement-1' }, requirement: { id: 'requirement-1' } }],
     ['run.succeeded', { run: { id: 'run-1', requirementId: 'requirement-1' }, requirement: { id: 'requirement-1' } }],

apps/web/lib/dashboard-state.ts

@@ -183,6 +183,7 @@ export function refreshTargetsForManagerEvent(event: ManagerEventDto): Dashboard
   const hasTimer = Boolean(requirementId && event.payload.timer?.requirementId === requirementId);
   switch (event.type) {
     case 'requirement.created':
+    case 'requirement.updated':
       return !hasRequirement && requirementId
         ? [{ scope: 'requirement', requirementId, includeRuns: false }]
         : [];
@@ -298,6 +299,7 @@ export function mergeRefreshTargets(
 export function managerEventInvalidatesSearch(event: ManagerEventDto): boolean {
   return [
     'requirement.created',
+    'requirement.updated',
     'requirement.deleted',
     'requirements.purged',
     'message.created',

apps/web/lib/manager-event-types.ts

@@ -1,5 +1,6 @@
 export const MANAGER_EVENT_TYPES = [
   'requirement.created',
+  'requirement.updated',
   'requirement.deleted',
   'requirement.completed',
   'requirements.purged',

docs/agent-manager-api.md

@@ -66,6 +66,9 @@ The service listens only on the loopback interface by default and currently has
 | GET | /api/events | Subscribe to the resumable SSE stream |
 | POST | /api/agent/pull-requests | Register or update a PR from an RD Agent |
 | POST | /api/agent/requirements | Propose a follow-up Requirement from an RD Agent |
+| PATCH | /api/agent/requirements/:id | Update a TODO Requirement proposed by the current RD Agent |
+| DELETE | /api/agent/requirements/:id | Delete a TODO Requirement proposed by the current RD Agent |
+| POST | /api/agent/requirements/:id/start | Start a TODO Requirement proposed by the current RD Agent |
 | GET | /api/agent/requirements/:id/related | List a source Requirement's direct parent and children |
 | POST | /api/agent/requirements/:id/related/:targetId/messages | Message a directly related Requirement's RD Agent |
 
@@ -703,6 +706,9 @@ These endpoints are the transport used by `code-factory-cli` and other trusted l
 ~~~bash
 code-factory-cli pr register --help
 code-factory-cli requirement propose --help
+code-factory-cli requirement update --help
+code-factory-cli requirement start --help
+code-factory-cli requirement delete --help
 code-factory-cli requirement related --help
 code-factory-cli requirement message --help
 code-factory-cli timer register --help
@@ -782,6 +788,73 @@ curl -X POST http://127.0.0.1:4310/api/agent/requirements \
 
 Success: 201 Created with the new Requirement and `createdBy=rd_agent`. Without `start: true`, it remains TODO. When `start` is true, the response reflects its started RD Session. Returns 404 for an unknown source Session and 400 when `parentRequirementId` does not match or another field is invalid.
 
+### PATCH /api/agent/requirements/:targetRequirementId
+
+Updates the title and/or description of a follow-up Requirement before it starts. The target must be a TODO child proposed by the same source RD Session. This prevents an Agent from changing unrelated, human-created, running, or terminal work.
+
+Request body:
+
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| sourceRequirementId | string | yes | Current Requirement injected into the source RD Agent |
+| sourceSessionId | string | yes | Current Requirement's RD Session |
+| title | string | no | Replacement title |
+| description | string | no | Replacement description |
+
+At least one of `title` or `description` is required. Omitted fields retain their current values.
+
+~~~bash
+curl -X PATCH http://127.0.0.1:4310/api/agent/requirements/req_child \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "sourceRequirementId": "req_parent",
+    "sourceSessionId": "ses_parent",
+    "description": "Corrected follow-up scope"
+  }'
+~~~
+
+Success: 200 OK with the updated Requirement and Session. Returns 404 for an unknown source or target, 400 for invalid input or a mismatched source Session, and 409 when the target was not proposed by the source or is no longer TODO.
+
+The CLI supplies the source identifiers from its injected context. Use `requirement related` to discover child IDs:
+
+~~~bash
+code-factory-cli requirement update --requirement-id req_child --title 'Corrected title'
+code-factory-cli requirement update --requirement-id req_child --description-file ./corrected-scope.md
+~~~
+
+### POST /api/agent/requirements/:targetRequirementId/start
+
+Starts a proposed child Requirement while it remains TODO. The JSON request body requires `sourceRequirementId` and `sourceSessionId`; they must identify the RD Session that originally proposed the target.
+
+~~~bash
+curl -X POST http://127.0.0.1:4310/api/agent/requirements/req_child/start \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "sourceRequirementId": "req_parent",
+    "sourceSessionId": "ses_parent"
+  }'
+~~~
+
+Success: 202 Accepted with `accepted`, `action=start`, the started Requirement/session snapshot, and its running RD Run. Returns 404 for an unknown source or target, 400 for a mismatched source Session, and 409 when the target was not proposed by the source or is no longer TODO.
+
+~~~bash
+code-factory-cli requirement start --requirement-id req_child
+~~~
+
+### DELETE /api/agent/requirements/:targetRequirementId
+
+Deletes a proposed child Requirement while it remains TODO. The required `sourceRequirementId` and `sourceSessionId` query parameters must identify the RD Session that originally proposed the target. Deletion follows the normal Requirement lifecycle: the Requirement becomes CANCELLED and is retained according to workspace policy.
+
+~~~bash
+curl -X DELETE 'http://127.0.0.1:4310/api/agent/requirements/req_child?sourceRequirementId=req_parent&sourceSessionId=ses_parent'
+~~~
+
+Success: 200 OK with `{ "deleted": true, "requirement": ... }`. Returns 404 for an unknown source or target, 400 for missing or mismatched source context, and 409 when the target was not proposed by the source or is no longer TODO.
+
+~~~bash
+code-factory-cli requirement delete --requirement-id req_child
+~~~
+
 ### GET /api/agent/requirements/:sourceRequirementId/related
 
 Returns the source Requirement's direct parent and children as `{ "parent": Requirement | null, "children": Requirement[] }`, including terminal records that have not yet expired. The required `sourceSessionId` query parameter must identify the source Requirement's RD Session.
@@ -843,6 +916,7 @@ Current event types and primary payloads:
 | Event | Payload |
 | --- | --- |
 | requirement.created | requirement, provider, createdBy |
+| requirement.updated | updated requirement |
 | requirement.deleted | terminal requirement and its timers |
 | requirement.completed | updated requirement and its timers |
 | requirements.purged | requirementIds, cancelledCount, doneCount |

docs/agent-runners.md

@@ -41,23 +41,29 @@ RD Agents use self-describing commands instead of constructing Agent API request
 ```bash
 code-factory-cli pr register --help
 code-factory-cli requirement propose --help
+code-factory-cli requirement update --help
+code-factory-cli requirement start --help
+code-factory-cli requirement delete --help
 code-factory-cli timer register --help
 code-factory-cli timer show --help
 code-factory-cli timer cancel --help
 ```
 
-`pr register` registers a newly created PR or refreshes metadata changed by the RD Agent. `requirement propose` records separate follow-up work as a linked TODO Requirement. `requirement related` lists direct parent and child Requirements; `requirement message` coordinates with their RD Agents. `timer register` registers a one-time wake-up by default or a recurring one with `--repeat`; `timer show` recovers timer IDs and statuses for the current Requirement; `timer cancel` stops an active timer. The commands print the Agent API JSON response on stdout. Exit code `0` means success, `2` means invalid input or missing context, and `1` means an execution, network, HTTP, or response-format failure. Errors go to stderr. API requests and GitHub lookups time out after 30 seconds; writes are never automatically retried. A timeout or invalid response can occur after the server commits a write: inspect the Requirement before retrying, especially when proposing follow-up work.
+`pr register` registers a newly created PR or refreshes metadata changed by the RD Agent. `requirement propose` records separate follow-up work as a linked TODO Requirement; `requirement update`, `requirement start`, and `requirement delete` manage that proposal before it starts. `requirement related` lists direct parent and child Requirements; `requirement message` coordinates with their RD Agents. `timer register` registers a one-time wake-up by default or a recurring one with `--repeat`; `timer show` recovers timer IDs and statuses for the current Requirement; `timer cancel` stops an active timer. The commands print the Agent API JSON response on stdout. Exit code `0` means success, `2` means invalid input or missing context, and `1` means an execution, network, HTTP, or response-format failure. Errors go to stderr. API requests and GitHub lookups time out after 30 seconds; writes are never automatically retried. A timeout or invalid response can occur after the server commits a write: inspect the Requirement before retrying, especially when proposing or managing follow-up work.
 
 Prefer registration from an explicit PR URL, using the authenticated local `gh` CLI:
 
 ```bash
 code-factory-cli pr register --from-github https://github.com/OWNER/REPO/pull/123
 code-factory-cli requirement propose --title 'Follow-up task' --description-file ./follow-up.md --start
+code-factory-cli requirement update --requirement-id req_... --description-file ./corrected-follow-up.md
+code-factory-cli requirement start --requirement-id req_...
+code-factory-cli requirement delete --requirement-id req_...
 ```
 
 `--from-github` reads the PR number, title, URL, branches, head SHA, and state from GitHub and validates the returned identity before registration. The repository key comes from the returned URL and is normalized to lowercase, matching Manager and Store identity checks. GitHub Enterprise URLs are supported and retain the hostname in the repository identifier. It cannot be mixed with manual metadata flags. The existing full manual registration form remains supported for callers that already have a snapshot; an existing PR's lifecycle is still owned by the reconciler, even when `--status` is supplied. The CLI does not create or edit GitHub PRs.
 
-`--description-file` reads a UTF-8 file relative to the CLI's working directory and is mutually exclusive with `--description`. This avoids shell quoting problems for multiline descriptions. Proposed Requirements remain TODO by default; `--start` starts the new Requirement's RD Session immediately.
+`--description-file` reads a UTF-8 file relative to the CLI's working directory and is mutually exclusive with `--description`. This avoids shell quoting problems for multiline descriptions. Proposed Requirements remain TODO by default; `--start` starts the new Requirement's RD Session immediately. Only the same source RD Session can update, start, or delete its directly proposed child, and only while that child remains TODO.
 
 The RD behavioral prompt is supplied on both initial and resumed invocations. It describes CLI capabilities and behavioral constraints, leaving command names and arguments to `code-factory-cli --help`. It covers Requirement scope, worktree isolation, recovery without duplicate actions, control-plane commands, lifecycle ownership, evaluating external feedback, and evidence-based handoff. Task-specific content stays in the stdin prompt; every invocation includes the current Requirement ID, title, and description, with only new external conversation messages on resume. Questions and investigations do not inherently require code changes, and the RD Agent must not substitute follow-up proposals for work required by the current Requirement. A successful GitHub PR creation and a successful Code Factory registration are separate outcomes; a failed registration must be reported without recreating the PR. Human confirmation owns Requirement completion.
 

docs/architecture.en.md

@@ -80,7 +80,8 @@ Every headless RD and Reviewer invocation skips interactive approval and CLI san
 - optional `model` and `reasoningEffort` pin the CLI configuration for every RD Run in the Session;
 - `createdBy`: `human | rd_agent`;
 - an agent-proposed Requirement records `parentRequirementId` and `sourceSessionId`;
-- an agent proposal is created as TODO by default, preventing uncontrolled recursive work; an explicit CLI `--start` opt-in starts its RD Session immediately.
+- the source RD Session may update, start, or delete that proposed child only while it remains TODO;
+- an agent proposal is created as TODO by default, preventing uncontrolled recursive work; an explicit CLI `--start` opt-in starts its RD Session immediately, while `requirement start` can start it later.
 - the proposing Requirement and its direct child can discover each other and exchange explicit, durable RD messages without sharing native agent-session context.
 
 ### AgentSession