宜博 / lemongraph

New skills/work-graph-node-review/SKILL.md documents the methodology for
judging a self-planned Work Graph node's output (real structured content
vs. narrative prose standing in for it) -- distilled from the real
narrative-output incident (docs/todo/validator-test-script-narrative-
output-issue.md §6) and the conditional-not-assertive phrasing lesson
already applied in _NARRATION_RETRY_HINT. Scoped explicitly against
planner-output-review (Planner's fixed doc chain, task-level gate),
qa-task-validation (overall task acceptance), and skill-defect-remediation
(rewriting a Skill file itself) -- this one judges a single self-planned
node's output, nothing broader.

Wired into roles/planner_reviewer, roles/coder, roles/validator role.json
skills lists. .claude/agents/*.md left untouched -- that's a deploy-time
artifact compiled from role.json by agent_profile.deploy_agent_definitions(),
not hand-synced (confirmed stale already: coder.md is missing an even
earlier Phase 2a skill addition).

This completes Phase 2c (§2.1/§2.2/§6/§7.1 all implemented; §7.2's
analysis was completed earlier without needing a code change).

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

A merged graph's one run genuinely spans several org_nodes now (Planner/
Coder/Validator all append their own nodes into the SAME run) -- a single
run-level org_node column was never accurate once Phase 2b/2c landed, and
real per-node ownership already lives in work_node_execution.subagent_type.

Schema: work_graph_run.org_node column removed; ux_work_graph_run_active
narrowed from UNIQUE(task_id, org_node) to UNIQUE(task_id) WHERE status
NOT IN ('done', 'failed') -- 'blocked' now counts as active on purpose,
since resuming a blocked run always appends into the same row rather than
inserting a fresh one. New migrate_drop_work_graph_run_org_node() handles
already-populated databases, wired into backend_server.py's startup path.

Call sites updated: work_graph_plan.py/work_graph_fork.py/
root_cause_trace.py's INSERTs; work_graph_run_query.py/task_query.py now
return "org_nodes_involved" (derived from work_node_execution.subagent_type)
instead of the removed single-value "org_node"; frontend/app.js's org-strip
and run-list rendering updated to the list-based shape.

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

Validator's terminal verdict is now a real self-planned node (node_type=
'final_verdict', judgment.kind='mechanical', on_fail.action=
'dynamic_loop_back') appended into the SAME shared work_graph_run Planner
and Coder already contribute to (plan_work_graph(..., append_to_run_id=
run_id)), instead of a flat post-graph org_node_trigger call against a
separate hardcoded Validator manifest. This is what lets a failing verdict
genuinely trigger Reflection-review + Fix-Skill + a precise loop back to
whichever real ancestor node is at fault, reusing the existing
dynamic_loop_back machinery instead of a parallel retry loop.

The 2026-08-06 hard gate (a real non-zero exit from Validator's own test
script force-overrides the verdict to FAIL, Python-enforced not just
prompted) is preserved via a build_prompt wrapper + mechanical check
closure sharing mutable state. INCONCLUSIVE is now treated the same as
FAIL (triggers a bounded retry via dynamic_loop_back) rather than accepted
as a terminal result.

_VALIDATOR_MANIFEST/_VALIDATOR_DOC_PROMPTS/_VALIDATOR_VERDICT_PROMPT/
_validator_prompt_builder are kept unused (same precedent as _CODER_PROMPT).
org_node column removal (§2.1), index narrowing (§2.2), and the new
work-graph-node-review skill (§7.1) remain for a later sub-phase.

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

Updates the Phase 2 SDD and requirements doc to reflect that Phase 2a
(86fc0bb) and Phase 2b (7c46a2f) are done, not just designed. Records the
concrete deviations/fixes found during implementation that the original
design didn't anticipate: the run_id=None bug in the artifact-reuse resume
path, the missing needs_worktree=True on Coder's run_graph() call, why
§2.2's index narrowing needed to move from "maybe safe after 2b" to
"actually needs 2c", and the test-fixture check_same_thread=False gap
concurrent merged-graph layers exposed.

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

Design for org-graph-unification-and-universal-self-planning-requirements.md
§3.1's step 3, previously flagged as the largest known gap in the Phase 2 SDD.

Extends §5.4's Reflection-review to judge both a target node AND a
defect_kind (content_error vs skill_defect), adds §5.5 Fix-Skill (a real
Validator-identity call rewriting the target node's skill_ref content, via
the existing but never-wired-up skill_update.py::update_skill() +
bug_record.create_bug_record()), and confirms Re-loop needs no new
mechanism -- the existing _LoopBackRequested path already re-runs the
target node, which picks up the new skill content automatically since
Claude Code loads Skill content by name at call time, not at agent
frontmatter deploy time.

Two findings during design that motivated/validated this work:
- org_level_loop.py's _ROUTE_FOR_CATEGORY has no 'skill_defect' key --
  skill_update.update_skill() has never been called by any production
  path despite root_cause_trace.py being able to classify skill_defect
  since U-015. Fix-Skill is the first time this dead capability gets wired
  up for real, via a new path, not by fixing the old one.
- execution_event.event_type's CHECK enum has had an unused 'skill_iterated'
  value since the original U-001 schema -- no new migration needed to log
  Fix-Skill events.

Also found and recorded a third work_graph_run.org_node call site
(root_cause_trace.judge_root_cause_via_work_graph) that §2.1's column-
removal missed.

Confirmed via AskUserQuestion: the Skill-rewrite call always runs under
the Validator identity, regardless of which org_node's skill is being
fixed -- avoids the self-correcting-its-own-blind-spot problem, and
matches skill_update.py's own "a Validator-triggered rewrite" docstring
intent from 03-C.

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

Phase 1 (planner_reviewer review gate + P0 resume-bug fix) shipped as
ea19c7d, matching org-graph-unification-phase1-review-gate-design.md
exactly (new task.status value, org role, _REQUIRED_ARTIFACTS narrowing,
both bugs fixed). Moving that design doc and the P0 bug doc it subsumed
to docs/done/, updating their status headers, and fixing the doc-path
references left pointing at their old docs/todo/ location across
agents/planner_reviewer/{SOUL,AGENTS}.md, src/schema.py migration
docstrings, and the other Phase 2/deblackbox docs. Full suite green
(731 tests) both before and after.

Also ran Phase 2 SDD's §9 interface-reconciliation checklist against the
real Phase 1 implementation now that it exists for real: all three items
check out (run_id is included in plan_and_review_documents()'s return
shape, the new task.status value is exactly reviewing_planner_output as
assumed, and planner_reviewer's role.json doesn't pre-reserve a skill
slot for Phase 2's new skill, which is fine -- a one-line addition when
Phase 2c lands, not an incompatibility). Updated §9 to reflect this.

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

User's key insight, recorded as a goal in the requirements doc (new §3.1):
a failed node shouldn't just get a corrective retry (fix-bug, forgotten
after this run) -- when the root cause is a systemic Skill defect, the
Skill itself must be fixed (fix-skill, persists across all future tasks).
Four-step chain: judgment fails -> Reflection-review node does full-chain
root-cause diagnosis (one-off content error vs systemic skill defect) ->
if systemic, a Fix-skill node calls the already-existing skill iteration
machinery (skill_update.py::update_skill() + bug_record.py, real Git-
versioned commits, previously only reachable via org_level_loop.py's
coarse Org-level path, never from inside a Work Graph's own judgment/
loop_back cycle) -> loop back and re-run using the updated skill.

Cross-referenced into the Phase 2 design doc: its dynamic_loop_back (§5)
implements steps 1/2/4 of this chain but not step 3 (Fix-skill) -- flagged
as the largest known scope gap in §8, not a missed detail.

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

Design for FR-2/FR-3/FR-4: extending self-planning to Coder/Validator,
per-node subagent/skill/tools binding, and node-level precise loop_back
replacing org_level_loop.py's coarse fast_lane/full_replan routing.

Three findings during design research that revise the requirements doc's
original FR-2 assumption ("just swap the call site"):
- _GENERIC_PROMPT_TEMPLATE never solicits judgment/on_fail today -- Coder/
  Validator switching to plan_work_graph() as-is would produce graphs with
  no judgment/loop-back capability at all.
- run_graph()'s subagent_type/skill_ref are run-level constants passed to
  every node identically, not node-level despite work_node_execution
  already having columns for it -- needs a real (bounded) engine extension.
- Today's on_fail.action="loop_back" target is statically declared at
  planning time via a single on_failure edge; it cannot express "a
  terminal validator dynamically diagnoses which of several ancestor
  nodes is the true root cause." New on_fail.action="dynamic_loop_back"
  designed for this, reusing root_cause_trace.py's jury/majority-vote
  structure with the vote target changed from a category to a node_id.

Also incorporates three requirements-doc §7 decisions that were made
(apparently concurrently) while this was being designed and overrule two
of this doc's initial drafts: work_graph_run.org_node is removed entirely
(not kept/sunk to node level) with concrete work_graph_run_query.py/
work_graph_fork.py rework; Coder/Validator get a suggested node-type
catalog (not fully free-form); the append interface is a parameter on
the existing plan_work_graph() (not a new function).

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