You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@magpie.apache.org by rb...@apache.org on 2026/07/15 13:37:54 UTC

(magpie) 01/01: Fix high-priority factual errors across docs

This is an automated email from the ASF dual-hosted git repository.

rbowen pushed a commit to branch rbowen-docs-refresh-20260715-02
in repository https://gitbox.apache.org/repos/asf/magpie.git

commit 3b8ab2c94e84310da3c1a2e0175ab98f7b67d641
Author: Rich Bowen <rb...@rcbowen.com>
AuthorDate: Wed Jul 15 09:37:30 2026 -0400

    Fix high-priority factual errors across docs
    
    - security/threat-model.md: "eight skills" → "twelve skills"; add
      security-issue-import-from-scan, security-issue-import-via-forwarder,
      security-issue-triage to STRIDE skill family listings
    - release-management/process.md: remove "proposed / no code yet"
      banner and 13 *(proposed)* markers — all 10 skills are shipped
    - release-management/spec.md: status "Proposed" → "Experimental"
    - adapters/add-a-harness.md: replace fabricated agent_guard/adapters/
      directory tree with the actual src/agent_guard/ layout
    - education/pattern-catalogue.md Pattern 5: fix privacy-routing CLI
      (python -m → uv run; --input/--output/--map → piped stdin)
    - setup/privacy-llm.md: gate-check path tools/privacy-llm/redactor →
      tools/privacy-llm/checker
---
 docs/adapters/add-a-harness.md      | 25 +++++++++++++------------
 docs/education/pattern-catalogue.md | 27 +++++++++++++++++----------
 docs/release-management/process.md  | 37 +++++++++++++------------------------
 docs/release-management/spec.md     |  8 ++++----
 docs/security/threat-model.md       | 14 +++++++++-----
 docs/setup/privacy-llm.md           |  2 +-
 6 files changed, 57 insertions(+), 56 deletions(-)

diff --git a/docs/adapters/add-a-harness.md b/docs/adapters/add-a-harness.md
index 507e0472..87af5ac0 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
-    <your-runtime>.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 eeadb064..564dce84 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 <content_file> --output <redacted_file> --map <map_file>`.
-2. Pass `<redacted_file>` to the model.
+1. Pipe content through the redactor:
+   ```bash
+   echo "<content>" | uv run --project <framework>/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 <model_output> --map <map_file>`.
-
-The mapping file (`<map_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 "<model_output>" | uv run --project <framework>/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 50f0e8f3..d1b041f1 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/<project>/<version>-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@<project>` 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
 [`<project-config>/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
 [`<project-config>/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 62fad5da..b2098f76 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 c59d8045..a940fe22 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 0991d957..3f03cc74 100644
--- a/docs/setup/privacy-llm.md
+++ b/docs/setup/privacy-llm.md
@@ -338,7 +338,7 @@ Once `<project-config>/privacy-llm.md` is in place:
 2. (PR-3) Run the privacy-llm-specific check:
 
    ```bash
-   uv run --project <framework>/tools/privacy-llm/redactor \
+   uv run --project <framework>/tools/privacy-llm/checker \
      privacy-llm-check --reads-private-list
    ```