Skill Pathways Onboarding

Purpose

This guide is the single onboarding path for both Decision Gate usage modes:

1. DG guards execution of external skills.
2. DG is called as an evaluation skill whose comparator/RET semantics are deterministic over complete observed inputs.

It also defines how an external harness can compose both modes without allowing LLM-authored policy drift. This is not recursive scenario execution or DG-owned cross-scenario orchestration.

The repo-owned skill platform is split into two rings:

• Inner ring: decision-gate-authoring, decision-gate-verification
• Outer ring: decision-gate-execution-boundary, decision-gate-incident-triage

Which Path To Use

Intent	Path	Enforcement Strength
Mutate external state (deploy, delete, pay, publish)	DG guards skill execution	Fail-closed wrapper boundary; not an atomic DG outbox
Produce analysis/reporting/decision support	DG as evaluation skill	Computation only unless wrapped by a boundary
Multi-step agent loops that author and then execute	Harness composition (outer guard + inner evaluation)	Fail-closed outer wrapper; not atomic effect eligibility

Path A: DG Guards Skill Execution

Use this when actions have side effects.

Primary skill surface:

• decision-gate-execution-boundary for live allow/deny decisions
• decision-gate-verification for bounded post-run checks and runpack integrity
• decision-gate-incident-triage when the boundary blocks unexpectedly

Operational Contract

1. Gate ownership is human/policy-owned.
2. Gate specs are versioned artifacts, not runtime LLM inventions.
3. Every mutating skill call must pass live DG evaluation before execution.
4. An active run blocks execution; only the exact bound run status completed satisfies initial scenario finality.
5. Consequential gate specs must have an independent falsification pass before adoption; self-authored predicates are candidate policy, not proof of sufficiency.

Setup Checklist

1. Define a per-action gate map.
2. Author and register scenario specs for each action class.
3. Implement a thin runtime wrapper: evaluate -> allow/deny -> execute.
4. Export and integrity-check runpacks as derived audit/export artifacts.

Example action map:

{
  "deploy_to_prod": {
    "scenario_id": "release-boundary-v1",
    "scenario_law_identity": "<64-lowercase-hex>",
    "required_min_lane": "verified",
    "required_run_status": "completed"
  },
  "publish_external_report": {
    "scenario_id": "publication-boundary-v1",
    "scenario_law_identity": "<64-lowercase-hex>",
    "required_min_lane": "verified",
    "required_run_status": "completed"
  }
}

Example wrapper logic:

def guarded_skill_call(action_name, action_args):
    policy = action_gate_map[action_name]
    # scenario_start binds this new run to the exact immutable law identity.
    run_id = start_run(policy["scenario_id"], policy["scenario_law_identity"])
    operate_explicit_ready_stages(run_id)  # external operator/harness policy
    status = scenario_status(policy["scenario_id"], run_id)
    if status["status"] != policy["required_run_status"]:
        return {"allowed": False, "reason": "scenario_not_completed", "status": status}
    runpack = runpack_export(policy["scenario_id"], run_id)
    verify = runpack_verify(runpack["dir"], runpack["manifest_path"])
    if verify["status"] != "passed":
        return {"allowed": False, "reason": "runpack_verification_failed"}
    skill_result = call_external_skill(action_name, action_args)
    return {"allowed": True, "skill_result": skill_result, "accepted_head": status["accepted_head"]}

Implementation references:

• scenario_define, scenario_start, scenario_evaluate_stage: integration_patterns.md
• runpack audit path: integration_patterns.md
• end-to-end adapter flow: scripts/adapters/adapter_tests.sh --frameworks=openai_agents --validate

Path B: DG As Evaluation Skill

Use this for structured analysis when no direct side-effect action is executed.

Primary skill surface:

• decision-gate-authoring
• decision-gate-verification

Operational Contract

