threadlight-governed-actions

Files (122)

• SKILL.md
• finding-catalog.json · references/
• governed-actions-apply-plan.schema.json · references/
• governed-actions-manifest.schema.json · references/
• agent_hooks_interceptor.py.tmpl · references/scaffold/
• approval-binding-fixture.json.tmpl · references/scaffold/
• governed-actions.policy.yaml.tmpl · references/scaffold/
• governed-actions.yml.tmpl · references/scaffold/
• test_governed_actions_contract.py.tmpl · references/scaffold/
• upstream-pin.json · references/
• upstream-pin.md · references/
• __init__.py · scripts/
• alerts.py · scripts/
• canonical.py · scripts/
• contracts.py · scripts/
• ghcp.py · scripts/
• governed_actions.py · scripts/
• inputs.py · scripts/
• inventory.py · scripts/
• maf_adapter.py · scripts/
• mediation.py · scripts/
• native_local.py · scripts/
• native_local_child.py · scripts/
• probes.py · scripts/
• render.py · scripts/
• scaffold.py · scripts/
• __init__.py · tests/
• conftest.py · tests/
• CODEOWNERS · tests/fixtures/approval-replay/.github/
• governed-actions.yml · tests/fixtures/approval-replay/.github/workflows/
• agent.yaml · tests/fixtures/approval-replay/
• agent.py · tests/fixtures/approval-replay/app/
• alerts.json · tests/fixtures/approval-replay/governance/
• change-plane.json · tests/fixtures/approval-replay/governance/
• installed-packages.json · tests/fixtures/approval-replay/governance/
• probe-contract.json · tests/fixtures/approval-replay/governance/
• SPEC.md · tests/fixtures/approval-replay/specs/
• CODEOWNERS · tests/fixtures/conformant-maf/.github/
• governed-actions.yml · tests/fixtures/conformant-maf/.github/workflows/
• agent.yaml · tests/fixtures/conformant-maf/
• agent.py · tests/fixtures/conformant-maf/app/
• alerts.json · tests/fixtures/conformant-maf/governance/
• change-plane.json · tests/fixtures/conformant-maf/governance/
• installed-packages.json · tests/fixtures/conformant-maf/governance/
• probe-contract.json · tests/fixtures/conformant-maf/governance/
• SPEC.md · tests/fixtures/conformant-maf/specs/
• CODEOWNERS · tests/fixtures/interceptor-failure/.github/
• governed-actions.yml · tests/fixtures/interceptor-failure/.github/workflows/
• agent.yaml · tests/fixtures/interceptor-failure/
• agent.py · tests/fixtures/interceptor-failure/app/
• alerts.json · tests/fixtures/interceptor-failure/governance/
• change-plane.json · tests/fixtures/interceptor-failure/governance/
• installed-packages.json · tests/fixtures/interceptor-failure/governance/
• probe-contract.json · tests/fixtures/interceptor-failure/governance/
• SPEC.md · tests/fixtures/interceptor-failure/specs/
• CODEOWNERS · tests/fixtures/output-streaming/.github/
• governed-actions.yml · tests/fixtures/output-streaming/.github/workflows/
• agent.yaml · tests/fixtures/output-streaming/
• agent.py · tests/fixtures/output-streaming/app/
• alerts.json · tests/fixtures/output-streaming/governance/
• …and 62 more

SKILL.md (first lines)

# Threadlight Governed Actions — implement and prove selected action paths

An agent that can only read is a demo risk. An agent that can *write*, *egress*,
or do something *irreversible* is a production risk, and the question a customer
actually asks is narrow: **when this agent takes a consequential action, what
stops it, who approved it, and where is the record?**

For implementation requests, produce actual selected runtime templates using
[generate.py](../threadlight-deploy/references/governance/generate.py) and its
[configuration/ordering contract](../threadlight-deploy/references/governance/README.md).
Use `threadlight-govern` for the real ACS bundle and authorized signed distribution;
implement the host-owned application seam, not an allow-only test adapter.
Assessment alone is not implementation. Deployment remains separately authorized.

For [signed business evidence](../../docs/signed-evidence.md), the assessor retains
`signed-evidence-proof-required` as `not-verified`: generic probes, LOCAL-14 and
hosted noop receipts cannot establish an issuer/profile/source-revision contract.
Catalog JWT/MCP fixtures do not close a customer's business acceptance gate.

For consent by the **requesting user**, `user-confirmation-proof-required` also
remains `not-verified`: generic approval probes cannot prove matching user
identity, the selected provider's assurance, a real out-of-band decision or the
deployment's one-use confirmation flow. It is distinct from third-party review.
Use the actual confirmation runtime and retain separate target-bound acceptance;
an email, local test or noop receipt is not MFA or business-write proof.

The **assessor CLI** is read-only by default and renders a deterministic manifest,
evidence pack and never-self-applying remediation plan. These are selected-path
evidence, **not whole-agent** governance. SAFE is the method, ACS/Rego the PDP,
Agent Hooks the host/interceptor contract, native host/gateway the PEP, AGT the
toolkit, and ASSERT assurance.

