Repository navigation
refactor(skills): break cross-skill cycles by ownership + canonical-blocks drift guard (T4) - #1459
RaduAna-Maria wants to merge 1 commit into
Conversation
…nical-blocks drift guard Cycles (all 3 bidirectional cycles eliminated; allowlist 15 → 10 edges, 0 cycles): - agents ↔ maestro-flow (13 deep links): maestro-flow owns flow-node JSON shapes and flow-variable semantics; uipath-agents owns building/prompting/ deploying the agent. Deep relative links replaced with ownership prose; the documented Skill-invocation handoff carries the transition. No JSON shape was copied across skills — single source of truth preserved. - maestro-flow hitl plugin ↔ uipath-human-in-the-loop (5 links): HITL skill owns schema contracts/conversion rules/app-task variant; plugin keeps its quick reference. Now-pointless self-containment disclaimers deleted. - test → rpa back-link removed (rpa owns pack flags; downstream rpa→test edge kept). hitl planning.md option table aligned with the 2a/2b split. Canonical blocks (drift guard for cross-skill boilerplate): - assets/canonical-blocks/<id>.md + scripts/check-canonical-blocks.py (--write to stamp, --list, --json) + validate-canonical-blocks.yml CI. Skills keep physical copies between BEGIN/END CANONICAL markers; CI fails on byte drift. Documented in CONTRIBUTING.md. - First block uip-cli-resolution stamped in 7 locations. Fixed real bugs found while unifying: /bin/uip appended outside the command substitution in coded-apps and human-in-the-loop (broken path when uip is on PATH), wrong fallback package path in agents lowcode, wrong package name @uipath/uipcli in 4 governance spots, and aligned the install command with hooks/ensure-uip.sh's registry-scope flag Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
Claude finished @RaduAna-Maria's task in 4m 23s —— View job PR Review: Cross-Skill Cycles & Canonical Blocks
SummaryTranche 4 eliminates three bidirectional cross-skill doc cycles (agents ↔ maestro-flow, maestro-flow ↔ hitl, test → rpa back-link) by assigning clear ownership and replacing cross-skill markdown links with prose pointers ("load that skill for X"). It also introduces the canonical-blocks mechanism — a CI-enforced drift guard for shared boilerplate — and uses it to unify the Change-by-Change Review1.
|
| Area | Status | Notes |
|---|---|---|
| Frontmatter | OK | No frontmatter changes in this PR |
| E2E Tests | OK | No new skills added; existing skill behavior unchanged |
| Skill Body | OK | All changes are link→prose replacements and canonical block insertions |
| References & Assets | OK | New assets/canonical-blocks/ directory well-structured |
| Repo Hygiene | OK | No secrets, no personal paths, CODEOWNERS adequate (wildcard covers new paths), scoped changes |
Issues for Manual Review
- Domain accuracy of the canonical block's shell command: The
echo "$(npm root -g 2>/dev/null | sed 's|/node_modules$||')/bin/uip"fallback assumes@uipath/cliinstalls abin/uipbinary under the npm global prefix. Confirm this matches the actual package layout of@uipath/cli— if the binary name or location changed, all 7 occurrences would be wrong simultaneously (the canonical mechanism makes this a single-point-of-failure by design, which is both a strength and a risk). - HITL planning table update (hitl/planning.md:12): The table now lists
uipath.human-in-the-loopwithinputs.type="custom"as an alternative touipath.core.human-task.{key}. Verify this accurately reflects the runtime's current capability.
Conclusion
Clean, well-executed PR. The cycle elimination is thorough — all cross-skill markdown links in the affected files are replaced with prose ownership pointers, and the allowlist ratchet is tightened accordingly. The canonical-blocks mechanism is well-designed (marker-based with CI enforcement, --write for automated stamping, --list for inventory). The first migrated block fixes 4 real bugs. No issues found that would block merge.
Summary
Tranche 4, stacked on #1458. Eliminates all three bidirectional cross-skill documentation cycles via ownership assignment, and introduces the canonical-blocks mechanism — the durable fix for cross-skill boilerplate drift that keeps skills physically self-contained.
Cycles eliminated (allowlist ratchet: 15 → 10 edges, 0 cycles)
scripts/check-cross-skill-links.py'sALLOWED_EDGESshrunk accordingly — CI now blocks reintroduction of any of these edges. Remaining 10 edges are the documented architecture (platform-IS, governance→admin, rpa→solution/test chain, hitl→tasks).Canonical blocks
New mechanism preserving the isolation rule while killing drift: each skill keeps its own physical copy of shared boilerplate between
<!-- BEGIN/END CANONICAL: <id> -->markers;assets/canonical-blocks/<id>.mdis the single source;scripts/check-canonical-blocks.py(CI:validate-canonical-blocks.yml) fails on any byte drift;--writere-stamps all copies. Documented in CONTRIBUTING.md.First migrated block:
uip-cli-resolution(7 occurrences across agents, coded-apps, governance ×2, human-in-the-loop, maestro-case, maestro-flow). Unifying the copies surfaced 4 real bugs the drift had already caused:/bin/uipappended outside the command substitution in coded-apps and human-in-the-loop — produces a broken path wheneveruipIS on PATHnode_modules/uip/bin/uip) in agents lowcode@uipath/uipcliin 4 governance locations (the real package is@uipath/cli)--@uipath:registryscope pin thathooks/ensure-uip.sh(the actual SessionStart installer) deliberately applies — canonical block now matches the hookValidation
scripts/check-canonical-blocks.py— OK, 1 block, 7 occurrences byte-identicalscripts/check-cross-skill-links.py— OK with the shrunken allowlistscripts/check-skill-status.py— OK; description hook — all pass🤖 Generated with Claude Code