宜博 / lemongraph

Implements docs/done/work-graph-node-execution-deblackbox-requirements.md
end to end. The three documented call sites (e2e_pipeline.py::
_check_prd_consistency, work_graph_orchestrate.py::_llm_judgment_verify_fn,
work_graph_orchestrate.py::_make_run_fn) all used to render a one-off
Dynamic Workflow .js script and run it via `claude -p 'Run /<name>...'`
purely to get "agent identity + schema-shaped output" -- a workaround for
--json-schema silently conflicting with --agent (05 §5.4.1.1). That
workaround was never actually necessary: work_graph_plan.py::
plan_work_graph() solved the identical problem from day one with a flat
`claude --agent ... -p ...` call + ```json-fence extraction from free text,
already validated in production.

New org_node_trigger.trigger_org_node_structured() unifies all three call
sites onto that same flat-call approach. extract_json_payload() generalizes
work_graph_plan.py's fence-extraction algorithm; _extract_graph_manifest is
now a thin wrapper over it. Two more call sites not in the original design
doc (written before they existed) were found and migrated too:
_run_reflection_perspective and _fix_skill_for_node (Phase 2a's
Reflection-review/Fix-Skill). work_graph_fork.py needed no changes -- it
only reaches _make_run_fn indirectly via run_graph(), so it benefits
automatically.

FR-4's real-agent verification (RUN_REAL_AGENT_E2E=1, mandatory, not
optional -- src/test_org_node_trigger_e2e.py) confirmed persona loading,
--model override, and JSON-fence extraction all work against a real model.

write_workflow_script/execute_work_graph/execute_work_graph_with_usage_
limit_retry are confirmed to have no remaining production callers;
docstrings mark them historical, the file is kept (not deleted).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Re-checking REQ-14's boundary case against the letter of its text found a
real functional gap, not just a testing gap: U-013's opus handling only
did "skip backoff" -- it never actually retried on a downgraded model,
just failed immediately. REQ-14 boundary says "不走退避轮询，直接降级到非
Opus 模型重试" (skip backoff, retry immediately on a non-opus model) --
the retry was the part that was missing.

Fixed: run_fn's signature is now run_fn(cwd, model=None); an opus quota
signal retries immediately (no backoff) with opus_downgrade_model
(default "claude-sonnet-5"). If the downgraded model somehow also reports
an opus signal (shouldn't happen -- it's not using Opus), this doesn't
loop forever chasing it, raises UsageLimitWaitTimeoutError instead.

work_graph_execute.py's own opus handling (U-012) deliberately NOT changed
to match: REQ-14's coverage only names c_work_node_run/c_org_node_trigger,
and that mechanism (a multi-agent dynamic workflow, no single top-level
--agent identity) has no one "the model" to downgrade -- a deeper A-1
question, documented as out of scope rather than silently left
inconsistent without explanation.

Also filled in a real test gap: quota_limit_type=weekly (detection +
recovery, and the 9-day timeout) was never tested despite the mechanism
already supporting it since U-013.

11 new/changed stdlib unittest cases across work_node_run.py's test suite
(all existing run_fn lambdas updated for the new signature). 178 total
across U-001-020, all passing.

This closes PH2-S3 alongside U-019. REQ-14 is now genuinely complete, not
just "mostly right."

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

judge_root_cause(): runs 3 perspective_fns (correctness/requirement-
completeness/skill-defect, 04-P §4.3), requires >=2/3 agreement on a
category or raises InconclusiveEscalateError with all raw judgments
attached (REQ-04's failure case). trace_root_cause_test_failed() creates a
brand-new bug_record on agreement; trace_root_cause_human_reported()
field-completes an existing one instead (04-P's explicit distinction
between the two origins, not a new record either way).

c_bug_record_create (bug_record.py): validates root_cause_category against
{planning, coder, skill_defect} -- core_engine deliberately excluded,
matching U-001's schema CHECK constraint (PH5/U-034 scope). Known,
deliberately-unenforced gap noted rather than guessed at: 03-C §3.10's
"skill_defect requires creating a skill_iteration_suggestion" constraint
can't be satisfied yet (skill_iteration.before/after_git_commit_sha are
NOT NULL but don't exist until a real skill rewrite happens in U-018) --
REQ-04's three cases never exercise skill_defect, so nothing here needs it
resolved yet.

real_validator_perspective() builds a real claude --agent validator call
framed from one of the three perspectives, parsing a CATEGORY:/DETAIL:
response format.

Also fixes a real diagnostic bug found investigating an unrelated failure:
org_node_trigger.py/work_graph_plan.py/work_graph_execute.py's nonzero-exit
error paths only included stderr in the raised exception, silently
dropping stdout -- which is where a real `claude` failure's actual detail
often lives. A real Coder call failed with exit 1 and empty stderr,
giving zero diagnostic signal; fixed to include both streams (truncated).

18 new mocked stdlib unittest cases + 1 gated real test (3 real Validator
perspective calls judging a deliberately-injected wall-collision bug,
expecting agreement on root_cause_category=coder). 146 total mocked tests
across U-001-015, all passing.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Extends U-006's execute_work_graph in place (same controller, being
completed, not a parallel module):
- ClassifierBlockedError: raised when a response's permission_denials array
  has >=3 entries (03-C §3.5 says "3 consecutive or 20 cumulative" -- true
  cross-call cumulative tracking needs persistence U-013 doesn't provide
  yet, so this is a documented, conservative per-call approximation).
- UsageLimitReachedError (carries quota_limit_type) + a new
  execute_work_graph_with_usage_limit_retry() implementing p_usage_limit_wait
  (04-P §4.4.1): 5->10->20->30min backoff (repeating at 30) for
  session/weekly quota hits, timeout after 8h/9d -> UsageLimitWaitTimeoutError;
  opus quota hits skip backoff and fail immediately (model-downgrade retry
  is a caller decision, not this function's). sleep/now are injectable so
  tests don't block on real waits.

Retry operates at the whole-work-graph-call level, not per individual
work_node_execution row -- U-013 (c_work_node_run, which actually owns that
table) doesn't exist yet, so node-level quota tracking isn't attempted
here; noted explicitly in development-plan.md rather than silently
simplified.

Also corrects the same class of Done-line overreach as U-009/U-010/U-011
(4th occurrence): REQ-07's happy case literally asks for REQ-01~06 all
passing end to end, which needs PH2 (Validator root-cause tracing, Org-level
Loop, breakpoint recovery) -- U-012 only owns REQ-07's boundary/failure and
REQ-14's happy case, which was already correctly scoped.

23 new/changed mocked stdlib unittest cases (existing U-006 tests untouched
and still passing -- subclassing WorkGraphExecuteError keeps them
backward-compatible). 107 total mocked tests across U-001-012, all passing;
both existing real-agent tests (U-006's reused spike, U-011's planner call)
re-verified against the refactored code.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

write_workflow_script(): writes an orchestration script to
<target>/.claude/workflows/<name>.js -- versioned with the target project's
own git history, not graphlemon's (03-C §3.5 step 1).

execute_work_graph(): `claude -p 'Run /<name> with args {...}' --output-format
json --json-schema <schema> --permission-mode auto`, no `--bare` (A-1 spike:
skips credential discovery, breaks headless invocation), never
bypassPermissions. Returns structured_output. No budget-usage bookkeeping
or CLASSIFIER_BLOCKED handling yet -- U-012's job ("骨架" here).

Real-call coverage reuses spikes/a1-dynamic-workflows/workflow-under-test.js
verbatim (read from that file, not retyped) through the new wrapper --
"直接复用已验证的代码路径" per development-plan.md U-006, not just citing the
old spike as prior art. Confirmed passing for real: same result as the
original spike (sum=29 for [2,3,4]).

8 new mocked stdlib unittest cases + 1 gated real-agent test. 53 total
mocked tests across U-001-006, all passing; both gated real-agent tests
(U-004/U-005's planner call, U-006's reused spike workflow) re-verified
manually this session.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>