From 26728c89fb347edca309eda131297e4f7ae75720 Mon Sep 17 00:00:00 2001 From: Erik LaBianca Date: Wed, 22 Jul 2026 18:23:14 -0400 Subject: [PATCH 1/3] feat(skill): dual-path engagement and desired-state align contracts Keep Skill(helix) first-class on skill-tool hosts; define SKILL.md load as engagement on hosts without a skill tool. Encode desired-state with intent guard, four-field handoffs, and evidence-gated implement work in Align, Polish, alignment-review template, and reconcile/polish actions. Closes helix-da73534f (PR2). --- .ddx/beads.jsonl | 2 +- skills/helix/SKILL.md | 75 +++++++++++++++++------- workflows/actions/polish.md | 11 ++++ workflows/actions/reconcile-alignment.md | 9 +++ workflows/templates/alignment-review.md | 14 ++++- 5 files changed, 85 insertions(+), 26 deletions(-) diff --git a/.ddx/beads.jsonl b/.ddx/beads.jsonl index f1c79228..a51e2d92 100644 --- a/.ddx/beads.jsonl +++ b/.ddx/beads.jsonl @@ -588,7 +588,7 @@ {"acceptance": "Normative workflow docs can be read without knowing DDx; DDx commands appear only in integration/appendix sections; skill naming guidance no longer requires all public skills to mirror HELIX CLI commands; authority order and artifact loop remain intact.", "created_at": "2026-05-12T04:41:46.767528957Z", "description": "Refactor workflows/README.md, workflows/REFERENCE.md, and related phase docs so the normative methodology is runtime-neutral. Move CLI mirroring, ddx bead, execute-loop, tracker queue, and wrapper guidance into explicit DDx integration appendices or transitional docs.", "events_attachment": "helix-d8f307d4/events.jsonl", "execute-loop-cooldown-base-rev": "34d5c2fd13fd9ff7ddc38d1f8e765aa2d86ff1fb", "execute-loop-failed-routes": [{"actual_power": 5, "at": "2026-05-14T17:17:45Z", "model": "Qwen3.6-27B-MLX-8bit", "provider": "grendel-omlx", "reason": "provider_connectivity"}], "execute-loop-last-detail": "agent: provider error: openai: Post \"http://grendel:1235/v1/chat/completions\": dial tcp 100.97.179.68:1235: i/o timeout", "execute-loop-last-status": "execution_failed", "execute-loop-retry-after": "2026-05-14T17:32:45Z", "id": "helix-d8f307d4", "issue_type": "task", "labels": ["helix", "activity:build", "kind:implementation", "area:workflow", "area:docs"], "parent": "helix-f9207605", "priority": 1, "schema_version": 1, "spec-id": "helix.prd", "status": "closed", "title": "Split workflow docs into runtime-neutral methodology and DDx integration appendices", "updated_at": "2026-05-14T19:18:21.389729355Z"} {"acceptance": "README.md, website/content/docs/getting-started.md, website/content/docs/cli/_index.md, and website/content/docs/demos/_index.md present `helix input` plus `ddx agent execute-loop` as the default path and label `helix run` / `helix build` as compatibility surfaces; the quickstart demo docs are aligned with that contract; `hugo --gc --minify` succeeds from website/.", "claimed-at": "2026-04-11T06:50:27Z", "claimed-machine": "eitri", "claimed-pid": "3349776", "created_at": "2026-04-11T02:25:07.402535676Z", "description": "\nDesign for Change · Design for Simplicity · Validate Your Work · Make Intent Explicit · Prefer Reversible Decisions\nhugo-hextra | demo-asciinema | e2e-playwright\nDefine the site's target audience and what content they need · Theme version: Hextra v0.12.1 — pinned in website/go.mod · Identify which workflows need demo reels — prioritize the \"first 5 minutes\" experience · Current demos: helix-quickstart (full lifecycle), helix-concerns (drift detection), helix-evolve (requirement threading), helix-experiment (metric-driven optimization) · Identify all user-facing pages and workflows that need testing · Test location: website/e2e/microsite.spec.ts\nADR-001 HELIX Supervisory Control Model — Supervision must remain live to concurrent local operator activity. A running helix-run session must treat tracker and governing-artifact changes as new control input at safe boundaries. It may not assume that the selected issue is still valid at claim time or close time just because it was valid earlier in the loop. Why: HELIX must preserve bounded execution, authority order, tracker-first work management, and direct interactive operation. It must also reduce orchestration burden by autonomously selecting the least-powerful sufficient next action when authority is available. · ADR-002 HELIX Tracker Write Safety Model — The tracker will not pretend to provide arbitrary multi-writer transactional semantics. Instead, it will define the supported local execution model, require explicit detection or prevention of silent lost updates, and make malformed tracker state a surfaced failure rather than something the rest of HELIX must guess around. Why: HELIX needs a conservative local tracker that is safe enough for agent-driven issue refinement and concurrent local supervision. The tracker must surface malformed state explicitly, define what concurrency/conflict guarantees are supported, and make metadata mutation available through first-class commands instead of direct file edits.\nwebsite/content/docs/getting-started.md — HELIX adds the methodology on top — the development phases (Frame → Design → Test → Build → Deploy → Iterate), the authority order that resolves conflicts between artifacts, the bounded execution loop that decides what to do next, and the skills that turn all of this into agent instructions. You install DDx first, then install HELIX as a DDx package.\n\n\nReview finding from fresh-eyes review.\nFile: website/content/docs/getting-started.md:90\nCategory: drift\nSeverity: medium\nDescription: Commit 466924b changes the governing contract to say new docs, quickstarts, plugin docs, and demos should prefer `helix input` plus `ddx agent execute-loop`, but the public surfaces still teach the legacy path: README.md starts with `/helix-run`, website/content/docs/getting-started.md and website/content/docs/cli/_index.md present `helix run` as the primary entrypoint, website/content/docs/demos/_index.md still describes demos as `ddx agent run` driven, and docs/demos/helix-quickstart/README.md keeps the old frame/design/build/review narrative. This violates the active hugo-hextra sync requirement that workflow-rule changes update the corresponding microsite pages in the same pass, leaving public guidance on the superseded execution path.\nSuggested fix: Update README, the microsite Getting Started / CLI / Demos pages, and the quickstart demo docs or script so they present `helix input` plus `ddx agent execute-loop` as the default path while labeling `helix run` / `helix build` as compatibility wrappers.", "id": "helix-d903a854", "issue_type": "task", "labels": ["helix", "activity:build", "review-finding", "area:demo", "area:docs", "area:site"], "owner": "erik", "priority": 0, "schema_version": 1, "spec-id": "website/content/docs/getting-started.md", "status": "closed", "title": "drift: update public quickstarts and demos for DDx queue-drain default", "updated_at": "2026-04-11T06:58:53.626005758Z"} {"acceptance": "scripts/validate_context_digests.py accepts HELIX beads that carry the documented explicit omission rationale, still rejects open HELIX beads with neither a digest nor a rationale, tests/validate-context-digests.sh covers both cases deterministically, and git diff --check passes.", "claimed-at": "2026-04-11T05:34:49Z", "claimed-machine": "eitri", "claimed-pid": "3100590", "created_at": "2026-04-11T00:34:03.654373258Z", "description": "\nDesign for Change · Design for Simplicity · Validate Your Work · Make Intent Explicit · Prefer Reversible Decisions\nhugo-hextra | demo-asciinema\nDefine the site's target audience and what content they need · Theme version: Hextra v0.12.1 — pinned in website/go.mod · Identify which workflows need demo reels — prioritize the \"first 5 minutes\" experience · Current demos: helix-quickstart (full lifecycle), helix-concerns (drift detection), helix-evolve (requirement threading), helix-experiment (metric-driven optimization)\nscripts/validate_context_digests.py — def main() -> int: parser = argparse.ArgumentParser( description=\"Validate that open HELIX beads carry a context digest.\" ) parser.add_argument( \"--tracker\", default=\".ddx/beads.jsonl\", help=\"Tracker JSONL path (default: .ddx/beads.jsonl).\", ) parser.add_argument( \"--status\", action=\"append\", default=[], help=\"Status to validate (repeatable, default: open).\", ) args = parser.parse_args()\n\n\nReview finding from fresh-eyes review.\nFile: scripts/validate_context_digests.py:47\nCategory: correctness\nSeverity: medium\nDescription: The new validator rejects every open HELIX bead whose description lacks a block, but the updated FEAT-006 contract and workflows/actions/input.md:84-85 explicitly allow an open bead to carry an explicit omission rationale when the contract permits omission. Reproducing against a temp tracker entry whose description is 'Explicit omission rationale: ...' exits 1 and reports the bead as invalid. That means the new validation gate can fail on queue entries that satisfy the documented omission path instead of the missing-digest failure mode it is supposed to catch.\nSuggested fix: Teach the validator to recognize the documented explicit-omission-rationale path, define the allowed marker/format in the contract if needed, and add deterministic fixtures that prove rationale-bearing beads pass while truly missing digests still fail.", "id": "helix-d9f93a59", "issue_type": "task", "labels": ["helix", "activity:build", "review-finding", "area:artifacts", "area:docs", "area:testing", "area:workflow"], "owner": "erik", "priority": 0, "schema_version": 1, "spec-id": "scripts/validate_context_digests.py", "status": "closed", "title": "correctness: allow explicit digest-omission rationale in validator", "updated_at": "2026-04-11T05:37:38.845469698Z"} -{"acceptance": "1. skills/helix/SKILL.md still contains Skill(helix) engagement requirement for skill-tool hosts.\n2. skills/helix/SKILL.md documents non-skill-tool host engagement via loading SKILL.md body.\n3. python3 -c \"import yaml; t=open('skills/helix/SKILL.md').read(); fm=yaml.safe_load(t[4:t.find(chr(10)+'---'+chr(10),4)]); assert len(fm['description'])<=1024\"\n4. ! rg -n 'compatibility' skills/helix/SKILL.md\n5. rg -n 'desired|intent|evidence' workflows/actions/reconcile-alignment.md workflows/templates/alignment-review.md\n6. bash tests/validate-skills.sh exits 0.\n7. Open GitHub PR for dual-path + Align/Polish.", "created_at": "2026-07-22T22:17:03.451392715Z", "dependencies": [{"issue_id": "helix-da73534f", "depends_on_id": "helix-3771e94b", "type": "blocks", "created_at": "2026-07-22T22:17:26Z"}], "description": "A3 dual-path: keep Skill(helix) MUST for hosts with skill tool; add Grok path first action loads SKILL.md body. Keep Read/Write/Edit/Bash literals. Description triggers only within 1024 chars; forbid substring compatibility in SKILL.md. A4: desired-state with operator intent guard for code-ahead; evidence-gated implement beads; mandatory template bind on author; four-field Align handoff. W5 mandatory: update workflows/templates/alignment-review.md, workflows/actions/reconcile-alignment.md, workflows/actions/polish.md. Out of scope: progressive disclosure thinning; Grok install docs (PR3); install harness (PR4).", "id": "helix-da73534f", "issue_type": "task", "labels": ["helix", "phase:build", "activity:build", "kind:implementation", "area:skills", "plan-2026-07-22", "runtime:grok", "tranche:pr2"], "parent": "helix-af0bc17b", "priority": 1, "schema_version": 1, "spec-id": "plan-2026-07-22-grok-plugin", "status": "open", "title": "PR2: Dual-path activation + Align/Polish desired-state contracts", "updated_at": "2026-07-22T22:17:26.684188623Z"} +{"acceptance": "1. skills/helix/SKILL.md still contains Skill(helix) engagement requirement for skill-tool hosts.\n2. skills/helix/SKILL.md documents non-skill-tool host engagement via loading SKILL.md body.\n3. python3 -c \"import yaml; t=open('skills/helix/SKILL.md').read(); fm=yaml.safe_load(t[4:t.find(chr(10)+'---'+chr(10),4)]); assert len(fm['description'])<=1024\"\n4. ! rg -n 'compatibility' skills/helix/SKILL.md\n5. rg -n 'desired|intent|evidence' workflows/actions/reconcile-alignment.md workflows/templates/alignment-review.md\n6. bash tests/validate-skills.sh exits 0.\n7. Open GitHub PR for dual-path + Align/Polish.", "created_at": "2026-07-22T22:17:03.451392715Z", "dependencies": [{"issue_id": "helix-da73534f", "depends_on_id": "helix-3771e94b", "type": "blocks", "created_at": "2026-07-22T22:17:26Z"}], "description": "A3 dual-path: keep Skill(helix) MUST for hosts with skill tool; add Grok path first action loads SKILL.md body. Keep Read/Write/Edit/Bash literals. Description triggers only within 1024 chars; forbid substring compatibility in SKILL.md. A4: desired-state with operator intent guard for code-ahead; evidence-gated implement beads; mandatory template bind on author; four-field Align handoff. W5 mandatory: update workflows/templates/alignment-review.md, workflows/actions/reconcile-alignment.md, workflows/actions/polish.md. Out of scope: progressive disclosure thinning; Grok install docs (PR3); install harness (PR4).", "id": "helix-da73534f", "issue_type": "task", "labels": ["helix", "phase:build", "activity:build", "kind:implementation", "area:skills", "plan-2026-07-22", "runtime:grok", "tranche:pr2"], "owner": "erik", "parent": "helix-af0bc17b", "priority": 1, "schema_version": 1, "spec-id": "plan-2026-07-22-grok-plugin", "status": "closed", "title": "PR2: Dual-path activation + Align/Polish desired-state contracts", "updated_at": "2026-07-22T22:22:43.704922985Z"} {"acceptance": "Skills are discoverable from the public site. Artifact types and worked HELIX artifacts have clear landing paths. The page narrative distinguishes methodology artifacts, runtime/platform integration, and legacy wrappers. Driving research and governing artifacts are linked from the relevant narrative pages.", "created_at": "2026-05-12T05:31:20.63831788Z", "description": "Ensure the microsite represents HELIX's portable skills, artifact-type catalog, and self-governing artifacts as first-class public concepts. The site should explain what exists, how the pieces relate, and what is legacy/runtime-specific versus core methodology.", "id": "helix-db1ed7c1", "issue_type": "feature", "labels": ["helix", "website", "activity:build", "area:skills", "area:artifacts"], "parent": "helix-e1a72cfc", "priority": 1, "schema_version": 1, "status": "closed", "title": "Represent HELIX skills and artifacts in the microsite", "updated_at": "2026-05-12T05:35:11.918546591Z"} {"acceptance": "All review passes complete; findings filed as beads; AGENTS.md updated if needed", "closing_commit_sha": "96b75eebbc39a1b53bc1d5644a931bd980d35932", "created_at": "2026-04-10T08:37:56.737778735Z", "description": "\nDesign for Change · Design for Simplicity · Validate Your Work · Make Intent Explicit · Prefer Reversible Decisions\nhugo-hextra and demo-asciinema are areas:all concerns; e2e-playwright is site-only. This review target is a tracker-state mutation in .ddx/beads.jsonl, so concern-specific site/demo/test practices are relevant only for drift detection.\nReview tracker-state mutation for durable evidence, accurate measure semantics, and compliance with bead-first measurement/report expectations.\nFresh-eyes review of implementation commit 80acf3d95d0818ad367d5bf4df112f812cfb9bb2 for bead helix-7171e7a1 after tracker-close commit 96b75eebbc39a1b53bc1d5644a931bd980d35932.\n- Executed bead: helix-7171e7a1\n- Implementation commit: 80acf3d95d0818ad367d5bf4df112f812cfb9bb2\n- Tracker-close commit after implementation: 96b75eebbc39a1b53bc1d5644a931bd980d35932\n- Reviewed issue: correctness: persist closure outcome on lessons-learned bead\n\nFresh-eyes review of last-commit in automated loop.\nReview target: commit:80acf3d95d0818ad367d5bf4df112f812cfb9bb2", "id": "helix-db2d312d", "issue_type": "task", "labels": ["helix", "kind:review", "kind:planning", "action:review"], "notes": "\n 2026-04-10T08:39:27Z\n ISSUES_FOUND\n \n NO\n 0\n", "priority": 0, "schema_version": 1, "spec-id": "80acf3d95d0818ad367d5bf4df112f812cfb9bb2", "status": "closed", "title": "review: last-commit 80acf3d helix-7171e7a1 implementation", "updated_at": "2026-04-10T08:39:27.841006006Z"} {"acceptance": "1. TestContractNonHttpScope: Contract guidance explicitly names non-HTTP protocol/data/interface surfaces, including telemetry/export contracts.\n2. TestContractNormativeFields: the Contract template requires exact keys/fields, types, units, enums, precedence rules, formulas, error semantics, examples, and validation checklists where relevant.\n3. TestContractShareableScope: guidance states contracts must be shareable across projects without inheriting unrelated feature-level or solution-level baggage.\n4. TestContractNonHttpVerification: `go test ./...` passes.\n5. TestContractNonHttpLefthookGate: `lefthook run pre-commit` passes.", "closing_commit_sha": "1b1d643337d848bc07f747dcfe565232692b8a3b", "created_at": "2026-05-18T08:21:24.645405476Z", "description": "PROBLEM: Contract artifacts must support more than HTTP APIs. HELIX needs reusable normative specifications for telemetry schemas, export protocols, ownership boundaries, authoring conventions, CLI/library mutation surfaces, and other cross-project interfaces. Governing artifact reference: workflows/phases/02-design/README.md. Dependency ID: helix-13cfe23f.\nROOT CAUSE: workflows/phases/02-design/README.md:1 and docs/helix/02-design/contracts/:1 recognize contracts as a design artifact area, but current guidance is underspecified for non-HTTP contracts such as telemetry/export schemas and reusable protocol/interface definitions.\nPROPOSED FIX: Extend the Contract docs and template language to explicitly cover non-HTTP surfaces. Include examples or guidance hooks for telemetry/export contracts, data/interface contracts, CLI/library mutation contracts, cross-project ownership boundaries, and authoring conventions. State that HTTP API contracts are one subtype, not the whole Contract category.\nNON-SCOPE: Do not change Hugo/Hextra theme behavior, website publishing configuration, demo asciinema recordings, agent harness invocation, OpenTelemetry runtime implementation, DDx/HELIX execution engine behavior, or generate a real project-specific telemetry contract beyond illustrative template guidance.", "events_attachment": "helix-db3c81ea/events.jsonl", "id": "helix-db3c81ea", "issue_type": "task", "labels": ["helix", "activity:design", "kind:spec", "area:docs", "area:workflow"], "parent": "helix-1940a77b", "priority": 0, "schema_version": 1, "session_id": "eb-2287a038", "status": "closed", "title": "Make contract guidance cover non-HTTP protocol and telemetry interfaces", "updated_at": "2026-05-18T08:46:24.209363302Z"} diff --git a/skills/helix/SKILL.md b/skills/helix/SKILL.md index d05068e7..d23ad743 100644 --- a/skills/helix/SKILL.md +++ b/skills/helix/SKILL.md @@ -11,7 +11,8 @@ description: | roadmap brief, requirements. Product, web, infra, and data are domain lanes that shape context and stop rules; they are not sibling public skills or workflow modes. Engage on "what's next" / "plan the change" - / cross-flow queries. + / cross-flow queries. Engage on desired state vs implementation, + specs behind code, and pruning beads against specs. argument-hint: "[intent or scope]" --- @@ -27,10 +28,21 @@ this skill instead. ## When to engage (read first; non-negotiable) -You ENGAGE this skill — call `Skill(helix)` — whenever any of these is true, -regardless of whether the artifact content is attached, the workspace is -empty, or the request looks like a generic task. Once engaged, you route -by four separate axes: +You ENGAGE this skill whenever any of these is true, regardless of whether +the artifact content is attached, the workspace is empty, or the request +looks like a generic task. **Engagement is the first tool action of the turn** +(dual-path by host): + +- **Skill-tool hosts** (Claude Code `Skill` tool, Codex/opencode skill tool): + invoke `Skill(helix)` (or the host's equivalent skill-load tool for `helix`) + as the first tool action. Narrating HELIX-shaped reasoning without that + invocation is a contract violation on these hosts. +- **Hosts without a skill tool** (for example Grok Build): the first action + MUST load this `SKILL.md` body via the host mechanism (`/helix`, skill + auto-load, or a read of this skill's path). That load is the engagement + event. + +Once engaged, you route by four separate axes: 1. **Scope instance** — which `flows:` entry in `.helix.yml` owns the target artifact or requested project area. @@ -71,9 +83,10 @@ Engage when: §Check And Next contract. Verbose-but-stuck anti-pattern: narrating HELIX-shaped reasoning in -assistant text WITHOUT calling `Skill(helix)` is a contract violation. -The Skill tool_use must fire as the FIRST tool_use of the turn when any -of the engage conditions above is true. +assistant text WITHOUT an engagement action (skill-tool invoke on +skill-tool hosts, or SKILL.md load on other hosts) is a contract +violation. The engagement action must be the first tool action of the +turn when any of the engage conditions above is true. ## Routing Axes @@ -236,11 +249,12 @@ marker. ### 4. Author / edit artifacts -When asked to author or edit an instance document, follow the type's -`template.md`, `prompt.md`, `meta.yml`, and active voice profile from the -library. Look up the type via the flow's `workflows/graph.yml` — every node -points at a `library:` or `local:` type, and the library tree is at -the canonical install root (`library/` after this install). +When asked to author or edit an instance document, **first bind the type's +`template.md`, `prompt.md`, `meta.yml`, and active voice profile** from the +resolved catalog (§Catalog Resolution). Do not author from the activity +table alone. Look up the type via the bound graph — every node points at a +`library:` or `local:` type, and the library tree is at the +canonical install root (`library/` after this install). **Edit existing instances; Write only new ones.** When the requested artifact already exists at the resolved path, use `Edit` (target the @@ -738,13 +752,22 @@ placement reviews. code surface (route/screen/CLI/API/job/migration) traces to a governing artifact, and every acceptance criterion traces to an exercising test. Unmapped material surfaces and unimplemented criteria are both alignment findings. -2. Reconstruct intent from planning artifacts before inspecting lower layers. -3. Classify each gap as `ALIGNED`, `INCOMPLETE`, `DIVERGENT`, +2. **Desired-state rule (with intent guard).** Specs describe the **desired** + future state. Code behind specs → residual work items (beads/tracker), not + silent requirement shrinks. Code ahead of docs → classify as plan-to-code + honesty (`STALE_PLAN` / honesty evolve). Evolving specs to match code + requires **operator intent** (explicit request or approved handoff) — do + not auto-bless unapproved implementation as plan authority. Code reflects + state; it does not redefine plan alone. +3. Reconstruct intent from planning artifacts before inspecting lower layers. +4. Classify each gap as `ALIGNED`, `INCOMPLETE`, `DIVERGENT`, `UNDERSPECIFIED`, `STALE_PLAN`, or `BLOCKED`. -4. Produce one durable alignment report when the action is more than a +5. Produce one durable alignment report when the action is more than a conversational review. The report must remain reviewable by a human in - under ten minutes. -5. For every non-aligned gap (`INCOMPLETE`, `UNDERSPECIFIED`, `DIVERGENT`, + under ten minutes. Prefer the alignment-review template under the catalog + (`workflows/templates/alignment-review.md` or the package + `references/templates/` path when present). +6. For every non-aligned gap (`INCOMPLETE`, `UNDERSPECIFIED`, `DIVERGENT`, `STALE_PLAN`), the handoff to implementation must name all four of: - **Destination artifact type** (e.g. PRD, FEAT, US, ADR, TD, TP) where the gap is resolved. @@ -755,8 +778,12 @@ placement reviews. already governed — never a CLI command. - **Evidence references**: artifact paths plus line numbers (or section anchors) supporting the finding. -6. Create or identify follow-up work for every non-aligned gap using the - handoff fields above. +7. Create or identify follow-up work for every non-aligned gap using the + handoff fields above. **Evidence-gated implement work:** before filing + build/implement items, require concrete residual evidence (paths, tests, + commands). Prefer story/AC floor items when only docs/traceability lag. + "Residual already green" means a governing AC is exercised by a passing + test (or a recorded exception). Close or re-scope only with that evidence. ### Validate @@ -924,9 +951,13 @@ Use to refine work items before execution. 1. Load open work for the scope and any governing plan. 2. Run multiple passes for deduplication, coverage, acceptance quality, dependency correctness, sizing, and label hygiene. -3. Require execution-ready work items to name exact files, commands, checks, fields, +3. **Evidence gate for implement/build items:** verify residual against + code/tests before keeping or filing build work. Prefer story/AC floor + items when only docs lag. Close or re-scope items whose residual is + already green (passing tests cite the AC, or documented exception). +4. Require execution-ready work items to name exact files, commands, checks, fields, or observable repository states. -4. If acceptance cannot be sharpened from governing artifacts, flag the work as +5. If acceptance cannot be sharpened from governing artifacts, flag the work as not execution-ready and route it back through planning. ### Check And Next diff --git a/workflows/actions/polish.md b/workflows/actions/polish.md index 5d969fde..908c66f1 100644 --- a/workflows/actions/polish.md +++ b/workflows/actions/polish.md @@ -54,6 +54,17 @@ Before modifying any work items, acquire a governing work item for this polish pass to record progress and govern changes. See the runtime's work-item acquisition reference for the full pattern. +## STEP 0.75 - Evidence gate (before filing or keeping build work) + +For every open or proposed `activity:build` / implement item in scope: + +1. Check residual against code and tests (paths, greps, named suites). +2. If the governing AC is already exercised by a passing test (or a recorded + exception), **close or re-scope** the item — do not leave stale implement work. +3. If only story/AC documentation lags shipped code, prefer frame/story floor + items over new implement items. +4. Record evidence (path:line or test name) on the item when keeping it open. + ## STEP 1 - Plan Decomposition **This activity runs first and is mandatory when a plan exists.** Plans must be diff --git a/workflows/actions/reconcile-alignment.md b/workflows/actions/reconcile-alignment.md index 83359c5a..6677aa98 100644 --- a/workflows/actions/reconcile-alignment.md +++ b/workflows/actions/reconcile-alignment.md @@ -40,6 +40,15 @@ Rules: - Source code reflects current state but does not redefine the plan. - If a higher layer is missing or contradictory, do not infer intent from lower layers. - Prefer aligning code to plan. Propose plan changes only when strongly justified. +- **Desired-state:** specs describe the desired future. Do not shrink requirements + to match incomplete code without operator intent. Code ahead of docs is + plan-to-code honesty (`STALE_PLAN`); evolving specs to match code requires + explicit operator intent or an approved handoff — never auto-bless impl as plan. +- **Four-field handoff** for every non-ALIGNED gap: destination artifact type, + deliverable shape, suggested next workflow mode, evidence path:line. +- **Evidence-gated implement work:** before filing build items, verify residual + against code/tests; prefer story/AC floor items when only docs lag; close or + re-scope only when residual is already green with recorded evidence. ## Tracker Rules diff --git a/workflows/templates/alignment-review.md b/workflows/templates/alignment-review.md index 8abd8517..09848156 100644 --- a/workflows/templates/alignment-review.md +++ b/workflows/templates/alignment-review.md @@ -47,11 +47,19 @@ |-----------------|-----------|----------------|--------|----------| | [ID] | [criterion] | [test path or "none"] | [SATISFIED/TESTED_NOT_PASSING/UNTESTED/UNIMPLEMENTED] | [refs] | +## Desired-state posture + +- Specs = **desired** future state (do not shrink requirements to match incomplete code without operator intent). +- Code behind specs → residual work items with evidence. +- Code ahead of docs → honesty evolve only with **operator intent**; classify as `STALE_PLAN` until approved. + ## Gap Register -| Area | Classification | Planning Evidence | Implementation Evidence | Resolution Direction | Issue | -|------|----------------|-------------------|------------------------|----------------------|-------| -| [Area] | [ALIGNED/INCOMPLETE/DIVERGENT/UNDERSPECIFIED/STALE_PLAN/BLOCKED] | [refs] | [refs] | [code-to-plan/plan-to-code/decision-needed/quality-improvement] | [ID] | +| Area | Classification | Destination type | Deliverable shape | Next mode | Evidence (path:line) | Resolution Direction | Issue | +|------|----------------|------------------|-------------------|-----------|----------------------|----------------------|-------| +| [Area] | [ALIGNED/INCOMPLETE/DIVERGENT/UNDERSPECIFIED/STALE_PLAN/BLOCKED] | [PRD/FEAT/US/ADR/…] | [concrete add] | [frame/design/evolve/…] | [refs] | [code-to-plan/plan-to-code/decision-needed/quality-improvement] | [ID] | + +Four-field handoff (required for every non-ALIGNED row): destination artifact type, deliverable shape, suggested next workflow mode, evidence path:line. ### Quality Findings From fb4bfc58f4cbc56e64091fa6505978e7940d5c9c Mon Sep 17 00:00:00 2001 From: Erik LaBianca Date: Wed, 22 Jul 2026 18:24:52 -0400 Subject: [PATCH 2/3] docs(install): add Grok Build guide and no-local-template doctrine Add docs/install/grok.md, list Grok as a sixth runtime, soft-update Claude/Codex guides for fall-through catalogs, and extend validate-install-consistency. Closes helix-416efaaa (PR3). --- .ddx/beads.jsonl | 2 +- docs/install/README.md | 30 +++++- docs/install/claude-code.md | 5 + docs/install/codex.md | 9 +- docs/install/grok.md | 134 ++++++++++++++++++++++++++ tests/validate-install-consistency.sh | 32 ++++++ 6 files changed, 204 insertions(+), 8 deletions(-) create mode 100644 docs/install/grok.md diff --git a/.ddx/beads.jsonl b/.ddx/beads.jsonl index a51e2d92..3f8950cb 100644 --- a/.ddx/beads.jsonl +++ b/.ddx/beads.jsonl @@ -149,7 +149,7 @@ {"acceptance": "All 8 child beads closed. Three new artifact-type directories exist with the four required files. Bundle rebuild + workspace re-upload + Genie e2e confirms the new types are listable from SKILL.md. v0.5.0 tagged with the three new types in the published bundle.", "created_at": "2026-05-18T01:41:31.110308647Z", "description": "\nDesign for Change · Design for Simplicity · Validate Your Work · Make Intent Explicit · Prefer Reversible Decisions\ndata-engineering-adoption | catalog-growth | databricks-platform-specific\nThree new artifact types: data-prd (01-frame), data-architecture (02-design), data-quality-expectations (03-test) · First-class types in their respective activity directories · Keep Databricks-specific terminology (UC, SDP EXPECT, DBU); document substitution in §Role Boundary · Skip FEAT-015 spec; this plan is the design · Phase G updates SKILL.md §Catalog Resolution inline table so Genie can enumerate new types from SKILL.md alone\nplan-2026-05-17-fold-datahelix-templates.md\n\n\nAdopt three rescued DataHelix templates as first-class HELIX artifact types:\n - data-prd (01-frame/artifacts/data-prd/)\n - data-architecture (02-design/artifacts/data-architecture/)\n - data-quality-expectations (03-test/artifacts/data-quality-expectations/)\n\nEach new type ships meta.yml + template.md + prompt.md + example.md, is referenced in workflows/artifact-hierarchy.md and REFERENCE.md, and appears in the SKILL.md §Catalog Resolution inline table so Genie and other runtimes can enumerate it without filesystem traversal. Decisions (naming, scope, platform, no FEAT spec) are locked in the plan doc.\n\nSource templates: .local/workspace-rescue/datahelix-2026-05-17/templates/.", "id": "helix-40aeaec5", "issue_type": "epic", "labels": ["helix", "activity:design", "kind:spec", "area:artifacts", "area:artifact-types"], "owner": "erik", "priority": 1, "schema_version": 1, "spec-id": "plan.fold-datahelix-templates", "status": "closed", "title": "Epic: fold DataHelix data-engineering templates into HELIX catalog", "updated_at": "2026-05-21T13:54:34.988843148Z"} {"acceptance": "Current HELIX docs and live repo state have been reviewed for 'monitoring-setup'; a decision is recorded to restore, supersede, or retire it; if restored, the minimum prompt/template bar for 'monitoring-setup' is explicit enough to guide reintroduction; if retired or superseded, the canonical replacement or stale references are identified", "claimed-at": "2026-04-09T22:50:18Z", "claimed-machine": "eitri", "claimed-pid": "2065534", "closing_commit_sha": "3c966b23ec78d98f9debf949d54754af822aad41", "created_at": "2026-04-09T21:13:58.613020797Z", "description": "\nMake Intent Explicit · Design for Change · Validate Your Work\nworkflow | docs\nCompare deleted artifact intent to current HELIX contract and live repo state before restoring anything · Prefer one canonical artifact per real responsibility · Restore only artifacts whose prompt/template bar is clear and justified\nworkflows/conventions.md\n\n\nReview the deleted artifact type 'monitoring-setup'. Determine whether its original intent still exists in current HELIX, whether that intent is already covered by another canonical artifact or tracker primitive, and whether 'monitoring-setup' should be restored, superseded, or retired. If restoration is warranted, define the minimum acceptable prompt and template bar for 'monitoring-setup' so the artifact is not reintroduced as another thin stub.\n\nIntent to validate: Monitoring configuration and observability setup needed before or during rollout.", "id": "helix-40f1522d", "issue_type": "task", "labels": ["helix", "activity:design", "kind:docs", "area:artifacts"], "owner": "erik", "parent": "helix-fef22846", "priority": 0, "schema_version": 1, "spec-id": "workflows/conventions.md", "status": "closed", "title": "Review deleted artifact type: monitoring-setup", "updated_at": "2026-04-09T22:51:11.398370369Z"} {"acceptance": "`website/content/docs/glossary/phases.md` describes the Deploy phase with artifact guidance that matches the restored contract for `deployment-checklist`, `monitoring-setup`, `runbook`, and `release-notes`, and the stale `Project-specific checklists and runbooks as needed` text is removed.", "claimed-at": "2026-04-10T19:17:36Z", "claimed-machine": "eitri", "claimed-pid": "62305", "closing_commit_sha": "68c56f1e223e148bb3c0ef1749413f8d047aeb9b", "created_at": "2026-04-10T13:13:34.805335623Z", "description": "\nDesign for Change · Design for Simplicity · Validate Your Work · Make Intent Explicit · Prefer Reversible Decisions\nhugo-hextra | demo-asciinema | e2e-playwright\nDefine the site's target audience and what content they need · Theme version: Hextra v0.12.1 — pinned in website/go.mod · Identify which workflows need demo reels — prioritize the \"first 5 minutes\" experience · Current demos: helix-quickstart (full lifecycle), helix-concerns (drift detection), helix-evolve (requirement threading) · Identify all user-facing pages and workflows that need testing · Test location: website/e2e/microsite.spec.ts\nwebsite/content/docs/glossary/phases.md — Tests are the contract between design and implementation. Code must satisfy tests, not the other way around.\n\n\nReview finding from fresh-eyes review.\nFile: website/content/docs/glossary/phases.md:86\nCategory: drift\nSeverity: medium\nDescription: The microsite phase glossary still says Deploy uses only project-specific checklists and runbooks as needed, even though commit 0d5fe16 restores `release-notes` and the updated deploy README now treats four deploy surfaces as first-class. Under the active `hugo-hextra` concern, governing artifact changes must update the corresponding microsite pages in the same pass; this page is still advertising the pre-restoration contract.\nSuggested fix: Update the Deploy row in the phase glossary so its key artifacts and output text match the restored deploy artifact surface and stay aligned with the workflow docs.", "id": "helix-414fe238", "issue_type": "task", "labels": ["helix", "activity:build", "review-finding", "area:site"], "notes": "\n 2026-04-10T19:18:59Z\n PASS\n \n \n \n \n \n \n \n \n \n \n \n", "owner": "erik", "priority": 0, "schema_version": 1, "spec-id": "website/content/docs/glossary/phases.md", "status": "closed", "title": "drift: update deploy phase glossary for restored release-notes", "updated_at": "2026-04-10T19:20:18.941089853Z"} -{"acceptance": "1. test -f docs/install/grok.md\n2. rg -n 'grok.md|Grok' docs/install/README.md\n3. rg -n 'grok plugin install' docs/install/grok.md\n4. rg -n 'fall.through|need not vendor|do not copy' docs/install/grok.md docs/install/README.md\n5. bash tests/validate-install-consistency.sh exits 0.\n6. Open GitHub PR for Grok install docs.", "created_at": "2026-07-22T22:17:20.801990263Z", "dependencies": [{"issue_id": "helix-416efaaa", "depends_on_id": "helix-da73534f", "type": "blocks", "created_at": "2026-07-22T22:17:26Z"}], "description": "Add docs/install/grok.md (install, trust, verify, no-local-templates fall-through doctrine, troubleshooting). Update docs/install/README.md as sixth runtime. Soft-update claude-code.md and codex.md doctrine only — do not change their install commands. Extend tests/validate-install-consistency.sh for grok guide + doctrine. Out of scope: tests/install/grok-build harness (PR4); skill contract changes.", "id": "helix-416efaaa", "issue_type": "task", "labels": ["helix", "phase:build", "activity:build", "kind:docs", "area:docs", "plan-2026-07-22", "runtime:grok", "tranche:pr3"], "parent": "helix-af0bc17b", "priority": 1, "schema_version": 1, "spec-id": "plan-2026-07-22-grok-plugin", "status": "open", "title": "PR3: docs/install/grok.md + install consistency + doctrine", "updated_at": "2026-07-22T22:17:26.807239199Z"} +{"acceptance": "1. test -f docs/install/grok.md\n2. rg -n 'grok.md|Grok' docs/install/README.md\n3. rg -n 'grok plugin install' docs/install/grok.md\n4. rg -n 'fall.through|need not vendor|do not copy' docs/install/grok.md docs/install/README.md\n5. bash tests/validate-install-consistency.sh exits 0.\n6. Open GitHub PR for Grok install docs.", "created_at": "2026-07-22T22:17:20.801990263Z", "dependencies": [{"issue_id": "helix-416efaaa", "depends_on_id": "helix-da73534f", "type": "blocks", "created_at": "2026-07-22T22:17:26Z"}], "description": "Add docs/install/grok.md (install, trust, verify, no-local-templates fall-through doctrine, troubleshooting). Update docs/install/README.md as sixth runtime. Soft-update claude-code.md and codex.md doctrine only — do not change their install commands. Extend tests/validate-install-consistency.sh for grok guide + doctrine. Out of scope: tests/install/grok-build harness (PR4); skill contract changes.", "id": "helix-416efaaa", "issue_type": "task", "labels": ["helix", "phase:build", "activity:build", "kind:docs", "area:docs", "plan-2026-07-22", "runtime:grok", "tranche:pr3"], "owner": "erik", "parent": "helix-af0bc17b", "priority": 1, "schema_version": 1, "spec-id": "plan-2026-07-22-grok-plugin", "status": "closed", "title": "PR3: docs/install/grok.md + install consistency + doctrine", "updated_at": "2026-07-22T22:24:22.209375803Z"} {"acceptance": "Supporting workflow docs no longer reference deleted artifact types without corresponding workflow artifact definitions; any intentionally retained artifact names have canonical definitions under workflows/phases/*/artifacts/; git diff --check passes", "claimed-at": "2026-04-10T19:25:19Z", "claimed-machine": "eitri", "claimed-pid": "68965", "closing_commit_sha": "abe28cca6c340c6bca674de19a4d4d73fe9656df", "created_at": "2026-04-09T21:02:37.441471923Z", "description": "\nDesign for Change · Design for Simplicity · Validate Your Work · Make Intent Explicit · Prefer Reversible Decisions\nhugo-hextra | demo-asciinema\nTheme version: Hextra v0.12.1 — pinned in website/go.mod · Hugo version: 0.159.2 extended — pinned in .github/workflows/pages.yml · Current demos: helix-quickstart (full lifecycle), helix-concerns (drift detection), helix-evolve (requirement threading) · Agent harness: ddx agent run --harness claude — not claude -p\nworkflows/state-machine.yaml — Supporting workflow docs no longer reference deleted artifact types without corresponding workflow artifact definitions\n\n\nReview finding from fresh-eyes review.\nFile: workflows/state-machine.yaml:72\nCategory: drift\nSeverity: medium\nDescription: Supporting workflow docs still enumerate deleted artifact types across multiple phases: design lists auth-design and data-protection; test lists story-test-plan; build lists story-implementation-plan, build-procedures, and secure-coding; deploy lists deployment-checklist, launch-checklist, release-notes, and gtm-plan; iterate lists metrics-dashboard, feedback-analysis, lessons-learned, improvement-backlog, and iteration-planning. The corresponding artifact directories are missing, so the support docs no longer describe the actual packaged workflow surface.\nSuggested fix: Audit supporting docs such as state-machine.yaml, conventions.md, artifact-hierarchy.md, diagrams/artifact-flow.md, and phase READMEs; remove stale deleted artifact names where responsibilities were consolidated, or restore the artifact definitions when those names are still intended to be part of HELIX.", "id": "helix-41b86771", "issue_type": "task", "labels": ["helix", "activity:build", "review-finding", "area:artifacts", "area:workflow"], "notes": "\n 2026-04-10T19:35:00Z\n PASS\n \n \n \n \n \n \n \n \n \n \n \n", "owner": "erik", "priority": 0, "schema_version": 1, "spec-id": "workflows/state-machine.yaml", "status": "closed", "title": "drift: remove or restore deleted artifact types still named in supporting workflow docs", "updated_at": "2026-04-10T19:33:42.143980821Z"} {"acceptance": "Microsite has a page citing agile, speckit, gastown, ralph, autoresearch, and Jeffrey Emmanuel's agentic flywheel as inspirations. Page is linked from navigation.", "claimed-at": "2026-04-07T00:12:03Z", "claimed-machine": "sindri", "claimed-pid": "1294304", "created_at": "2026-04-07T00:09:44.73572943Z", "id": "helix-41baf1ea", "issue_type": "task", "labels": ["helix", "activity:build", "microsite"], "owner": "erik", "priority": 0, "schema_version": 1, "spec-id": "FEAT-007", "status": "closed", "title": "Add inspirations and references page to microsite", "updated_at": "2026-04-07T00:13:15.929569779Z"} {"acceptance": "All committed docs/helix/* instances that meant story-test-plans use STP-NNN. File rename complete (docs/helix/03-test/test-plans/STP-002-helix-cli.md, etc.). Cross-references updated. grep -rn 'TP-[0-9]' docs/helix/ workflows/ skills/ returns only references to legitimate (project-level) test-plans, if any.", "closing_commit_sha": "c0e484e58ca51e6d93525463b33fa7dfc08d044a", "created_at": "2026-05-14T21:31:45.219673981Z", "description": "Companion to helix-7a2427f5 which split test-plan (TP-XXX, singleton) from story-test-plan (STP-XXX, numbered). The id_format change leaves ~50+ committed instance artifacts referencing the old TP-NNN names that should be migrated to STP-NNN. Files include: docs/helix/03-test/test-plans/TP-002-helix-cli.md (rename to STP-002-helix-cli.md), all alignment reviews under docs/helix/06-iterate/alignment-reviews/ referencing TP-002, features under docs/helix/01-frame/features/ with TP-002 deps, and several technical-designs and 02-design artifacts. Pure rename + cross-reference update; mechanical.", "events_attachment": "helix-41e2ba9c/events.jsonl", "id": "helix-41e2ba9c", "issue_type": "task", "labels": ["helix", "activity:build", "kind:implementation", "area:artifacts", "modernization", "follow-up"], "parent": "helix-f9207605", "priority": 3, "schema_version": 1, "session_id": "eb-a3cd52e3", "spec-id": "helix.prd", "status": "closed", "title": "Migrate legacy TP-NNN instance artifacts to STP-NNN (story-test-plan)", "updated_at": "2026-05-19T01:22:03.784970558Z"} diff --git a/docs/install/README.md b/docs/install/README.md index fa6bb043..5600e3bb 100644 --- a/docs/install/README.md +++ b/docs/install/README.md @@ -15,6 +15,15 @@ directory so runtimes that install only the skill subtree remain self-contained. That directory is package output, not a second source of truth. +### No local template copies (adopter default) + +Normal adopter projects need not vendor HELIX templates. Install the HELIX +plugin (or package floor) and keep project content as `.helix.yml` plus +instance docs under the flow root (typically `docs/helix/`). If project-local +`workflows/` is absent, catalog resolution **falls through** to the plugin. +Project-local `workflows/` remains valid for self-hosting and intentional +methodology forks and outranks the installed plugin when present. + ## Minimal runtime contract A HELIX-compliant runtime can: @@ -60,7 +69,7 @@ source. ## Per-runtime install guides -Five supported runtimes. Each guide is self-contained: file layout, +Six supported runtimes. Each guide is self-contained: file layout, install steps, invocation, and verification. Pick the one that matches your environment; install more than one if you use more than one. @@ -107,6 +116,20 @@ Dockerfile/no-Node environments. **Best fit for:** terminal-native Codex sessions that load HELIX through the Codex plugin manager. +### [Grok Build](grok.md) + +```bash +grok plugin install DocumentDrivenDX/helix --trust +# development: +grok plugin install /path/to/helix --trust +``` + +Install via Grok's plugin manager. Full-repo installs bind the catalog at +`/workflows/`; adopters need not copy templates into the project. + +**Best fit for:** Grok Build TUI/CLI sessions that should load HELIX as a +plugin without vendoring the methodology catalog into each product repo. + ### [GitHub Copilot](copilot.md) ```bash @@ -154,9 +177,10 @@ the same HELIX methodology for validation and artifact updates. ## Convergence point: agentskills.io -Claude Code, Codex CLI, Cursor, VS Code/Copilot, Gemini CLI, and +Claude Code, Codex CLI, Grok Build, Cursor, VS Code/Copilot, Gemini CLI, and Databricks Genie Code all adopt the open -[Agent Skills specification](https://agentskills.io/specification). +[Agent Skills specification](https://agentskills.io/specification) +(or load agentskills-shaped skill packages). HELIX's `skills/helix/SKILL.md` is agentskills-compliant: required `name` and `description` frontmatter, parent directory name equal to `name:`, progressive-disclosure layout with heavy content in diff --git a/docs/install/claude-code.md b/docs/install/claude-code.md index ec92c586..77340814 100644 --- a/docs/install/claude-code.md +++ b/docs/install/claude-code.md @@ -50,6 +50,11 @@ claude plugin install helix@helix --scope user -y ``` After install, the skill is available in any Claude Code session. +Adopter product repos need not copy `workflows/` templates; missing +project-local catalogs **fall through** to the installed plugin (see skill +§Catalog Resolution). Vendoring `workflows/` remains valid for self-host +and intentional forks and outranks the plugin when present. + Verify with `claude plugin list`: ``` diff --git a/docs/install/codex.md b/docs/install/codex.md index 81b8c960..cf9b86c8 100644 --- a/docs/install/codex.md +++ b/docs/install/codex.md @@ -117,13 +117,14 @@ start, add a HELIX section to `AGENTS.md` at the repo root: This repo uses HELIX (methodology + artifact catalog + one routing skill). -- Routing skill: `skills/helix/SKILL.md` -- Artifact catalog: `workflows/activities/` (00-discover through 06-iterate) -- Methodology spec: `workflows/README.md`, `workflows/principles.md` +- Routing skill: installed helix plugin / `skills/helix/SKILL.md` +- Artifact catalog: plugin `workflows/` or package `references/` (fall-through + when the project does not vendor templates); optional local `workflows/` +- Instance docs: `docs/helix/` (or the flow root in `.helix.yml`) When the user asks to use HELIX, align documents, frame requirements, design a change, evolve specs, review work, or otherwise touch -HELIX-governed material, load `skills/helix/SKILL.md` and follow the +HELIX-governed material, load the helix skill and follow the routing table inside it. Do not invent new `helix-*` skills. ``` diff --git a/docs/install/grok.md b/docs/install/grok.md new file mode 100644 index 00000000..245bd587 --- /dev/null +++ b/docs/install/grok.md @@ -0,0 +1,134 @@ +# HELIX in Grok Build + +This guide installs HELIX as a **Grok Build plugin**. The deliverable is the +routing skill plus the methodology catalog — not a CLI or tracker. Queue and +execution stay with your runtime (for example DDx) when you use one. + +Phase 0 layout probe notes (full-repo install paths) live at +[`tests/install/grok-build/phase0-layout.md`](../../tests/install/grok-build/phase0-layout.md). + +## What you are installing + +| Piece | Role | +|-------|------| +| `skills/helix/SKILL.md` | Single public HELIX router (`/helix` or description match) | +| `workflows/` (full-repo install) | Artifact templates, prompts, graph, voice, concerns | +| `skills/helix/references/` (generated package only) | Same catalog floor for slim installs | + +Adopter projects **need not vendor templates**. Prefer only: + +``` +adopter-repo/ + .helix.yml + docs/helix/… # instance artifacts +``` + +If project-local `workflows/` is absent, the skill **falls through** to the +plugin catalog (see skill §Catalog Resolution). Project-local `workflows/` +remains valid for self-host and intentional forks and **outranks** the +installed plugin when present. + +## Install path A: local checkout (development) + +```bash +grok plugin validate /path/to/helix +grok plugin install /path/to/helix --trust +grok plugin list +``` + +Observed layout (Phase 0): full tree under +`~/.grok/installed-plugins//` with `skills/helix/SKILL.md` and +`workflows/graph.yml` at the plugin root. Catalog binds via +`/../../workflows/…`. + +## Install path B: GitHub source + +```bash +grok plugin install DocumentDrivenDX/helix --trust +# pin optional: DocumentDrivenDX/helix@v0.10.3 +``` + +Use a full-repo install so `workflows/` is present. If a future install shape +ships only the skill subtree without `workflows/` or `references/`, install +the **generated package** from `scripts/build-plugin-package.sh` instead +(`dist/plugin-package/helix/`). + +## Install path C: session-only + +```bash +grok --plugin-dir /path/to/helix +``` + +Session load does not persist after exit. + +## Trust and enablement + +Install with `--trust` so hooks and skills activate. Grok also sets +`GROK_PLUGIN_ROOT` / `CLAUDE_PLUGIN_ROOT` for plugin hooks (and documents +Claude aliases). Skills may fall through to those env roots when relative +paths do not bind. + +If a plugin is listed but inactive, enable it via Grok plugin UI or +`[plugins].enabled` in `~/.grok/config.toml` for your Grok version. + +## Verify + +```bash +grok plugin list +grok inspect # skill name helix; prefer source under installed helix plugin +grok plugin details helix +``` + +In a session: + +``` +/helix check +``` + +Or natural language: “Use the helix skill to list workflow modes.” + +Expect engagement (skill load), then a short routing response naming modes +such as frame, align, design, evolve, review, polish, check. + +**Headless / non-interactive:** name the skill in the prompt; do not rely on +slash expansion if the host does not expand `/helix` outside the TUI. + +## Update / uninstall + +```bash +grok plugin update helix +grok plugin uninstall helix --confirm +``` + +## Catalog resolution (summary) + +Fall-through order (first bind wins): + +1. Marker `graph:` / `catalog:` pointer +2. Project-local `workflows/` (self-host / intentional vendor) +3. `../../workflows/` from this skill (full plugin / checkout) +4. `$GROK_PLUGIN_ROOT` / `$CLAUDE_PLUGIN_ROOT` → `workflows/` then `skills/helix/references/` +5. `references/` floor beside `SKILL.md` +6. Fail closed + +Missing project `workflows/` is **not** an error when a later step binds. + +## Engagement (dual-path) + +- Claude Code / skill-tool hosts: `Skill(helix)` first tool action (unchanged). +- Grok Build: first action loads the HELIX skill body (`/helix` or read). + +## Troubleshooting + +| Symptom | Check | +|---------|--------| +| Multiple `helix` skills | Prefer the skill from the installed `helix` plugin path; ignore legacy DDx `helix-workflow` / `helix-alignment-review` for routing | +| Catalog not found | Confirm `workflows/graph.yml` or `skills/helix/references/graph.yml` under the install root | +| Plugin listed but inactive | Trust/enable the plugin; reinstall with `--trust` | +| Untrusted hooks | Install with `--trust` or trust via Plugins UI | + +## Relation to Claude Code and Codex + +HELIX remains one skill + one catalog. Claude Code and Codex keep their own +install guides and marketplace flows. This page only documents **Grok discovery +and invocation**. Do not fork methodology content per runtime. diff --git a/tests/validate-install-consistency.sh b/tests/validate-install-consistency.sh index 50fb7844..dc2207c5 100755 --- a/tests/validate-install-consistency.sh +++ b/tests/validate-install-consistency.sh @@ -152,5 +152,37 @@ if ! grep -rE "DocumentDrivenDX/helix" "$INSTALL_DOCS_DIR" >/dev/null 2>&1; then fi echo "ok: install docs reference canonical repo ($MARKER_REPO)" +# Grok install guide (sixth runtime) +GROK_MD="$INSTALL_DOCS_DIR/grok.md" +if [[ ! -f "$GROK_MD" ]]; then + echo "FAIL: missing docs/install/grok.md" >&2 + exit 1 +fi +echo "ok: docs/install/grok.md exists" + +if ! grep -q 'grok plugin install' "$GROK_MD"; then + echo "FAIL: docs/install/grok.md must document grok plugin install" >&2 + exit 1 +fi +echo "ok: grok.md documents grok plugin install" + +if ! grep -qE -- '--trust' "$GROK_MD"; then + echo "FAIL: docs/install/grok.md must mention --trust (or trust flow)" >&2 + exit 1 +fi +echo "ok: grok.md documents trust" + +if ! grep -qE 'fall.?through|need not vendor|do not copy|need not copy' "$GROK_MD" "$INSTALL_DOCS_DIR/README.md"; then + echo "FAIL: grok guide or README must state no-local-template / fall-through doctrine" >&2 + exit 1 +fi +echo "ok: no-local-template / fall-through doctrine present" + +if ! grep -qE '\[Grok Build\]\(grok\.md\)|docs/install/grok\.md|Grok Build' "$INSTALL_DOCS_DIR/README.md"; then + echo "FAIL: docs/install/README.md must link or list Grok Build runtime" >&2 + exit 1 +fi +echo "ok: README lists Grok Build runtime" + echo echo "validate-install-consistency: PASS" From d83578a2a0b94737d1e10ed33f9cd1a745d545fa Mon Sep 17 00:00:00 2001 From: Erik LaBianca Date: Wed, 22 Jul 2026 18:26:23 -0400 Subject: [PATCH 3/3] test(install): add Grok Build host install harness Host-side install.sh/verify.sh with exit 77 skip semantics, wired into tests/install/run-all.sh. Asserts canonical helix skill layout and catalog fall-through paths for no-Docker CI when grok is present. Closes helix-26257203 (PR4). --- .ddx/beads.jsonl | 2 +- tests/install/grok-build/install.sh | 53 +++++++++++++ tests/install/grok-build/verify.sh | 113 ++++++++++++++++++++++++++++ tests/install/run-all.sh | 50 ++++++++++++ 4 files changed, 217 insertions(+), 1 deletion(-) create mode 100755 tests/install/grok-build/install.sh create mode 100755 tests/install/grok-build/verify.sh diff --git a/.ddx/beads.jsonl b/.ddx/beads.jsonl index 3f8950cb..83b11de0 100644 --- a/.ddx/beads.jsonl +++ b/.ddx/beads.jsonl @@ -77,7 +77,7 @@ {"acceptance": "Queue hygiene assessed; test issues and stale artifacts identified", "created_at": "2026-04-04T19:56:05.798325039Z", "id": "helix-25836a2d", "issue_type": "task", "labels": ["helix", "kind:review", "kind:review", "area:tracker"], "parent": "helix-71894dd3", "priority": 0, "schema_version": 1, "spec-id": "helix.prd", "status": "closed", "title": "Review: Tracker queue hygiene", "updated_at": "2026-04-04T20:04:48.434428903Z"} {"acceptance": "All review passes complete; findings filed as beads with scope-appropriate area labels; AGENTS.md updated if needed", "claimed-at": "2026-04-11T10:53:39Z", "claimed-machine": "eitri", "claimed-pid": "1978252", "created_at": "2026-04-11T10:53:39.087804569Z", "description": "\nFresh-eyes review of last-commit resolved to implementation commit a671506734e3ad50fc9825398b8e57879656b4f1.\nReview target: last-commit (tracker-only close commit skipped per automated run-loop rule).\nReviewed execution bead: helix-e28dc2fa.\nReviewed files: .ddx/beads.jsonl, scripts/helix, tests/helix-cli.sh.", "id": "helix-25acd775", "issue_type": "task", "labels": ["helix", "kind:review", "kind:planning", "action:review", "area:workflow", "area:testing"], "notes": "\n 2026-04-11T10:57:55Z\n ISSUES_FOUND\n \n NO\n 0\n helix-af52f67a\n\n\nFresh-eyes review of commit a671506734e3ad50fc9825398b8e57879656b4f1 completed.\nEvidence:\n- Re-read AGENTS.md and loaded the active principles, concerns, practices, and reviewed bead context before inspection.\n- Reviewed HEAD tracker-only close commit 57bcd0758fea3408ab8cc2f5dc9b98f57e76c80c and resolved implementation commit a671506734e3ad50fc9825398b8e57879656b4f1 from helix-e28dc2fa.closing_commit_sha per the automated run-loop rule.\n- Pass 1 correctness found one medium-severity defect in scripts/helix:2518-2526: `sync_issue_closing_commit_sha()` mutates the tracker, then runs `git commit --only -qm` without checking that commit's exit status even though both callers execute the helper in an `|| true` context. Bash reproduction: `bash -lc 'set -euo pipefail; f(){ false; echo after; }; f || true; echo survived'` prints `after` and `survived`, showing inner failures are ignored in that call pattern.\n- Pass 2 integration: if the repo-local sync commit fails, HELIX can continue review/loop execution with an uncommitted `.ddx/beads.jsonl` mutation, so the new review-targeting repair is not yet failure-safe.\n- Pass 3 concern-aware quality: active concerns hugo-hextra and demo-asciinema match via areas:all but introduce no additional scope-specific drift for this workflow/testing change.\n- Pass 4 operational learnings: no AGENTS.md updates or separate learnings issues were required.\n- Filed follow-on bead: helix-af52f67a.", "owner": "erik", "priority": 0, "schema_version": 1, "spec-id": "helix-e28dc2fa", "status": "closed", "title": "review: last-commit a671506 helix-e28dc2fa implementation", "updated_at": "2026-04-11T10:57:55.633517304Z"} {"acceptance": "Review areas reconciled and durable report updated", "created_at": "2026-04-10T20:16:50.497479046Z", "description": "Repo-wide alignment review for the HELIX repository covering workflow/CLI contract, tracker hygiene, DDx boundary, and public site/demo surfaces.", "id": "helix-25ec03b4", "issue_type": "epic", "labels": ["helix", "kind:review", "kind:review"], "priority": 0, "schema_version": 1, "status": "closed", "title": "HELIX alignment review: repo", "updated_at": "2026-04-10T20:23:02.637459732Z"} -{"acceptance": "1. test -f tests/install/grok-build/install.sh && test -f tests/install/grok-build/verify.sh\n2. rg -n 'grok-build|grok' tests/install/run-all.sh\n3. bash tests/install/grok-build/verify.sh either exits 0 or exits with documented skip code when grok missing.\n4. Open GitHub PR for Grok install harness.", "created_at": "2026-07-22T22:17:03.810463033Z", "dependencies": [{"issue_id": "helix-26257203", "depends_on_id": "helix-416efaaa", "type": "blocks", "created_at": "2026-07-22T22:17:26Z"}], "description": "Add tests/install/grok-build/{install.sh,verify.sh} and wire into tests/install/run-all.sh. Use Phase 0 install paths. Static verify: grok inspect asserts canonical helix plugin source path (not mere name=helix); verify-skill-layout.sh; adopter no-local-workflows path probe. Explicit skip exit semantics if grok binary unavailable (no false-fail/false-green). Functional mode list gated by TEST_FUNCTIONAL=1. Out of scope: skill content changes; progressive disclosure.", "id": "helix-26257203", "issue_type": "task", "labels": ["helix", "phase:test", "activity:test", "kind:test", "area:testing", "plan-2026-07-22", "runtime:grok", "tranche:pr4"], "parent": "helix-af0bc17b", "priority": 1, "schema_version": 1, "spec-id": "plan-2026-07-22-grok-plugin", "status": "open", "title": "PR4: Grok install harness tests/install/grok-build", "updated_at": "2026-07-22T22:17:26.922303072Z"} +{"acceptance": "1. test -f tests/install/grok-build/install.sh && test -f tests/install/grok-build/verify.sh\n2. rg -n 'grok-build|grok' tests/install/run-all.sh\n3. bash tests/install/grok-build/verify.sh either exits 0 or exits with documented skip code when grok missing.\n4. Open GitHub PR for Grok install harness.", "created_at": "2026-07-22T22:17:03.810463033Z", "dependencies": [{"issue_id": "helix-26257203", "depends_on_id": "helix-416efaaa", "type": "blocks", "created_at": "2026-07-22T22:17:26Z"}], "description": "Add tests/install/grok-build/{install.sh,verify.sh} and wire into tests/install/run-all.sh. Use Phase 0 install paths. Static verify: grok inspect asserts canonical helix plugin source path (not mere name=helix); verify-skill-layout.sh; adopter no-local-workflows path probe. Explicit skip exit semantics if grok binary unavailable (no false-fail/false-green). Functional mode list gated by TEST_FUNCTIONAL=1. Out of scope: skill content changes; progressive disclosure.", "id": "helix-26257203", "issue_type": "task", "labels": ["helix", "phase:test", "activity:test", "kind:test", "area:testing", "plan-2026-07-22", "runtime:grok", "tranche:pr4"], "owner": "erik", "parent": "helix-af0bc17b", "priority": 1, "schema_version": 1, "spec-id": "plan-2026-07-22-grok-plugin", "status": "closed", "title": "PR4: Grok install harness tests/install/grok-build", "updated_at": "2026-07-22T22:25:51.496990877Z"} {"acceptance": "`docker build -t helix-workflow-test:genie tests/workflows/genie/` succeeds (or for Genie: scripts present, no Dockerfile needed). `bash tests/workflows/genie/run-scenarios.sh --list` enumerates the 13 scenarios. Each scenario hooks into shared verifiers.", "closing_commit_sha": "1793ff4aab93799363766e793708544ba648a53c", "created_at": "2026-05-17T20:52:31.559909343Z", "description": "\nDesign for Change · Design for Simplicity · Validate Your Work · Make Intent Explicit · Prefer Reversible Decisions\nworkflow-coverage | shared-fixture | runtime-parity | refusal-hardening\ntests/workflows/fixtures/recipe-app/ is the single shared fixture across all 5 runtimes · Pass criteria are runtime-neutral; per-runtime variants vary by invocation/observability only · Static checks free, functional checks gated by TEST_FUNCTIONAL=1 · Genie scenarios may emit `genie:catalog-unreachable` skip until helix-96f7dd34 resolves · Symlink/inherit from tests/install//install.sh where reusable\nFEAT-014 RT-* · tests/install/genie/ (reference pattern) · TP-014 §7 layout\n\n\nReuse install.py + verify.py from tests/install/genie/. Add run-scenarios.py — a Playwright driver iterating each scenario against the workspace. Per-scenario test-procedure-.md for manual fallback when Playwright is unavailable. DATABRICKS_HOST + DATABRICKS_TOKEN required. Scenarios 2/4/5/6 may emit genie:catalog-unreachable skip until helix-96f7dd34 resolves.\n\nLayout: `tests/workflows/genie/Dockerfile` (symlink to tests/install/genie/Dockerfile where applicable), `install.sh` (symlink), `run-scenarios.sh` (per-scenario loop), `.tape` files per scenario, optional `recordings/` dir.", "events_attachment": "helix-264e6b8a/events.jsonl", "id": "helix-264e6b8a", "issue_type": "task", "labels": ["helix", "activity:test", "kind:test", "area:testing", "area:runtime"], "owner": "erik", "parent": "helix-88f790e4", "priority": 1, "schema_version": 1, "session_id": "eb-d9f54b6c", "spec-id": "FEAT-014", "status": "closed", "title": "RT-genie: author tests/workflows/genie/ harness", "updated_at": "2026-05-18T04:52:45.625380157Z"} {"acceptance": "Sidecar JSON and three screenshots written under tests/install/genie/recordings/; all three new types appear in their activity-specific prompt responses; baseline diff reports zero new failures; go test ./... and lefthook pre-commit pass. Depends on B7b.", "closing_commit_sha": "a74b65e7e21e13cf89228d557eaaf6f29cdadadf", "created_at": "2026-05-18T21:10:23.075059016Z", "description": "PROBLEM: Even with bundle and install confirmed, only a live Playwright drive against the Databricks Genie workspace proves the three new types are reachable via real prompts. Results must be archived as a metadata sidecar plus screenshots and compared to the 2026-05-17-verify-clean baseline to detect regressions.\n\nROOT CAUSE: tests/install/genie/drive-genie.py runs Playwright against the workspace with fresh cookies; tests/install/genie/recordings/ stores per-run metadata sidecars and screenshots. Without a fresh run after B7b there is no evidence the workspace actually surfaces the new types, and without a baseline diff a regression in any other prompt could land silently.\n\nPROPOSED FIX: Run drive-genie.py with fresh cookies; for Prompt 2 ('list the artifact types defined under activity 01-frame') and the analogous prompts for 02-design and 03-test, assert the response text contains data-prd, data-architecture, and data-quality-expectations respectively. Write tests/install/genie/recordings/2026-05-18-verify-data-types.json containing prompts, response excerpts, screenshot paths, and the manifests from B7a/B7b. Save three screenshots. Diff prompt-by-prompt against tests/install/genie/recordings/2026-05-17-verify-clean and report zero new failures.\n\nNON-SCOPE: bundle rebuild (B7a); workspace install (B7b); editing templates or SKILL.md; rotating cookies; extending baseline scope beyond the existing 2026-05-17-verify-clean prompt set.\n\nAC:\n1. TestE2eListsDataPrdIn01Frame — Prompt 2 response text includes data-prd.\n2. TestE2eListsDataArchitectureIn02Design — corresponding prompt response includes data-architecture.\n3. TestE2eListsDataQualityExpectationsIn03Test — corresponding prompt response includes data-quality-expectations.\n4. TestSidecarMetadataWritten — tests/install/genie/recordings/2026-05-18-verify-data-types.json exists and references each prompt, response, and screenshot path.\n5. TestThreeScreenshotsPreserved — exactly three new screenshots exist under tests/install/genie/recordings/ for the three prompts.\n6. TestNoNewFailuresVsBaseline — diff against tests/install/genie/recordings/2026-05-17-verify-clean shows no prompts regressing from pass to fail.\n7. TestGoSuitePasses — go test ./... passes.\n8. TestLefthookGate — lefthook run pre-commit passes.", "events_attachment": "helix-2664deb8/events.jsonl", "id": "helix-2664deb8", "issue_type": "task", "labels": ["helix", "activity:test", "kind:test", "area:artifacts", "area:integration", "area:packaging"], "parent": "helix-72f075e1", "priority": 0, "schema_version": 1, "session_id": "eb-bd5eea57", "status": "closed", "title": "B7c: Playwright e2e drive, metadata sidecar, and baseline diff", "updated_at": "2026-05-18T21:44:54.189721845Z"} {"acceptance": "Running `bash scripts/helix help` and comparing it to docs/helix/04-build/implementation-plan.md shows that every command listed under Current Command Surface is present in the help output, including `input` and `commit` if they are claimed as live surfaces.", "claimed-at": "2026-04-11T02:27:44Z", "claimed-machine": "eitri", "claimed-pid": "2204771", "closing_commit_sha": "f62cba864302333b395aa632fad6a3fc8549a085", "created_at": "2026-04-10T11:57:42.721928144Z", "dependencies": [{"issue_id": "helix-268c54ee", "depends_on_id": "helix-ea97cbda", "type": "blocks", "created_at": "2026-04-10T22:33:39Z"}], "description": "\nDesign for Change · Design for Simplicity · Validate Your Work · Make Intent Explicit · Prefer Reversible Decisions\nhugo-hextra | demo-asciinema\nTheme version: Hextra v0.12.1 — pinned in website/go.mod · Hugo version: 0.159.2 extended — pinned in .github/workflows/pages.yml · Current demos: helix-quickstart (full lifecycle), helix-concerns (drift detection), helix-evolve (requirement threading) · Agent harness: ddx agent run --harness claude — not claude -p\ndocs/helix/04-build/implementation-plan.md — Running bash scripts/helix help and comparing it to docs/helix/04-build/implementation-plan.md shows that every command listed under Current Command Surface is present in the help output, including input and commit if they are claimed as live surfaces.\n\n\nReview finding from fresh-eyes review.\nFile: docs/helix/04-build/implementation-plan.md:58\nCategory: correctness\nSeverity: medium\nDescription: The refreshed plan says the current command surface was validated against `bash scripts/helix help`, then lists `input` and groups `commit` as part of that validated surface. But `bash scripts/helix help` does not print an `input` command at all, and its Usage block omits `commit` as an invocable surface even though the dispatcher has `commit)` and `input)` handlers in scripts/helix. That leaves the implementation plan internally inconsistent with the verification source it cites, so operators using the plan cannot tell whether the CLI help is stale or the plan is overstating what the documented command surface actually is.\nSuggested fix: Make the implementation plan and `bash scripts/helix help` agree. Either remove commands from the plan until the help text advertises them, or update the help output so every command claimed in the Current Command Surface section is visible in the documented CLI surface.", "id": "helix-268c54ee", "issue_type": "task", "labels": ["helix", "activity:build", "review-finding", "area:cli", "area:docs"], "owner": "erik", "parent": "helix-13cfe23f", "priority": 0, "schema_version": 1, "spec-id": "docs/helix/04-build/implementation-plan.md", "status": "closed", "title": "correctness: reconcile implementation-plan command surface with helix help evidence", "updated_at": "2026-04-11T02:36:20.16752076Z"} diff --git a/tests/install/grok-build/install.sh b/tests/install/grok-build/install.sh new file mode 100755 index 00000000..08cca075 --- /dev/null +++ b/tests/install/grok-build/install.sh @@ -0,0 +1,53 @@ +#!/usr/bin/env bash +# Install HELIX into Grok Build from a local checkout (default) or published source. +# +# Env: +# HELIX_ROOT path to helix checkout (default: /workspace/helix or repo relative) +# TEST_PUBLISHED=1 use DocumentDrivenDX/helix instead of local path +# +# Exit: +# 0 install succeeded +# 77 grok CLI not available (caller may treat as skip) +# 1 install failed + +set -euo pipefail + +if ! command -v grok >/dev/null 2>&1; then + echo "SKIP: grok not on PATH" + exit 77 +fi + +if [[ -n "${HELIX_ROOT:-}" ]]; then + ROOT="$HELIX_ROOT" +elif [[ -d /workspace/helix ]]; then + ROOT=/workspace/helix +else + ROOT="$(cd "$(dirname "$0")/../../.." && pwd -P)" +fi + +echo "→ HELIX_ROOT=$ROOT" +grok plugin validate "$ROOT" + +set +e +if [[ "${TEST_PUBLISHED:-}" == "1" ]]; then + echo "→ grok plugin install DocumentDrivenDX/helix --trust" + out="$(grok plugin install DocumentDrivenDX/helix --trust 2>&1)" + rc=$? +else + echo "→ grok plugin install $ROOT --trust" + out="$(grok plugin install "$ROOT" --trust 2>&1)" + rc=$? +fi +set -e +printf '%s\n' "$out" +if [[ $rc -ne 0 ]]; then + if printf '%s\n' "$out" | grep -qiE 'already installed|already exists'; then + echo "→ plugin already installed; continuing" + else + echo "FAIL: grok plugin install exit $rc" + exit 1 + fi +fi + +grok plugin list +echo "install: OK" diff --git a/tests/install/grok-build/verify.sh b/tests/install/grok-build/verify.sh new file mode 100755 index 00000000..e3351b4f --- /dev/null +++ b/tests/install/grok-build/verify.sh @@ -0,0 +1,113 @@ +#!/usr/bin/env bash +# Static verify for Grok HELIX plugin install. +# +# Exit: +# 0 pass +# 77 grok not available (skip — not a failure for CI without grok) +# 1 fail + +set -euo pipefail + +if ! command -v grok >/dev/null 2>&1; then + echo "SKIP: grok not on PATH" + exit 77 +fi + +REPO_ROOT="$(cd "$(dirname "$0")/../../.." && pwd -P)" +SHARED_VERIFY="$REPO_ROOT/tests/install/shared/verify-skill-layout.sh" + +echo "→ grok plugin list" +grok plugin list + +echo "→ resolve skill root (prefer installed-plugins helix, else checkout)" +SKILL_ROOT="" +# Prefer registry-installed full plugin tree +if [[ -d "$HOME/.grok/installed-plugins" ]]; then + cand="$(find "$HOME/.grok/installed-plugins" -path '*/skills/helix/SKILL.md' 2>/dev/null | head -1 || true)" + if [[ -n "$cand" ]]; then + SKILL_ROOT="$(dirname "$cand")" + fi +fi +if [[ -z "$SKILL_ROOT" && -f "$REPO_ROOT/skills/helix/SKILL.md" ]]; then + SKILL_ROOT="$REPO_ROOT/skills/helix" +fi +if [[ -z "$SKILL_ROOT" ]]; then + echo "FAIL: could not resolve skills/helix root" + exit 1 +fi +echo "→ SKILL_ROOT=$SKILL_ROOT" + +# Canonical source: path must contain 'helix' and end with skills/helix +case "$SKILL_ROOT" in + */skills/helix) ;; + *) + echo "FAIL: skill root is not …/skills/helix: $SKILL_ROOT" + exit 1 + ;; +esac + +# Prefer non-legacy sources: reject known DDx legacy skill names when inspecting +if command -v python3 >/dev/null 2>&1; then + python3 - <<'PY' || exit 1 +import json, subprocess, sys +try: + raw = subprocess.check_output(["grok", "inspect", "--json"], text=True) + data = json.loads(raw) +except Exception as e: + print(f"WARN: grok inspect --json failed: {e}", file=sys.stderr) + sys.exit(0) + +def walk(o, out): + if isinstance(o, dict): + if o.get("name") == "helix" or ( + isinstance(o.get("source"), dict) + and "helix" in str(o.get("source")).lower() + and o.get("name") + ): + out.append(o) + for v in o.values(): + walk(v, out) + elif isinstance(o, list): + for v in o: + walk(v, out) + +found = [] +walk(data, found) +helix = [s for s in found if s.get("name") == "helix"] +if not helix: + print("FAIL: grok inspect has no skill name=helix", file=sys.stderr) + sys.exit(1) +# At least one helix skill should not be the renamed helix-workflow path only +paths = [] +for s in helix: + src = s.get("source") or {} + if isinstance(src, dict): + paths.append(str(src.get("path") or src)) + else: + paths.append(str(src)) +print("→ helix skill sources:") +for p in paths: + print(" ", p) +if any("helix-workflow" in p for p in paths) and not any( + "/skills/helix/" in p or p.endswith("skills/helix/SKILL.md") for p in paths +): + print("FAIL: only legacy helix-workflow found", file=sys.stderr) + sys.exit(1) +print("ok: canonical helix skill present in inspect") +PY +fi + +echo "→ verify-skill-layout" +bash "$SHARED_VERIFY" "$SKILL_ROOT" + +# Adopter no-local-workflows path probe against this skill root +if [[ -f "$SKILL_ROOT/../../workflows/graph.yml" ]]; then + echo "ok: full-plugin catalog via ../../workflows/graph.yml" +elif [[ -f "$SKILL_ROOT/references/graph.yml" ]]; then + echo "ok: package floor catalog via references/graph.yml" +else + echo "FAIL: neither ../../workflows/graph.yml nor references/graph.yml from skill root" + exit 1 +fi + +echo "verify: PASS" diff --git a/tests/install/run-all.sh b/tests/install/run-all.sh index 24ae4798..2e275375 100755 --- a/tests/install/run-all.sh +++ b/tests/install/run-all.sh @@ -28,6 +28,8 @@ if command -v docker >/dev/null 2>&1; then DOCKER=1; fi # marketplace/plugin install surfaces; DDx's legacy `ddx install helix` path is # intentionally not part of the release gate. TERMINAL_SCENARIOS=(claude-code codex-cli copilot-cli) +# Host-side scenarios (no Docker required). Exit 77 = skip, not failure. +HOST_SCENARIOS=(grok-build) failed=0 @@ -100,10 +102,58 @@ run_terminal_scenario() { echo "PASS: $name" } +run_host_scenario() { + local name="$1" + local dir="$TESTS_DIR/$name" + echo + echo "============================================================" + echo "scenario: $name (host)" + echo "============================================================" + if [[ ! -x "$dir/install.sh" || ! -x "$dir/verify.sh" ]]; then + # allow non-executable; bash them + if [[ ! -f "$dir/install.sh" || ! -f "$dir/verify.sh" ]]; then + echo "FAIL: missing install.sh or verify.sh in $dir" + failed=$((failed + 1)) + return + fi + fi + set +e + HELIX_ROOT="$REPO_ROOT" bash "$dir/install.sh" + local inst=$? + set -e + if [[ $inst -eq 77 ]]; then + echo "SKIP: $name (install reported skip)" + return + fi + if [[ $inst -ne 0 ]]; then + echo "FAIL: $name install exit $inst" + failed=$((failed + 1)) + return + fi + set +e + HELIX_ROOT="$REPO_ROOT" bash "$dir/verify.sh" + local ver=$? + set -e + if [[ $ver -eq 77 ]]; then + echo "SKIP: $name (verify reported skip)" + return + fi + if [[ $ver -ne 0 ]]; then + echo "FAIL: $name verify exit $ver" + failed=$((failed + 1)) + return + fi + echo "PASS: $name" +} + for scenario in "${TERMINAL_SCENARIOS[@]}"; do run_terminal_scenario "$scenario" done +for scenario in "${HOST_SCENARIOS[@]}"; do + run_host_scenario "$scenario" +done + # Genie scenario: not Docker. Calls scripts directly. echo echo "============================================================"