@mutagent/helix 0.1.0-alpha.14

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/assets/templates/shared/self-diagnosis-contract.v0.1.0.yaml.tpl

@@ -0,0 +1,234 @@
+# self-diagnosis-contract.yaml — FROZEN SCHEMA v0.1.0
+# ═════════════════════════════════════════════════════════════════════════════
+# This file is the inter-skill CONTRACT. Any skill that wants STRUCTURED
+# (rather than open-ended) diagnostic reports about its own behavior ships a
+# populated copy of this template at:
+#
+#     <skill-source-root>/self-diagnosis-contract.yaml
+#
+# A diagnostic skill (any tool that ingests traces and emits findings) MAY
+# look for this file when targeting <skill>. If present → structured report
+# per declared criteria. If absent → open-ended pattern-match (status quo).
+#
+# Schema is FROZEN at v0.1.0. Mid-flight changes FORBIDDEN. New versions ship
+# as NEW filenames (self-diagnosis-contract.v0.2.0.yaml.tpl).
+# ═════════════════════════════════════════════════════════════════════════════
+
+schema_version: "0.1.0"
+
+# ─── Subject identification ───────────────────────────────────────────────────
+skill:
+  name: "{{skill_name}}"                  # e.g. mutagent-some-skill (no leading @)
+  version: "{{skill_version}}"            # semver
+  class: "{{skill_class}}"                # one of: pure-procedural | orchestrator | tool-skill | meta-skill
+
+# ─── 10-CATEGORY SUCCESS CRITERIA (Hybrid decomposition · operator-locked 2026-05-31) ──
+#
+# The 10 categories cover: Operational / Onboarding / Behavioral / HITL /
+# Output / Methodology / Tier-performance / Source-platform health /
+# Target-platform health / Maintenance.
+#
+# Each category contains a `criteria[]` array. Each criterion has:
+#   id              — kebab-case stable identifier
+#   statement       — binary observable assertion ("X happens")
+#   evidence_source — one of: trace | commit | cmd-output | file:line | screenshot
+#
+# Producer skills evaluate per-criterion against the target's trace and emit
+# a result per criterion: pass | fail | not-applicable | pending.
+#
+# Skills SHOULD declare ≥1 criterion per relevant category and MAY skip
+# categories that don't apply to their class (e.g. tool-skill class has no
+# HITL gates → leave category present with `criteria: []` and a `notes:` line).
+# ─────────────────────────────────────────────────────────────────────────────
+success_criteria:
+
+  # ──── 1. OPERATIONAL ────────────────────────────────────────────────────────
+  # Install / invoke / runtime / exit hygiene.
+  - category: operational
+    notes: "install / invoke / runtime detection / exit codes"
+    criteria:
+      - id: "{{op_criterion_1_id}}"
+        statement: "{{op_criterion_1_statement}}"
+        evidence_source: "{{op_criterion_1_evidence_source}}"
+      # Append additional operational criteria as needed.
+
+  # ──── 2. ONBOARDING ─────────────────────────────────────────────────────────
+  # First-time UX / platform detection / config persistence.
+  - category: onboarding
+    notes: "first-invocation routing / platform detect / config persist"
+    criteria:
+      - id: "{{on_criterion_1_id}}"
+        statement: "{{on_criterion_1_statement}}"
+        evidence_source: "{{on_criterion_1_evidence_source}}"
+
+  # ──── 3. BEHAVIORAL / AGENT HANDOFFS ───────────────────────────────────────
+  # Dispatch → return / cap-of-5 fan-out / orphan check / sub-agent contracts.
+  - category: behavioral
+    notes: "agent dispatch + return + cap-of-5 + orphan check"
+    criteria:
+      - id: "{{bh_criterion_1_id}}"
+        statement: "{{bh_criterion_1_statement}}"
+        evidence_source: "{{bh_criterion_1_evidence_source}}"
+
+  # ──── 4. HITL GATES ─────────────────────────────────────────────────────────
+  # AskUserQuestion fires correctly + clipboard handoff (or platform-fallback).
+  - category: hitl
+    notes: "AskUserQuestion fires + clipboard handoff + chat-fallback works"
+    criteria:
+      - id: "{{hi_criterion_1_id}}"
+        statement: "{{hi_criterion_1_statement}}"
+        evidence_source: "{{hi_criterion_1_evidence_source}}"
+
+  # ──── 5. OUTPUT ─────────────────────────────────────────────────────────────
+  # Report schema / template-stamp discipline / payload contracts.
+  - category: output
+    notes: "output artifacts conform to declared schema; template-stamp not procedural"
+    criteria:
+      - id: "{{os_criterion_1_id}}"
+        statement: "{{os_criterion_1_statement}}"
+        evidence_source: "{{os_criterion_1_evidence_source}}"
+
+  # ──── 6. METHODOLOGY HYGIENE ───────────────────────────────────────────────
+  # Step 0 census, assumption enumeration, evidence grounding, recursive whys.
+  - category: methodology
+    notes: "Step 0 census + assumptions + evidence-grounded findings + recursive whys"
+    criteria:
+      - id: "{{me_criterion_1_id}}"
+        statement: "{{me_criterion_1_statement}}"
+        evidence_source: "{{me_criterion_1_evidence_source}}"
+
+  # ──── 7. TIER / PERFORMANCE ────────────────────────────────────────────────
+  # Tier 0 → LLM gating / budgets / cap-of-5 / relative thresholds (not hardcoded).
+  - category: tier-performance
+    notes: "Tier 0 scan before LLM + budgets + relative thresholds (no hardcoded ms/token)"
+    criteria:
+      - id: "{{tp_criterion_1_id}}"
+        statement: "{{tp_criterion_1_statement}}"
+        evidence_source: "{{tp_criterion_1_evidence_source}}"
+
+  # ──── 8. SOURCE-PLATFORM HEALTH ────────────────────────────────────────────
+  # For skills that consume external sources (traces, transcripts, JSONL etc).
+  - category: source-platform
+    notes: "if skill ingests sources: each source primitive normalizes correctly"
+    criteria:
+      - id: "{{sp_criterion_1_id}}"
+        statement: "{{sp_criterion_1_statement}}"
+        evidence_source: "{{sp_criterion_1_evidence_source}}"
+
+  # ──── 9. TARGET-PLATFORM HEALTH ────────────────────────────────────────────
+  # For skills that emit changes to external targets (local-agent .md / cloud REST etc).
+  - category: target-platform
+    notes: "if skill applies changes: each target adapter behaves per contract"
+    criteria:
+      - id: "{{tg_criterion_1_id}}"
+        statement: "{{tg_criterion_1_statement}}"
+        evidence_source: "{{tg_criterion_1_evidence_source}}"
+
+  # ──── 10. MAINTENANCE ───────────────────────────────────────────────────────
+  # doctor / self-diagnosis / audit emit / version-pin / SKILL.md frontmatter integrity.
+  - category: maintenance
+    notes: "doctor.ts + audit emit + version pinned + frontmatter intact"
+    criteria:
+      - id: "{{mt_criterion_1_id}}"
+        statement: "{{mt_criterion_1_statement}}"
+        evidence_source: "{{mt_criterion_1_evidence_source}}"
+
+# ─── SCENARIO MATRIX ─────────────────────────────────────────────────────────
+# Operator-runnable scenarios that exercise the skill end-to-end. A diagnostic
+# tool consuming this contract attempts to MATCH trace evidence against each
+# scenario's trigger pattern, then evaluates acceptance_gate.
+#
+# Each scenario:
+#   id              — kebab-case unique id (e.g. s1-happy-path, s2-error-edge)
+#   trigger         — what kicks the scenario off (CLI invocation / API call / event)
+#   expected        — observable end-state (one-line description)
+#   acceptance_gate — concrete verification: command exit / metric / predicate / llm-judge
+# ─────────────────────────────────────────────────────────────────────────────
+scenarios:
+  - id: "{{scenario_1_id}}"
+    trigger:
+      type: "{{scenario_1_trigger_type}}"     # cli | api | event | chat
+      payload: "{{scenario_1_trigger_payload}}" # literal invocation string
+    expected: "{{scenario_1_expected}}"        # 1-line observable end-state
+    acceptance_gate:
+      gate_type: "{{scenario_1_gate_type}}"    # command-exit | metric-threshold | predicate | llm-judge
+      gate_spec: "{{scenario_1_gate_spec}}"    # type-specific specification
+
+  # Append additional scenarios. Recommended ≥3 (happy / edge / failure-mode).
+
+# ─── TRAJECTORY LOG FORMAT ───────────────────────────────────────────────────
+# Append-only log of captured invocations of THIS skill, in a shape that
+# downstream diagnostic tools can ingest without transformation.
+#
+# Each trajectory entry:
+#   invocation_id      — UUID stamped at invocation time
+#   captured_at        — ISO8601 timestamp
+#   scenario_id        — matches a scenarios[].id above OR "freeform"
+#   trace_refs         — pointers to the underlying trace evidence
+#   diagnostics_ingestable — true = no transformation needed; false = needs adapter
+#   summary            — 1-sentence what happened
+#   findings_count_by_audience — counts per PRODUCT/META/CORE audience tag
+# ─────────────────────────────────────────────────────────────────────────────
+trajectory_log_format:
+  schema:
+    invocation_id: "string (uuid v4)"
+    captured_at: "string (ISO8601)"
+    scenario_id: "string (matches scenarios[].id) | 'freeform'"
+    trace_refs:
+      langfuse_session: "string | null"
+      playwright_trace: "string (path) | null"
+      claude_code_session: "string (jsonl path) | null"
+      otel_span: "string (span id) | null"
+    diagnostics_ingestable: "boolean"
+    summary: "string (≤1 sentence)"
+    findings_count_by_audience:
+      PRODUCT: "integer ≥0"
+      META: "integer ≥0"
+      CORE: "integer ≥0"
+
+  # Default landing path. Skill may override to relocate within its source tree
+  # but the SHAPE above is fixed (so diagnostic tools can ingest without
+  # per-skill adapters).
+  default_landing_path: "<skill-feature-dir>/trajectory-log.yaml"
+
+# ─── EVIDENCE LANDING PATHS ─────────────────────────────────────────────────
+# Where the producer skill should write structured artifacts when emitting
+# a report against this contract.
+# ─────────────────────────────────────────────────────────────────────────────
+evidence_landing_paths:
+  test_report_yaml: "{{landing_test_report_yaml}}"        # default: <skill-feature-dir>/test-report.yaml
+  trajectory_log_append_to: "{{landing_trajectory_log}}"  # default: <skill-feature-dir>/trajectory-log.yaml
+  llm_judge_results_dir: "{{landing_llm_judge_dir}}"      # default: <skill-feature-dir>/llm-judge-evals/
+
+# ─── AUDIENCE TAG HINTS (optional) ──────────────────────────────────────────
+# Guidance for producer skills' audience-tag classifiers (PRODUCT / META / CORE).
+# Skill can supply patterns matching its own typical failure origins to help
+# the classifier route findings correctly without operator override.
+# ─────────────────────────────────────────────────────────────────────────────
+audience_tag_hints:
+  finding_patterns:
+    - pattern: "{{audience_hint_1_pattern}}"          # regex on failureOrigin.where or .what
+      default_audience: "{{audience_hint_1_audience}}" # one of: PRODUCT | META | CORE
+
+# ═════════════════════════════════════════════════════════════════════════════
+# Schema-freeze invariants (DO NOT VIOLATE)
+# ═════════════════════════════════════════════════════════════════════════════
+# 1. The 10 categories above are the COMPLETE canonical set for v0.1.0. No
+#    skill may add or rename categories within this schema version. New
+#    categories require a versioned bump (v0.2.0 — new file).
+#
+# 2. Each criterion's `evidence_source` MUST be one of the 5 allowed values:
+#    trace | commit | cmd-output | file:line | screenshot. No free-form
+#    evidence sources.
+#
+# 3. Each scenario's `gate_type` MUST be one of the 4 allowed values:
+#    command-exit | metric-threshold | predicate | llm-judge.
+#
+# 4. trajectory_log_format.schema is the SHAPE producer skills must emit when
+#    appending to a target's trajectory log. Adding fields is forbidden
+#    within this version (forward-compat only via versioned bump).
+#
+# 5. audience tags are the 3 from the established taxonomy: PRODUCT (user-
+#    visible behavior), META (methodology / discipline observations), CORE
+#    (runtime engine / scripts / sub-agents).
+# ═════════════════════════════════════════════════════════════════════════════

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/assets/templates/shared/spec.yaml.tpl