### Native selected local proof

The current `LOCAL-14` producer runs the actual served application/native path
and returns assessor-verified allow/deny/failure/approval/terminal-effect proof.
The standalone export includes `.governance-tools`, exact-pin tooling, official
CTK sources/test-oracle build inputs and native-local CI. Follow the generated
commands; do not depend on a catalog checkout accidentally on `PYTHONPATH`.
Native/CTK uses published unmodified execution packages: 47 declared vectors,
four undeclared incremental-output vectors and only a corrected test oracle.
Native APIs are preview/alpha, with explicit experimental defaults.

Unbound reads remain unbound and never invoke ACS. Selected bindings require
signed fresh policy, host-trusted facts, authenticated one-use human approval
when required, and central audit ACK before effects. Recheck after awaits at
the actual terminal target; a check at function start is insufficient. GHCP
supports registered gateway effects only, not arbitrary URLs/shells or full
lifecycle/output coverage. `enforced`, `observed`, `unbound`, `unverified`,
`unsupported` and `bypassable` are binding statuses, not whole-agent verdicts.

Local proof remains local. The Task11 collector only invokes the reserved,
registered `governance_probe_noop`; it cannot certify business bindings.
`returns_apply_decision` has local Cosmos decision/audit proof, not live payment
or settlement proof. A new deployment requires fresh after-deploy evidence;
policy/CI or legacy v2 green cannot replace it.

```
declared actions ─┐
implemented code ─┼─► inventory ─► mediation graph ─► application probes ─┐
policy/approval  ─┘                                                       ├─► manifest
workflows/CODEOWNERS ─────────────► change-plane assessment ──────────────┤   evidence pack
alert catalog ────────────────────► alert posture ────────────────────────┘   apply plan
```

## When to invoke

| Phase | Invoke | What it proves |
| --- | --- | --- |
| `design` | after `threadlight-design`, before code exists | the SPEC § 8 action declaration is complete and every action has an explicit consequence class |
| `pre-deploy` | before `threadlight-deploy` | declared and implemented actions agree; path-bound allow/deny receipts verify mediation candidates; separate generic probes exercise deny/transform/fail-closed, approval anti-replay, output gating, and payload-free audit |
| `post-deploy` | **staging only** | the same assessment against a deployed non-production environment; `--phase post-deploy` refuses to run without `--staging-resource-group` naming an explicit, non-production staging resource group |

`post-deploy` is deliberately staging-only. This skill never runs, not even
read-only, against an unnamed or production environment.

## Inputs

Everything is repository-relative and read-only. Nine categories, each an
explicit rule — discovery never widens into "anything under the repository":

| Input | Where | Used by |
| --- | --- | --- |
| SPEC action declaration | `specs/SPEC.md` § 8 (required for `design`/`pre-deploy`) | `ACT-001`, `ACT-002` |
| Action registries | `agent.yaml`, `agent.yml`, `tool-registry.json`, `tool_registry.json` (target root) | `ACT-001`, `ACT-002` |
| Runtime + middleware source | every non-vendored `*.py` under the target | `MED-001`..`MED-003`, `ENF-001`, `ENF-002` |
| Policy files | `governance/**/*.{json,yaml,yml}`, `policies/**/*.{json,yaml,yml}` | `MED-001`, `ENF-001` |
| Approval handling | runtime files whose AST references `issue_approval`, `consume_approval`, `redeem_approval`, or `ApprovalHandler` | `APR-001` |
| Tests, conformance, evals | `tests/**`, `**/conformance/**`, `**/evals/**` | `ENF-001`, `GHCP-003`, `PIN-001` |
| Workflows | `.github/workflows/*.yml`, `*.yaml` (direct children) | `GHCP-001`, `GHCP-003`..`GHCP-006` |
| Ownership | `CODEOWNERS` and `.github/CODEOWNERS` | `GHCP-002` |
| Dependency pins | `pyproject.toml`, `requirements*.txt`, lockfiles | `PIN-001` |
| Alert catalog | `governance/alerts.json` | `OPS-001` |
| Optional live evidence | `--live-github` (`gh api`), `--subscription`/`--deploy-identity` (`az ... list`) | `GHCP-002`, `GHCP-006` |

Optional live evidence is exactly that: **optional**. When it is not selected, or
when a permission is missing, the affected control is reported `not-verified`.
A `not-verified` finding is never silently converted to `pass`.

## Path-bound execution contract

`governance/probe-contract.json` must declare one importable application
execution dispatcher and bind every assessor-discovered, non-provider mediation
path to its recomputed path id and action/mode routing-table key:

```json
{
  "dispatch": "app.agent:dispatch",
  "execution_dispatch": "app.agent:dispatch_execution_path",
  "execution_paths": [
    {
      "action_id": "payments.refund",
      "mode": "background",
      "path_id": "400019bbedc16b75"
    }
  ]
}
```

From aiappsgbb/threadlight-skills, MIT.

More from aiappsgbb/threadlight-skills