diff --git a/docs/adapters/add-a-harness.md b/docs/adapters/add-a-harness.md index 507e04724..87af5ac0c 100644 --- a/docs/adapters/add-a-harness.md +++ b/docs/adapters/add-a-harness.md @@ -89,23 +89,24 @@ they run and denies ones that break hard framework rules (unauthorized each harness gets a thin adapter translating its hook format. **For runtimes with a pre-tool hook API:** add an adapter following the -existing Claude Code and OpenCode examples. +existing OpenCode example. ```text tools/agent-guard/ - agent_guard/__init__.py ← dispatch() core (harness-agnostic) - agent_guard/adapters/ - claude.py ← reads stdin JSON, writes stdout JSON - opencode.py ← reads stdin JSON, throws on block - .py ← same shape; translate your hook format + src/agent_guard/__init__.py ← dispatch() core (harness-agnostic) + src/agent_guard/__main__.py ← CLI entry point (stdin JSON → stdout JSON) + src/agent_guard/guards.d/ ← individual guard scripts + opencode/plugin.js ← OpenCode adapter (JS plugin) + tests/ ← test suite incl. per-harness tests ``` -The adapter must: -1. Parse the harness's pre-tool hook payload (stdin JSON, env vars, or - CLI args — check the runtime docs). -2. Call `dispatch(command_string)` from the core. -3. Return the harness's expected "allow" or "block" response (format - varies per harness). +The core (`__init__.py`) exposes a `dispatch()` function. Per-harness +adapters translate the runtime's hook format into a `dispatch()` call. +Your adapter must: +1. Parse the harness's pre-tool hook payload (stdin JSON, env vars, + CLI args, or a native plugin format — check the runtime docs). +2. Call `dispatch(command_string)` from the core module. +3. Return the harness's expected "allow" or "block" response. Run the guard's test suite to verify the adapter: diff --git a/docs/education/pattern-catalogue.md b/docs/education/pattern-catalogue.md index eeadb0641..564dce84a 100644 --- a/docs/education/pattern-catalogue.md +++ b/docs/education/pattern-catalogue.md @@ -240,25 +240,32 @@ security email, reporter contact details, issue bodies from private trackers. **The pattern (prose block in the skill):** -```markdown +````markdown ## Privacy routing Mail bodies and issue contents for this step may carry third-party PII (names, email addresses, handles). Before passing content to the model: -1. Run the redactor: `python -m privacy_llm.redactor redact - --input --output --map `. -2. Pass `` to the model. +1. Pipe content through the redactor: + ```bash + echo "" | uv run --project /tools/privacy-llm/redactor \ + pii-redact --field name:"Third Party" --field email:"third@example.com" + ``` +2. Pass the redacted output to the model. 3. After the model step, restore identifiers for any user-facing - output that must include them: `python -m privacy_llm.redactor - restore --input --map `. - -The mapping file (``) is session-local and is deleted at the -end of the skill run. It never leaves the local machine. See + output that must include them: + ```bash + echo "" | uv run --project /tools/privacy-llm/redactor \ + pii-reveal + ``` + +The redactor's map is session-local (`~/.config/apache-magpie/pii-map/`) +and is deleted at the end of the skill run. It never leaves the local +machine. See [`tools/privacy-llm/pii.md`](../../tools/privacy-llm/pii.md) for the full redaction contract. -``` +```` **Why it works:** the three steps (clean, then model, then restore) are the only safe order. Restoring the real names after the model step lets the user see diff --git a/docs/release-management/process.md b/docs/release-management/process.md index 50f0e8f37..d1b041f1b 100644 --- a/docs/release-management/process.md +++ b/docs/release-management/process.md @@ -79,17 +79,6 @@ adopter's `pmc-roster.md` for ASF projects, or files share the same schema (handle, binding-flag, optional GPG fingerprint). -> [!IMPORTANT] -> Release Management is **proposed** in the framework today. No -> `release-*` skill code exists yet. This document, the family -> [`README.md`](README.md), the [`spec.md`](spec.md), and -> [`projects/_template/release-management-config.md`](../../projects/_template/release-management-config.md) -> land first so the lifecycle, the state-change boundaries, and the -> adopter contract are reviewable independently from the runtime -> behaviour. The pattern matches [Mentoring](../mentoring/spec.md). -> See [`docs/modes.md` § Drafting / Triage](../modes.md#drafting) -> for status. - ## Process reference: the 14 steps This is the authoritative outline of the 14-step lifecycle. Each @@ -165,7 +154,7 @@ vote, green = publication and follow-up. **Owner:** PMC + nominated Release Manager (RM). **Skill:** `release-prepare` -*(proposed)*, Agentic Drafting. +Agentic Drafting. The RM opens a planning issue listing the target version, the release train it belongs to (see @@ -186,7 +175,7 @@ and adapts. **Owner:** RM. **Skill:** `release-prepare` -*(proposed)*, Agentic Drafting (same skill as Step 1, second invocation). +Agentic Drafting (same skill as Step 1, second invocation). The skill drafts the changelog entry from the merged-PR set since the previous release tag, the `NOTICE` diff (third-party @@ -213,7 +202,7 @@ after their own review. **Owner:** RM. **Skill:** `release-keys-sync` -*(proposed)*, Agentic Drafting. +Agentic Drafting. If the RM is signing their first release for the project, their public key must appear in the project's `KEYS` file under @@ -232,7 +221,7 @@ no-op and reports so on the planning issue. **Owner:** RM. **Skill:** `release-rc-cut` -*(proposed)*, Agentic Drafting. +Agentic Drafting. The skill emits a paste-ready command sequence: @@ -265,7 +254,7 @@ Step 13. **Owner:** RM. **Skill:** `release-rc-cut` -*(proposed)*, Agentic Drafting (same skill as Step 4). +Agentic Drafting (same skill as Step 4). The skill emits the `svn` command sequence to import the artefacts + `.asc` + `.sha512` files into @@ -283,7 +272,7 @@ back to the planning issue. **Owner:** RM (self-check) + any committer who plans to vote. **Skill:** `release-verify-rc` -*(proposed)*, Agentic Triage / Agentic Pairing. +Agentic Triage / Agentic Pairing. Read-only. The skill fetches the staged artefacts from `dist/dev//-rcN/`, then verifies: @@ -318,7 +307,7 @@ conversation. **Owner:** RM. **Skill:** `release-vote-draft` -*(proposed)*, Agentic Drafting. +Agentic Drafting. The skill drafts the `[VOTE]` email body to `dev@` from the planning issue's metadata: version, RC number, staging URL, @@ -348,7 +337,7 @@ its hand-off rules, vote discussion is PMC business). **Owner:** RM. **Skill:** `release-vote-tally` -*(proposed)*, Agentic Triage. +Agentic Triage. After the window closes, the skill fetches the thread from the project's mail archive (PonyMail by default), parses each reply, @@ -378,7 +367,7 @@ planning issue on a failed vote. **Owner:** RM. **Skill:** `release-promote` -*(proposed)*, Agentic Drafting. +Agentic Drafting. The skill emits a paste-ready `svn mv` command set that moves the voted artefacts from @@ -411,7 +400,7 @@ set (see [`release-promote` § hand-off](spec.md#release-promote)). **Owner:** RM (`[ANNOUNCE]`) + PMC committers (site PR merge). **Skill:** `release-announce-draft` -*(proposed)*, Agentic Drafting. +Agentic Drafting. Two artefacts: @@ -442,7 +431,7 @@ site PR. **Owner:** RM (or whoever holds release-archive duty per [`/release-management-config.md`](../../projects/_template/release-management-config.md)). **Skill:** `release-archive-sweep` -*(proposed)*, Agentic Triage. +Agentic Triage. Per [release-distribution § archiving](https://infra.apache.org/release-distribution.html), only the current release line is kept on `dist/release/`; @@ -465,7 +454,7 @@ under their own credentials. **Owner:** the framework (per-project audit-log store configured in [`/release-management-config.md`](../../projects/_template/release-management-config.md)). **Skill:** `release-audit-report` -*(proposed)*, Agentic Triage (read-only dashboard). +Agentic Triage (read-only dashboard). Read-only. The skill assembles a per-release record from the planning issue, the `[VOTE]` and `[RESULT]` archive URLs, the @@ -484,7 +473,7 @@ does not modify the artefacts it summarises. **Owner:** RM. **Skill:** `release-prepare` -*(proposed)*, Agentic Drafting (same skill as Steps 1-2, third +Agentic Drafting (same skill as Steps 1-2, third invocation). The skill drafts the PR that bumps the development branch to the diff --git a/docs/release-management/spec.md b/docs/release-management/spec.md index 62fad5da6..b2098f76c 100644 --- a/docs/release-management/spec.md +++ b/docs/release-management/spec.md @@ -37,10 +37,10 @@ ## Status -Proposed. No `release-*` skill code yet. This document defines the -runtime contract the future skills must satisfy. The lifecycle they -execute against is in [`process.md`](process.md); the family overview -is in [`README.md`](README.md). The pattern matches +**Experimental.** All ten `release-*` skills are shipped. This document +defines the runtime contract those skills satisfy. The lifecycle they +execute against is in [`process.md`](process.md); the family overview is +in [`README.md`](README.md). The pattern matches [Mentoring](../mentoring/spec.md), spec lands first so the contract, state-change boundaries, and adopter knobs are reviewable independently from skill code. diff --git a/docs/security/threat-model.md b/docs/security/threat-model.md index c59d80453..a940fe223 100644 --- a/docs/security/threat-model.md +++ b/docs/security/threat-model.md @@ -82,7 +82,7 @@ The intended readers are: In scope for this document: -- the eight skills in the [security workflow skill family](README.md#skills); +- the twelve skills in the [security workflow skill family](README.md#skills); - the privacy-LLM tooling (redactor + checker) those skills invoke on inbound content; - the agent host's sandbox configuration in [`.claude/settings.json`](../../.claude/settings.json) @@ -399,7 +399,7 @@ interested in it, and the boundary that protects it. ## STRIDE matrix per skill family -The eight security skills group into five families by where they +The twelve security skills group into five families by where they sit in the lifecycle. STRIDE rows below are per-family; per-skill deviations are noted inline. @@ -409,9 +409,12 @@ to the [cross-reference table](#mitigation-cross-reference). ### Skill family A — Inbound import -Skills: [`security-issue-import`](../../skills/security-issue-import/SKILL.md), +Skills: +[`security-issue-import`](../../skills/security-issue-import/SKILL.md), [`security-issue-import-from-pr`](../../skills/security-issue-import-from-pr/SKILL.md), -[`security-issue-import-from-md`](../../skills/security-issue-import-from-md/SKILL.md). +[`security-issue-import-from-md`](../../skills/security-issue-import-from-md/SKILL.md), +[`security-issue-import-from-scan`](../../skills/security-issue-import-from-scan/SKILL.md), +[`security-issue-import-via-forwarder`](../../skills/security-issue-import-via-forwarder/SKILL.md). | ID | STRIDE | Adversary | Boundary | Threat | Mitigation | |---|---|---|---|---|---| @@ -427,7 +430,8 @@ Skills: [`security-issue-import`](../../skills/security-issue-import/SKILL.md), Skills: [`security-issue-sync`](../../skills/security-issue-sync/SKILL.md), [`security-issue-deduplicate`](../../skills/security-issue-deduplicate/SKILL.md), -[`security-issue-invalidate`](../../skills/security-issue-invalidate/SKILL.md). +[`security-issue-invalidate`](../../skills/security-issue-invalidate/SKILL.md), +[`security-issue-triage`](../../skills/security-issue-triage/SKILL.md). | ID | STRIDE | Adversary | Boundary | Threat | Mitigation | |---|---|---|---|---|---| diff --git a/docs/setup/privacy-llm.md b/docs/setup/privacy-llm.md index 0991d957e..3f03cc749 100644 --- a/docs/setup/privacy-llm.md +++ b/docs/setup/privacy-llm.md @@ -338,7 +338,7 @@ Once `/privacy-llm.md` is in place: 2. (PR-3) Run the privacy-llm-specific check: ```bash - uv run --project /tools/privacy-llm/redactor \ + uv run --project /tools/privacy-llm/checker \ privacy-llm-check --reads-private-list ```