@@ -0,0 +1,152 @@
+# spec.yaml — afkloop spec for {{wave_id}}
+# Template extracted from afkloop-mdiag-w2 spec.yaml (proven across 5 iterations).
+# Consumer renderer fills {{...}} placeholders at install / dispatch time.
+
+afkloop_id: {{wave_id}}
+intent: |
+  {{wave_intent_paragraph}}
+
+scope:
+  files:
+    {{#each scope_files}}
+    - {{path_glob}}
+    {{/each}}
+  repos: [{{repos_csv}}]
+  worktree_path: {{worktree_path}}
+  branch: {{branch}}
+  pr_trunk: {{pr_trunk_number}}
+
+goal_condition:
+  type: observable
+  predicate: |
+    {{goal_predicate}}
+  probe_interval: {{probe_interval}}
+
+termination_gates:
+  max_iterations: {{max_iterations}}
+  max_wallclock_minutes: {{max_wallclock_minutes}}
+  max_consecutive_failures: {{max_consecutive_failures}}
+  max_tokens_spent: {{max_tokens_spent}}
+  on_scope_creep: abort
+  on_phase_complete: {{on_phase_complete_action}}
+
+# ────────────────────────────────────────────────────────────────────────────
+# DISPATCH GATE — hard pre-spawn check
+# ────────────────────────────────────────────────────────────────────────────
+# NO TeamCreate, NO Agent() spawn may proceed for iteration N without
+# operator-approved review artifacts present + an approval signal file on
+# disk. iter-1 of each wave MAY be grandfathered per `precedent_record`.
+dispatch_gate:
+  scope: {{dispatch_gate_scope}}
+  required_artifacts_before_dispatch:
+    {{#each required_dashboard_artifacts}}
+    - path: {{path}}
+      semantics: {{semantics}}
+    {{/each}}
+  required_signal_file:
+    path: {{approval_flag_path_template}}
+    semantics: |
+      Created ONLY by operator via clipboard-export from the iter-N dashboard
+      lockin block (LOCK / REVISE / HOLD / DROP radios + decision textarea).
+      Orchestrator MUST verify file exists + has non-zero size before any
+      Agent() / TeamCreate call.
+  enforcement:
+    mode: refuse_spawn_with_message
+    error_message: |
+      Iteration <N> requires operator-approved review artifacts + the
+      iter-<N>-approved.flag signal file. Dispatch REFUSED. Operator must
+      review the rendered artifacts and clipboard-export their decision.
+  precedent_record:
+    {{#each precedent_records}}
+    {{iter_label}}: |
+      {{precedent_text}}
+    {{/each}}
+
+iteration_contract:
+  inputs:
+    {{#each iteration_inputs}}
+    - {{description}}
+    {{/each}}
+  one_tick_does: |
+    {{one_tick_does_paragraph}}
+
+  deliverables:
+    code_artifacts:
+      {{#each code_artifacts}}
+      - "{{artifact}}"
+      {{/each}}
+    design_review_artifacts:
+      {{#each design_review_artifacts}}
+      {{key}}:
+        path: {{path}}
+        purpose: |
+          {{purpose}}
+      {{/each}}
+
+agent_team:
+  actor:
+    subagent_type: {{actor_subagent_type}}
+    prompt_template: |
+      MANDATORY PRE-READ:
+        cat {{handover_path_template}}
+      {{actor_prompt_body}}
+  verifier:
+    subagent_type: {{verifier_subagent_type}}
+    role: {{verifier_role}}
+    watches:
+      {{#each verifier_watch_sources}}
+      - {{source}}
+      {{/each}}
+    can_inject: [course-correct, abort, escalate-to-user]
+
+live_steering_protocol:
+  mode: checkpoint
+  checkpoint_triggers:
+    {{#each checkpoint_triggers}}
+    - {{trigger}}
+    {{/each}}
+
+observability:
+  tasklist_prefix: "[{{wave_id}}]"
+  per_iter_log: {{per_iter_log_path_template}}
+  per_iter_handover: {{per_iter_handover_path_template}}
+  views_anchor:
+    {{#each views_anchors}}
+    {{key}}: {{path}}
+    {{/each}}
+
+exit_behavior:
+  on_success: |
+    {{on_success_text}}
+  on_gate_hit: |
+    {{on_gate_hit_text}}
+  on_user_interrupt: |
+    {{on_user_interrupt_text}}
+  on_phase_complete: |
+    {{on_phase_complete_text}}
+
+skill_handover:
+  parent_skills:
+    {{#each parent_skills}}
+    - {{skill_name}}
+    {{/each}}
+  inline_files:
+    # Pulled into iter-N-handover.md verbatim at Phase 1.5
+    {{#each inline_files}}
+    - {{path}}
+    {{/each}}
+  handover_doc: {{handover_doc_path_template}}
+
+prior_session_artifacts:
+  {{#each prior_session_artifacts}}
+  - path: {{path}}
+    description: {{description}}
+  {{/each}}
+
+known_gotchas:
+  {{#each known_gotchas}}
+  - id: {{id}}
+    description: {{description}}
+    workaround: {{workaround}}
+    source: {{source}}
+  {{/each}}

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/assets/templates/shared/team.yaml.tpl

@@ -0,0 +1,127 @@
+# team.yaml — afkloop team for {{wave_id}}
+# Template extracted from afkloop-mdiag-w2 team.yaml (proven across 5 iterations).
+# Consumer renderer fills {{...}} placeholders at install / dispatch time.
+
+team:
+  name: {{wave_id}}-iter-{N}
+  lifecycle: per-iteration   # TeamCreate at tick start, TeamDelete at tick end
+
+  # ──────────────────────────────────────────────────────────────────────
+  # PRE-SPAWN GATE — see spec.yaml dispatch_gate for full rationale
+  # ──────────────────────────────────────────────────────────────────────
+  pre_spawn_gate:
+    skip_for_iterations: [{{grandfather_iterations_csv}}]
+    required_files_exist:
+      {{#each required_review_files}}
+      - {{path_template}}
+      {{/each}}
+    required_signal_file:
+      path: {{approval_flag_path_template}}
+      check: test -s
+    on_failure: |
+      REFUSE TeamCreate AND any Agent() spawn for iter-{N}. Print error,
+      surface paths to operator, await re-invocation after approval.
+      ABORT cascades up to the parent orchestrator — do NOT silently
+      proceed. Do NOT improvise around the gate.
+
+  actor:
+    type: {{actor_agent_type}}
+    scope:
+      {{#each actor_scope_globs}}
+      - {{glob}}
+      {{/each}}
+    forbidden_paths:
+      - .github/workflows/**     # infra changes deferred to end-of-wave PR
+      - Dockerfile**
+      - tsconfig*.json
+      - bunfig.toml
+      - .claude/settings.local.json   # operator-owned on root
+      {{#each additional_forbidden_paths}}
+      - {{glob}}
+      {{/each}}
+    prompt: |
+      You are the Actor for {{wave_id}} iteration {N}{{actor_phase_suffix}}.
+
+      MANDATORY PRE-READ:
+        cat {{handover_path_template}}
+
+      This handover contains:
+        - The {{phase_descriptor}} scope (your task)
+        - Skill operational contracts (relevant SKILL.md + workflow refs) inlined
+        - Per-remedy acceptance commands
+        - Known gotchas
+        - Drift from prior iterations + rediscovery promotions
+        - Scope envelope + forbidden paths
+
+      Internalize handover BEFORE editing. Then:
+        1. Implement remedies in handover-specified order (within-phase deps)
+        2. ONE commit per remedy, message prefixed with remedy ID
+        3. Run acceptance commands LOCALLY before pushing
+        4. Push to {{branch}}
+        5. Emit checkpoints at: plan internalized, first commit pushed, all commits done, acceptance run
+
+      Hard constraints:
+        - Do NOT merge to main
+        - Do NOT touch forbidden_paths
+        - Do NOT skip pre-commit hooks (--no-verify FORBIDDEN per feedback_correctness_discipline)
+        - On Verifier SendMessage with binding steering — comply
+
+      {{additional_actor_constraints}}
+
+      On phase complete: post PR Final-Status comment per feedback_pr_final_status_comment.md.
+
+  verifier:
+    type: {{verifier_agent_type}}
+    role: live-steering-observer + handover-saturation-auditor
+    ground_truth_sources:
+      {{#each verifier_ground_truth_sources}}
+      - {{source}}
+      {{/each}}
+    prompt: |
+      You are the Verifier for {{wave_id}} iteration {N}.
+      You do NOT execute the implementation.
+
+      VERIFIER CONTEXT INVERSION — you receive the SUPERSET of Actor's brief:
+        - Full iter-{N}-handover.md (same as Actor)
+        - All skill operational contracts (SKILL.md + workflow refs)
+        - prior_session_artifacts catalog (so you can cross-reference)
+        - known_gotchas catalog (so you can pre-empt rediscovery)
+        - Verifier-only ground-truth probes (do NOT run as Actor's behalf)
+
+      GOAL (this iteration): {{verifier_goal_summary}}.
+      Hard gates: scope envelope, forbidden_paths, no-merge-to-main, no --no-verify.
+
+      {{additional_verifier_invariants}}
+
+      Monitor Actor's task output. On each checkpoint:
+        - Read Actor's stated plan + diff so far
+        - Cross-check against handover-inlined contracts
+        - Check scope compliance (in scope + not forbidden)
+        - Check drift from THIS phase's remedy IDs
+        - Decide: PROCEED (silent) | STEER (SendMessage Actor) | ABORT (SendMessage Orchestrator)
+
+      Steering messages must be SPECIFIC + REASONED + MINIMAL.
+      Drift in ≥3 dimensions = ABORT not STEER (per anti-pattern table).
+
+      On iteration end, list REDISCOVERY EVENTS (Actor probed --help / introspection
+      / trial-and-error that should have been in handover). These get promoted into
+      iter-{N+1}-handover.md known_gotchas. Loop converges toward zero rediscovery
+      per iteration.
+
+      Final verdict: PASS | RETRY | ABORT.
+      On PASS — confirm phase Final-Status comment is accurate before authorizing
+      pause-for-dogfood.
+
+per_phase_overrides:
+  {{#each per_phase_overrides}}
+  {{iter_label}}:
+    phase: {{phase_letter}}
+    remedies: [{{remedies_csv}}]
+    risk_pill: {{risk_pill_class}}
+    estimated_hours: {{estimated_hours}}
+    acceptance:
+      {{#each acceptance_commands}}
+      - {{cmd}}
+      {{/each}}
+    {{optional_phase_notes}}
+  {{/each}}