宜博 / lemongraph

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>

Inserts Planner -> planner_reviewer -> Coder -> Validator into the fixed Org
Graph flow (was Planner -> Coder -> Validator), per
docs/todo/org-graph-unification-phase1-review-gate-design.md. A new
planner_reviewer role independently judges whether Planner's BRD/PRD/SDD/
Benchmark output is real structured content (not narrative prose) before
Coder is allowed to start, with a 3-attempt retry loop and a narration
heuristic informed by the real narrative-output incident
(docs/todo/validator-test-script-narrative-output-issue.md).

Also fixes, in the same code path:
- The P0 bug in task-execution-resume-assumes-planner-artifacts-exist.md:
  resuming a task no longer assumes sdd/prd/benchmark artifacts exist --
  falls through to real replanning when they don't.
- A fresh-run KeyError (not resume-specific) when a self-planned graph omits
  the prd/benchmark node types.
- agent_profile.migrated_from_profile was NOT NULL, which broke as soon as a
  role with no legacy Hermes profile (planner_reviewer) was recorded.

org_node_lifecycle._REQUIRED_ARTIFACTS["coder"] is narrowed from
(brd,prd,sdd,benchmark) to (sdd,) -- the old 4-artifact gate never actually
blocked anything since artifact_write.py sets validation_status='passed'
unconditionally; planner_reviewer is the first real semantic gate.

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>

… work, compress bloated incident log

- Delete org-graph-as-work-graph-unified-loop-requirements.md: fully
  superseded by org-graph-unification-and-universal-self-planning-
  requirements.md; folded its one non-duplicated detail (the 2084590a
  benchmark-narration trigger incident) into that doc's background instead.
- Split scheduler-production-polling-loop-{requirements,design}.md by
  completion status: FR-2 (in-flight task reconciliation, shipped) moves to
  docs/done/scheduler-task-reconciliation-{requirements,design}.md; FR-1
  (new-goal auto-dispatch, still undecided) becomes a small standalone
  docs/todo/scheduler-new-goal-dispatch-requirements.md instead of staying
  bundled with a doc that's mostly done.
- Compress validator-test-script-narrative-output-issue.md's six
  ad-hoc "第N轮更新" paragraphs crammed into one status line into a scannable
  timeline table; moved the task 2084590a benchmark evidence into §1 where
  the other repro examples live instead of leaving it stranded in the header.
- implementation-gap-analysis.md: logged two new gaps found today (no
  pre-Coder review of Planner's output; node execution still depends on
  native Dynamic Workflow) plus the architecture.md §10.1 staleness itself,
  per that doc's own "edit in place" maintenance convention.
- Updated the doc-path references left in src/task_execution.py and
  src/task_reconciliation.py docstrings to point at the new locations.

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

- org-graph-unification-phase1-review-gate-design.md: implementable SDD for
  inserting a planner_reviewer stage (new org role, since _PRE_STATE/
  _POST_STATE map org_node -> status 1:1 and can't reuse "validator" twice)
  between Planner and Coder. Folds in the P0 resume-artifact-assumption fix
  and a newly-found sibling KeyError in the fresh-run path.
- graphlemon_architecture.md §10.2: records that §10.1's "方案 A" (reuse
  Claude Code's native Dynamic Workflow for Work Graph execution) was
  superseded -- the graph-orchestration layer already diverged (REQ-06
  checkpoint/resume), and per today's decision the single-node execution
  layer is being migrated off it too, for controllability.
- work-graph-node-execution-deblackbox-requirements.md: requirements+design
  for that migration -- replace the 3 remaining write_workflow_script/
  execute_work_graph call sites with plan_work_graph()'s already-proven
  flat `claude --agent` + JSON-fence-extraction pattern.
- Cross-referenced the two new docs from each other and from the existing
  P0/P2 todo docs they fold into or relate to.

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

Merges the fixed-flow change (Planner -> Validator -> Coder -> Validator),
universal per-org-agent self-planning, node-level validator skill, and
frontend dynamic/historical graph asks into one requirements doc, folding
in the P0 resume-artifact bug and the P2 test_script structural-fix
placeholder that were blocking on the same design. Records the user's
2026-08-08 decision to merge all four org stages into one work_graph_run
(scheme A) rather than cross-graph routing (scheme B), plus the concrete
schema conflicts that decision surfaces (work_graph_run.org_node's single
value + unique-active-run index) for Phase 2's SDD to resolve.

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

work-graph-partial-artifact-persistence and work-graph-self-planning-
and-loop-back (requirements + design) are all shipped and tested;
move them out of docs/todo/ and fix up the docs/todo/*.md and
src/*.py path references that pointed at their old location.

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

Real end-to-end verification of Work Graph self-planning + loop-back
(task 2084590a) hit the narrative-output problem again -- this time on a
self-planned benchmark node, not test_script, disproving the earlier
"BRD/PRD/SDD/Benchmark won't recur" hypothesis in validator-test-script-
narrative-output-issue.md. The judge caught it once (round 3) but couldn't
force a fix; the loop_back retry limit correctly exhausted and blocked the
task cleanly instead of hanging or crashing.

Also drafts org-graph-as-work-graph-unified-loop-requirements.md: extending
today's Work-Graph-internal judgment/on_fail/loop_back mechanism up to the
Org Graph itself, so Coder doesn't start from an unreviewed Planner output
and a Validator FAIL can route to a precise node instead of a whole phase.
Flags the real hard part (Planner/Coder each plan their own graph_manifest,
so node ids don't share an address space across the org boundary) as the
first open question, not yet implemented.

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

v_task_board's task_id cell now links to #/graph?task_id=<id> for quick
navigation to a task's execution graph. v_graph_console reads that param
to preselect the task, and syncs the URL (via history.replaceState) on
every task load -- including the initial auto-preselect -- so the address
bar always reflects the task actually showing.

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

…76ae-main-checkout-drift

…4843-main-checkout-drift

ConsistencyCheckFailedError is now raised by both the PRD-consistency
check and the test_script mechanical compile-check (07a0a27), but
scheduler._blocked_reason_for still labeled every instance
'prd_consistency_check_failed', misleadingly blaming the PRD for
test_script node failures. Distinguishes by node_id substring match
(see docstring for the ponytail ceiling/upgrade path).

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

Mitigates the recurring test_script/validator_test_script narration issue
(100% repro across 3 tasks, 6 nodes): the existing compile-error feedback
buries its "not a narrative description" note under raw tracebacks, which
wasn't enough to stop the model repeating narrative output on retry. Adds
_NARRATION_RETRY_HINT as a separate, directive feedback item alongside the
compiler detail. See docs/todo/validator-test-script-narrative-output-issue.md
§6-7 for the full root-cause analysis and rationale.

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

…9789-main-checkout-drift

…d4ef-main-checkout-drift

…bbe3-main-checkout-drift