1. DG invokes deterministic comparison/RET semantics over the complete observed inputs; acquisition and current orchestration remain open-world.
2. Outputs drive explanation/reporting, not direct mutation.
3. If mutation is later requested, switch to Path A boundary first.
4. A passed evaluation reports that the declared predicates evaluated true under the exact supplied/acquired evidence and current policy semantics. It does not by itself prove evidence truth, predicate sufficiency, accepted commitment, or the unstated intent behind them.

Typical Tool Flow

1. Read the generated tool/schema resources and exact local capability profile.
2. Build artifacts: claim_inventory, capability_matrix, claim_condition_map.
3. Evaluate: scenario_precheck_stage against an exact registered law for iteration, then scenario_start -> scenario_open_stage -> scenario_evaluate_stage with hostile caller evidence or explicit bounded local-acquisition directives.
4. Export and verify runpack integrity when a derived audit/export artifact is required: runpack_export, runpack_verify.

Permanent target contract: llm_native_playbook.md. The tool sequence in this guide remains a current-contract onboarding exercise until PF-09 regenerates the executable projections.

Path C: Harness Composition (Authoring Loop + Execution Boundary)

This is the common “DG inside an agent workflow that also uses DG as its outer guard” concern. The harness sequences independent DG calls; an evaluator never invokes another scenario.

Use a ring model:

1. Inner ring: authoring and verification.
2. Outer ring: execution boundary and incident triage for consequential control.

Hard rules:

1. Inner ring may propose mappings; it may not relax outer ring policy.
2. Outer ring gate definitions remain system-authored and versioned.
3. Outer ring blocks on any unresolved required claim regardless of inner-ring confidence text.
4. The exact immutable scenario-law identity and accepted run head are the DG semantic decision sources. Base runpack verification establishes its named artifact-integrity checks; authority-assisted verification additionally revalidates the hostile law and replays accepted semantic history when that explicit path is used. Neither mode proves external-effect delivery, cross-scenario causality, recovery, deployment qualification, or policy-qualified nonrepudiation.
5. Consequential outer-ring gate changes require independent predicate falsification during authoring, before live use.

Anti-pattern to avoid:

"The agent self-evaluated with DG and therefore can deploy."

"The agent authored new predicates, passed them, and therefore the intended claim is proven."

Correct pattern:

"The agent used DG for analysis, then the system-enforced deployment gate passed live, then deploy executed."

"The authoring agent proposed predicates, a separate review attempted to falsify them, unresolved false-green risks were blocked, and only then was the gate used for closure."

Fast Onboarding Route (Repository)

Use this sequence when onboarding humans or LLM agents to both pathways.

1. Run the tested one-command quickstart (both pathways + forced deny case):

scripts/bootstrap/skill_pathways_quickstart.sh configs/presets/quickstart-dev.toml

2. Read llm_native_playbook.md and this guide.
3. Install skills:

scripts/skills/install_local.sh

4. Run end-to-end onboarding loop:

bash scripts/adapters/adapter_tests.sh --frameworks=openai_agents --validate

5. Run deterministic correctness matrix:

uv run --project . --locked --extra quality python scripts/skills/eval_runner.py \
  --mode deterministic \
  --cases all \
  --out-dir .tmp/skills/eval-deterministic-local

6. Run live required matrix for the boundary-facing skills:

uv run --project . --locked --extra quality python scripts/skills/eval_runner.py \
  --mode live \
  --cases live-required \
  --out-dir .tmp/skills/eval-live-local

Definition Of Done (No-Mistake Minimum)

Before declaring adoption complete:

1. Mutating skills are wrapped by Path A boundary logic.
2. Gate specs are versioned and policy-owned (not ad hoc prompt text).
3. All four supported skills install as self-contained packages with no repo-external references.
4. LLM-facing instructions include explicit hard-stop rules.
5. Deterministic skill eval reports pass for required cases.
6. Live required skill eval reports pass for boundary-facing cases.
7. Runpack verification passes in live boundary workflows.

Cross-References

• llm_native_playbook.md
• integration_patterns.md
• openai_agents_onboarding_playbook.md
• README.md