docs(operators): alfred-code intake note (#292)

[ssdavidai]

Adds the operator note requested by #292: docs/operators/alfred-code-intake.md, documenting the Alfred Code control-plane intake flow.

The note covers both label-gated and automatic intake, lane and contract discovery before building, exact full-hash approval and rejection before launch, the lack of a post-launch cancellation command, and the authority boundary between GitHub Projects and the Superset execution runtime.

Lane V (edges-infra), controller job docs-292, pinned base eaf0802a, approved plan 0b0c823a01293dc5979185259da0616ce08131b8a8063ce134a02e724544902e. Documentation-only; docs/operators/ matches the lane V docs/** allowed glob and no forbidden-zone glob.

Refs #292

Smoke evidence

Exact current head: 318d1559ac82275a4e2b64f9280914139037d223.

Diff versus the pinned base is exactly one added file and 66 inserted lines:

$ git diff --name-status eaf0802aab77a9bb127790ec7837b3544183a95d..HEAD
A	docs/operators/alfred-code-intake.md

$ git diff --numstat eaf0802aab77a9bb127790ec7837b3544183a95d..HEAD
66	0	docs/operators/alfred-code-intake.md

$ git diff --check eaf0802aab77a9bb127790ec7837b3544183a95d..HEAD
# exit 0

Lane V verification at the current branch head, with the local ignored .env already present:

$ docker compose config -q
# exit 0

$ python3 scripts/hooks/check_lane.py --ci --lane V --base eaf0802aab77a9bb127790ec7837b3544183a95d
✓ lane V (edges-infra) CI gate passed — 66 LOC, 1 files
# exit 0

$ PYTHONDONTWRITEBYTECODE=1 python3 -m unittest -v scripts.hooks.test_check_lane
Ran 17 tests
OK

Focused controller behavior was verified against ssdavidai/alfred-code@4cba6bc5c5aeae62e8552068804ae632c1de4b1b:

$ PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python3 -m unittest discover -s tests -v
Ran 44 tests
OK

The issue thread records plan publication before the owner supplied the exact full-hash approval. Focused tests verify that no job or workspace is materialized before approval, exact rejection blocks a pre-build plan, automatic intake projects an issue to Specifying before planning, and a late rejection does not cancel a launched job.

[ssdavidai]

Independent review result for dc0110232f2274b88fe412d01c947afd0a14849d: fail.

Finding

• P1 — The note incorrectly promises that removing alfred-code withdraws work after intake. docs/operators/alfred-code-intake.md:8-10 says that removing the label withdraws the issue. The controller keeps an issue active once a plan or jobs exist, regardless of subsequent label membership. A focused test against the clean controller source snapshot ssdavidai/alfred-code@6e2d6dc9048dfa3fe47e3276c5d63cfd10d7afc8 reproduced the unsafe operator outcome: plan state awaiting_approval; remove the label; supply the exact approval; resulting state building, one job materialized, one worker launched (exit 0). An operator following this note could remove the label believing execution is cancelled while the controller still accepts approval and starts work. Qualify withdrawal as pre-intake only, or document the real cancellation mechanism.

Scope, contracts, and command evidence

• Live GitHub diff from base eaf0802aab77a9bb127790ec7837b3544183a95d contains exactly A docs/operators/alfred-code-intake.md (56 LOC); git diff --check passed. No application code, contract, hook, config, workflow, or dependency file changed.
• Live scripts/hooks/lanes.json assigns docs/** to lane V (edges-infra), excludes this path from the forbidden zone, and specifies docker compose config -q. Contracts read: lane policy only; contracts changed: none.
• docker compose config -q → exit 0.
• python3 scripts/hooks/check_lane.py --ci --lane V --base eaf0802aab77a9bb127790ec7837b3544183a95d → lane V passed, 56 LOC, 1 file, exit 0.
• python3 scripts/hooks/test_check_lane.py → 17/17 passed, exit 0.
• The required four acceptance topics are present, and the issue thread shows the plan was published before the later exact full-hash human approval. The inaccurate withdrawal claim is extra prose and remains actionable.

Actual CI

GitHub reports 13/13 check runs completed successfully on this exact head SHA, including lane-gate, compose-lint, workflow-lint, builds/tests, gitleaks, and GitGuardian. All 5 GitHub Actions workflows for the SHA completed successfully on attempt 1; the compose-lint job records both compose-config steps as successful.

[ssdavidai]

Independent review of dc0110232f2274b88fe412d01c947afd0a14849d: FAIL

Finding

1. Actionable documentation defect — the intake description contradicts the live controller. docs/operators/alfred-code-intake.md:8-11 says only the alfred-code label triggers intake, an unlabeled issue is invisible, and removing the label withdraws it. The deployed non-secret config has github.auto_intake = true. The live controller source at src/alfred_code/controller.py:94-97 enrolls an open issue when auto_intake is true or the label matches, and :121 continues processing an already-active issue. Therefore unlabeled open issues are currently enrolled, and removing the label does not withdraw a plan/job already in progress. Update the note to distinguish auto-intake mode from label-gated mode and remove the withdrawal claim unless that behavior is implemented.

Scope, contracts, and acceptance

• Fetched base eaf0802aab77a9bb127790ec7837b3544183a95d and head dc0110232f2274b88fe412d01c947afd0a14849d. git diff --name-status base..head reports exactly A docs/operators/alfred-code-intake.md; stat is 56 insertions in one file; git diff --check exits 0.
• Live scripts/hooks/lanes.json: lane V (edges-infra) allows docs/**, has a 200-LOC cap, and none of the forbidden globs match this path. The lane manifest further narrows scope to the requested file.
• The four requested topics are present. The live issue timeline shows plan publication at 2026-07-16T11:55:59Z, exact-full-hash human approval at 12:02:49Z, and specification at 12:06:39Z; build/commit activity followed later. That supports the approval-gate sequence, but it does not support the extra exclusivity/withdrawal claims above.

Command and CI evidence

• docker compose config -q → exit 0 (unset-variable warnings only; no secret values inspected or printed).
• python3 scripts/hooks/check_lane.py --ci --lane V --base eaf0802aab77a9bb127790ec7837b3544183a95d → lane V passed, 56 LOC / 1 file, exit 0.
• Focused live-controller tests → 3 passed: unlabeled auto-intake, label-gated backlog behavior, and full/exact/allow-listed approval.
• GitHub REST commit checks for the exact SHA: 13 total, 0 pending/non-success. The five Actions runs and all 12 Actions jobs completed successfully (ci-check, gitleaks, lane-gate, notify-telegram, pr-review-gate), plus GitGuardian succeeded. CI logs show the actual Compose and lane-gate commands ran.
• PR head and remote branch were re-fetched immediately before this comment and still resolve to the reviewed SHA.

[ssdavidai]

Independent review of dc01102: FAIL

Findings

1. Blocking documentation defect at docs/operators/alfred-code-intake.md:8-10. The note says an unlabeled issue is invisible and removing alfred-code withdraws it. The live controller observes and project-syncs the full open backlog, including unlabeled issues, and keeps any issue with a current plan or jobs active regardless of later label membership. A focused behavior probe reproduced the dangerous sequence: state awaiting_approval; remove the label; supply the already-published exact approval; result state building with 1 job and 1 Superset worker. Removing the label is therefore not a cancellation mechanism. Limit the label statement to enrollment and document the real cancellation path.

2. Blocking operational overclaim at docs/operators/alfred-code-intake.md:49-52. Superset is not technically read-only and actions there can dispatch or halt execution: the installed Superset v1.15 CLI exposes agents create and workspaces delete, while the controller explicitly blocks a job when Superset reports failed, crashed, or terminated. Reword this as an authority/convention rule: GitHub is the controller source of truth, and manual Superset mutations are out-of-band and disruptive.

Scope, contracts, and acceptance evidence

• The live GitHub base/head remained eaf0802..dc01102 immediately before this comment.
• git diff --name-status reports exactly A docs/operators/alfred-code-intake.md; mode is 100644, 56 inserted lines, and git diff --check passed.
• Live scripts/hooks/lanes.json assigns docs/** to lane V edges-infra, with docker compose config -q verification and a 200 LOC limit. The requested file does not match any forbidden-zone contract path. Contracts read: lane policy only. Contracts changed: none.
• All four requested topics are present. The issue timeline shows plan publication at 11:55:59Z followed by the exact full-hash human approval at 12:02:49Z, so the core approval-gate acceptance claim is evidenced. The two inaccurate absolute claims above are additional prose and remain actionable.

Command evidence

• docker compose config -q: exit 0. Compose emitted unset-variable warnings but no secret values.
• python3 scripts/hooks/check_lane.py --ci --lane V --base eaf0802: exit 0; lane V passed, 56 LOC, 1 file.
• python3 -m unittest scripts.hooks.test_check_lane -v: 17 of 17 passed.
• PYTHONPATH=src focused controller tests for exact approval, no pre-approval launch, unlabeled backlog projection, plan hashing, and forbidden-zone validation: 5 of 5 passed.
• Focused unlabel-then-approve behavior probe: exit 0; awaiting_approval became building with 1 job and 1 workspace.

Actual CI

GitHub REST reports 13 of 13 check runs completed successfully for this exact SHA, with no pending or non-success conclusions. This includes lane-gate, compose-lint, workflow-lint, build and test jobs, gitleaks, GitGuardian, smoke-evidence-check, and notification.

[ssdavidai]

Independent review of 294bb4cee9f37e430e3f4545498d4eb9f8cb9ece: FAIL.

Findings

1. Blocking cancellation guidance is unsafe at docs/operators/alfred-code-intake.md:10-12. The note says that after a plan or job exists, the operator can “reject the current plan in GitHub” or use a “documented incident procedure.” Exact /reject-plan is effective only while the plan is awaiting approval; once approval has materialized a job, a later exact rejection does not cancel or halt it. A focused current-controller probe observed post_launch_reject: before=running after=running. The referenced incident procedure is not linked, and a search of this repository plus the current controller docs/source found no such procedure beyond this new sentence. Restrict /reject-plan guidance to pre-build plans and link a real, verified stop/cancellation procedure for launched work.

2. Blocking Superset control claims are technically false at docs/operators/alfred-code-intake.md:55-62. The installed Superset 1.15.0 CLI exposes agents create and workspaces delete, so Superset can start agent sessions and remove their workspaces. More importantly, the current controller polls Superset workspace details and changes a job to blocked when an agent reports failed, crashed, or terminated; a focused probe observed superset_terminated: state=blocked last_error=Superset reports a failed agent session. Recast “GitHub is the control center” as the supported authority/operator convention and warn that manual Superset mutations are out-of-band and disruptive; do not claim that nothing done there can dispatch or halt work or that the controller only responds to GitHub signals.

3. The PR smoke transcript is stale for this head. It reports a 56-line diff and 56-LOC lane result from dc011023, while the live pinned diff is 62 inserted lines and the current lane gate reports 62 LOC. Refresh the claimed smoke evidence for the exact reviewed SHA.

Scope, contracts, and acceptance

• GitHub and the local checkout both resolved to base eaf0802aab77a9bb127790ec7837b3544183a95d and head 294bb4cee9f37e430e3f4545498d4eb9f8cb9ece immediately before this comment.
• git diff --name-status base..head reports exactly A docs/operators/alfred-code-intake.md; numstat is 62 0; git diff --check exits 0. No application code, contract, hook, configuration, workflow, or dependency file changed.
• Live scripts/hooks/lanes.json assigns docs/** to lane V (edges-infra), caps it at 200 LOC, specifies docker compose config -q, and no forbidden-zone glob matches this path. Contracts read: lane policy only. Contracts changed: none.
• The four issue-requested topics are present. The issue thread records plan publication at 2026-07-16T11:55:59Z, followed by the exact full-hash human approval at 12:02:49Z; the focused no-approval test also confirms no job/workspace is materialized before approval. The extra operational claims above remain actionable.

Command evidence

• Clean-worktree docker compose config -q initially exits 1 because the ignored .env is absent. Running that exact command against an isolated archive of this SHA with .env seeded from committed .env.example exits 0; no repository file was changed.
• python3 scripts/hooks/check_lane.py --ci --lane V --base eaf0802aab77a9bb127790ec7837b3544183a95d → lane V passed, 62 LOC / 1 file, exit 0.
• PYTHONDONTWRITEBYTECODE=1 python3 -m unittest -v scripts.hooks.test_check_lane → 17/17 passed.
• Eight focused tests against current ssdavidai/alfred-code@700fc34a3424b1b37df7c344997b7e2091f632fb covering no-preapproval launch, exact rejection, feedback replanning, automatic intake, launch adoption, exact/allow-listed approval, decision ordering, and forbidden-zone validation → 8/8 passed.
• Focused behavioral probes against that same controller → exit 0, reproducing both running -> running after a post-launch rejection and running -> blocked after Superset reports TERMINATED.

Actual CI

GitHub REST reports 12/12 check runs completed successfully for this exact SHA, with zero pending or non-success conclusions. All four Actions runs and all 11 Actions jobs succeeded; GitGuardian also succeeded. The actual logs show compose-lint seeded .env from .env.example and ran docker compose config --quiet, while lane-gate resolved lane V and passed the current 62-LOC / 1-file diff plus its gate unit tests.

[ssdavidai]

Independent review of 5b0a76f: FAIL

Finding

1. Blocking operator-guidance mismatch at docs/operators/alfred-code-intake.md:36-41. The note says that any operator comment other than an exact approval/rejection is specification feedback and produces a new plan. The controller deliberately excludes every comment beginning with /approve-plan or /reject-plan from feedback handling, even when the hash is truncated, stale, or otherwise malformed. A focused probe produced truncated_decision=None and truncated_feedback=None; the current controller branch at a9553802a33bffbebea097effdf80d06e1178fd1 now has an explicit regression test for this and describes malformed control commands as ignored. Narrow the note to normal/non-command feedback from an allow-listed operator, and state that malformed approval/rejection commands are ignored rather than replanning.

Scope, contracts, and acceptance

• Live GitHub base/head and the remote lane branch remained eaf0802..5b0a76f immediately before this comment.
• git diff --name-status reports exactly A docs/operators/alfred-code-intake.md; numstat is 65 0; git diff --check exits 0. The requested lane manifest is therefore exact, with no application code, contract, hook, configuration, workflow, or dependency change.
• Live scripts/hooks/lanes.json assigns docs/** to lane V (edges-infra), specifies docker compose config -q, caps the lane at 200 LOC, and no forbidden-zone glob matches this path. Contracts read: lane policy. Contracts changed: none.
• The four requested topics are present. The issue timeline shows plan publication at 2026-07-16T11:55:59Z and exact-full-hash human approval at 12:02:49Z, before implementation. The inaccurate extra feedback sentence above remains actionable.
• The revised post-launch guidance is otherwise supported: a focused probe observed no pre-approval job/workspace, building/running after approval, building/running after a late exact rejection, and blocked/blocked after Superset reported TERMINATED.

Command evidence

• In an isolated archive of this exact SHA, with .env copied from .env.example and the same dummy values appended by CI, docker compose config -q and docker compose --profile tailscale config -q both exited 0 (unset-variable warnings only).
• PYTHONDONTWRITEBYTECODE=1 python3 scripts/hooks/check_lane.py --ci --lane V --base eaf0802 → lane V passed, 65 LOC / 1 file, exit 0.
• PYTHONDONTWRITEBYTECODE=1 python3 -m unittest -v scripts.hooks.test_check_lane → 17/17 passed.
• Against the smoke-pinned controller 700fc34a3424b1b37df7c344997b7e2091f632fb, 32 focused controller/GitHub/plan/planner tests passed. Re-running at current controller branch head a9553802a33bffbebea097effdf80d06e1178fd1 passed 33/33, including the new malformed-command regression test.

Actual CI

GitHub REST reports 14/14 check-run records completed successfully for this exact SHA, with zero pending or non-success conclusions (12 unique check names; the smoke gate ran successfully three times after PR-body edits). All six Actions runs succeeded, and GitGuardian succeeded. Actual logs show compose-lint seeded .env from .env.example and ran both Compose configurations; lane-gate resolved branch lane-5/292-alfred-code-intake-note to lane V, passed the 65-LOC / 1-file gate, and ran 17 passing gate tests.

[ssdavidai]

Independent review of 318d1559ac82275a4e2b64f9280914139037d223: FAIL.

Finding

1. P1 — docs/operators/alfred-code-intake.md:39-40 overstates malformed-command handling at the required controller commit. The note says malformed approval and rejection commands are ignored rather than treated as feedback. At the mandated ssdavidai/alfred-code@a9553802a33bffbebea097effdf80d06e1178fd1, src/alfred_code/github.py:281-285 excludes only bodies beginning with /approve-plan or /reject-plan (an ASCII-space suffix). Bare /approve-plan, bare /reject-plan, and tab-separated variants are not decisions but are classified as specification feedback. A focused parser probe returned decision=None, feedback='/approve-plan', context_count=1; an integrated reconcile changed awaiting_approval to a fresh awaiting_approval plan with planner_calls=2, hash_changed=True, zero jobs, and zero workers. An operator can therefore replace the current plan accidentally instead of getting the documented no-op. Narrow the note to the behavior at a9553802, or make the controller ignore every malformed control-command shape and cover bare/tab forms with regression tests.

The PR body changed during this review to cite alfred-code@4cba6bc5c5aeae62e8552068804ae632c1de4b1b. Its claimed full suite is reproducible (Ran 44 tests, OK), but that is one commit after the required baseline. The sole intervening commit is Ignore malformed control commands consistently; its diff broadens _is_feedback to ignore bare/whitespace-separated command forms and adds exactly those missing test cases. Evidence from that later commit cannot establish the claimed behavior at the exact a9553802 review contract.

Scope, contracts, and acceptance

• Final live GitHub, remote branch, and local checkout all resolve to base eaf0802aab77a9bb127790ec7837b3544183a95d and head 318d1559ac82275a4e2b64f9280914139037d223.
• git diff --name-status reports exactly A docs/operators/alfred-code-intake.md; numstat is 66 0, mode is 100644, and git diff --check exits 0. No application code, contract, hook, configuration, workflow, or dependency file changed.
• Live scripts/hooks/lanes.json assigns docs/** to lane V (edges-infra), caps it at 200 LOC, and specifies docker compose config -q; the requested path matches no forbidden-zone glob. Contracts read: lane policy. Contracts changed: none.
• All four issue-requested topics are present. The issue timeline shows plan publication at 2026-07-16T11:55:59Z followed by exact-full-hash owner approval at 12:02:49Z, before implementation. Other operational claims also reproduced at a9553802: no pre-approval job/workspace; unlabel-then-approve launches one job/worker; late rejection leaves it running; Superset TERMINATED changes the job and issue to blocked. The malformed-command claim above remains actionable.

Command evidence

• In an isolated archive of this exact PR SHA, with .env copied from .env.example and the CI dummy values appended, docker compose config -q and docker compose --profile tailscale config -q both exited 0 (unset-variable warnings only).
• PYTHONDONTWRITEBYTECODE=1 python3 scripts/hooks/check_lane.py --ci --lane V --base eaf0802aab77a9bb127790ec7837b3544183a95d → lane V passed, 66 LOC / 1 file, exit 0.
• PYTHONDONTWRITEBYTECODE=1 python3 -m unittest -v scripts.hooks.test_check_lane → 17/17 passed.
• At exact controller a9553802, PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python3 -m unittest -v tests.test_controller tests.test_github tests.test_plans → 28/28 passed; the existing malformed-command test covers truncated space-separated hashes but not bare/tab forms. The focused lifecycle and malformed-command probes above both exited 0 and exposed the mismatch.
• The current PR smoke command at later controller 4cba6bc5 → 44/44 passed, confirming that the PR body is internally reproducible but pinned to the wrong behavior baseline for this review.

Actual CI

At final recheck, GitHub REST reports 16/16 check-run records completed successfully and eight Actions runs completed successfully, with no pending or non-success conclusions. This includes lane-gate, compose-lint, workflow-lint, builds/tests, gitleaks, GitGuardian, and five successful smoke-evidence-check records after PR-body edits. Actual logs show Compose seeded .env from .env.example and ran both profiles; lane-gate resolved the branch to lane V, passed the 66-LOC / 1-file diff, and ran 17 passing gate tests. CI is green but does not test the external controller behavior at the mandated a9553802 commit.