feat: Workflow Composition API — compose_serial, trim_nodes, describe_nodes

[akashgit]

Closes #961

Changes

• New module factory/workflow/composition.py with 6 functions:

  • prefix_nodes(wf, prefix) — namespace all node IDs with a prefix
  • find_terminal_nodes(wf) — discover nodes with no unconditional outgoing edges
  • compose_serial(w1, w2, ...) — chain two workflows end-to-end with ID conflict detection
  • trim_nodes(wf, node_ids) — remove linear nodes and auto-reconnect predecessors to successors
  • validate_composition(wf) — graph validation + composition-specific checks (fork targets, join sources)
  • describe_nodes(wf, use_llm=False) — topo-sorted node introspection with fast extraction or LLM-powered summaries

• 18 comprehensive test cases using real workflows (discover, build, improve, review) from definitions.py

• Create mode integration — updated Builder and Strategist prompt_template fields in create_workflow() to reference composition functions. SKILL.md files auto-regenerate at runtime via the Pydantic → export-skills pipeline

• README documentation — added Composition section with API table, chaining/trimming examples, ID conflict resolution, and constraints

Test plan

• All 18 composition tests pass (pytest tests/test_workflow_composition.py -v)
• 202 workflow/model tests pass with no regressions
• ruff check clean on all changed files
• mypy clean on factory/workflow/composition.py
• validate_composition() passes on all 13 registered workflows
• Create mode SKILL.md regeneration verified — composition guidance propagates to Strategist and Builder steps

🤖 Generated with Claude Code

[github-actions]

Sentrux Quality Report

Absolute

Scanning ....
[scan] git ls-files: 375 total, 363 kept, 12 dropped (ext:12, meta:0, big:0)
[build_project_map] 363 files, 64 unique dirs, 58 cache misses, 2.7ms
[resolve] 558 resolved, 905 unresolved (of 1463 total specs)
[resolve_imports] project_map 2.8ms, suffix_idx 0.6ms, suffix_resolve 8.5ms, total 11.9ms
[build_graphs] 363 files | maps 1.3ms, imports 12.0ms, calls+inherit 2.2ms, total 15.5ms | 557 import, 4304 call, 0 inherit edges
sentrux check — 3 rules checked

Quality: 4555

✗ [Error] max_cc: 5 function(s) exceed max cyclomatic complexity of 30
    factory/cli/ceo.py:cmd_ceo (cc=93)
    factory/study.py:study_project_local (cc=43)
    factory/cli/_wizard.py:_welcome_wizard (cc=39)
    factory/cli/ceo.py:cmd_run (cc=37)
    factory/workflow/validation.py:validate_workflow (cc=31)

✗ 1 violation(s) found

Diff (vs base branch)

Scanning ....
[scan] git ls-files: 375 total, 363 kept, 12 dropped (ext:12, meta:0, big:0)
[build_project_map] 363 files, 64 unique dirs, 58 cache misses, 2.8ms
[resolve] 558 resolved, 905 unresolved (of 1463 total specs)
[resolve_imports] project_map 2.8ms, suffix_idx 0.6ms, suffix_resolve 8.2ms, total 11.6ms
[build_graphs] 363 files | maps 1.1ms, imports 11.7ms, calls+inherit 2.3ms, total 15.1ms | 557 import, 4304 call, 0 inherit edges
sentrux gate — structural regression check

Quality:      4562 -> 4555
Coupling:     0.79 → 0.79
Cycles:       5 → 5
God files:    2 → 2

Distance from Main Sequence: 0.31

✗ DEGRADED
  ✗ Complex functions increased: 33 → 35

[codecov]

Codecov Report

❌ Patch coverage is 87.62542% with 37 lines in your changes missing coverage. Please review.
✅ Project coverage is 87.97%. Comparing base (48e2e15) to head (9ad6827).

Files with missing lines	Patch %	Lines
factory/workflow/composition.py	87.62%	37 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #962      +/-   ##
==========================================
- Coverage   87.98%   87.97%   -0.01%     
==========================================
  Files         104      105       +1     
  Lines       13316    13615     +299     
==========================================
+ Hits        11716    11978     +262     
- Misses       1600     1637      +37     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.