From 879c5f1315d2a043bd45c4445ed750241594e9fd Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sat, 5 Sep 2026 12:56:18 -0700 Subject: [PATCH] docs(transcript): scope previews and publication explicitly --- CHANGELOG.md | 2 + skills/agent-transcript/SKILL.md | 118 +++++++++++-------------------- 2 files changed, 44 insertions(+), 76 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ade47c4f..fd415e09 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,8 @@ summary: Timeline of guardrail helper changes mirrored from Sweetistics and rela ## Unreleased +- Simplified requested agent transcripts and require scope trimming before previews or publication; helpers that rerender sessions cannot reuse approval of edited Markdown. + - Set `codex-first` workers and Codex-backed reviews to GPT-6 Astra with high reasoning and Fast service, including fresh, resumed, and watchdog launches. - Removed the retired private launch-skill dependency from shared instructions and Claude routing; Codex workers now inherit saved model, reasoning, and service-tier defaults. diff --git a/skills/agent-transcript/SKILL.md b/skills/agent-transcript/SKILL.md index 8b83bb2a..edfec307 100644 --- a/skills/agent-transcript/SKILL.md +++ b/skills/agent-transcript/SKILL.md @@ -1,91 +1,57 @@ --- name: agent-transcript -description: "Requested GitHub PR/issue agent transcripts: redact, preview, and insert safely." +description: "Requested GitHub PR/issue agent transcripts: redact, trim, preview, and insert safely." --- # Agent Transcript -Best-effort local-only provenance for OpenClaw PR/issue bodies. Use only when the user explicitly requests a transcript or preview. +Use only when the user explicitly requests a transcript or preview. Omit by +default; never offer one or ask whether to include one during ordinary PR work. +A preview request alone does not authorize publication. -## Contract +## Prepare Locally -- Never use network. Session discovery reads local agent logs only. -- Never upload raw logs. Render sanitized Markdown first. -- Omit transcripts by default; do not offer or ask about them. -- If explicitly requested, offer a local HTML preview before insertion and wait for confirmation before adding the section. -- Fail closed on unresolved secrets, private keys, browser/session/cookie details, or auth URLs. -- Drop system/developer prompts, raw tool outputs, reasoning, env, cookies, tokens, and broad local paths. -- Keep user prompts, assistant visible decisions, terse tool summaries, and test/proof outcomes. -- Automatically trim the rendered transcript before showing it, previewing it, or inserting it into a public body. Never paste the raw full-session render into a PR/issue body just because `render` or `append-body` produced it. -- Remove session turns unrelated to the PR/issue work. Use the PR/issue title, branch name, changed files, and stated goal as scope; omit earlier/later unrelated tasks even when they are in the same session log. -- Best effort only: PR/issue creation must continue if no safe transcript is found. -- Add the `## Agent Transcript` section only when inserting a real transcript. Never add a placeholder transcript heading or text such as "A sanitized local transcript preview was generated but not included." -- Use a collapsed `
` section and update existing markers instead of duplicating sections. - -## Helper - -```bash -skills/agent-transcript/scripts/agent-transcript --help -``` - -Find a likely local session: +The helper reads local Codex, Claude, Pi, and OpenClaw logs; no network is used +for discovery/rendering. Never upload raw logs. ```bash skills/agent-transcript/scripts/agent-transcript find \ - --query "$PR_TITLE $BRANCH_OR_PR_URL" \ - --cwd "$PWD" \ - --since-days 14 -``` - -`find` scans the newest 400 matching local JSONL logs by default across Codex, Claude, Pi, and OpenClaw agent sessions. Use `--max-files N` for a wider local search. - -In a downstream repo that syncs shared skills under `.agents/skills`, replace -`skills/agent-transcript` with `.agents/skills/agent-transcript`. - -Render a PR/issue body section: - -```bash + --query "$PR_TITLE $BRANCH_OR_PR_URL" --cwd "$PWD" --since-days 14 skills/agent-transcript/scripts/agent-transcript render \ - --session "$SESSION_JSONL" \ - --out /tmp/agent-transcript.md + --session "$SESSION_JSONL" --out /tmp/agent-transcript.md ``` -Preview one candidate session locally: - -```bash -skills/agent-transcript/scripts/agent-transcript preview \ - --session "$SESSION_JSONL" \ - --out /tmp/agent-transcript-preview.html -open /tmp/agent-transcript-preview.html -``` - -Append/update a body file before `gh pr create --body-file` or connector PR creation: - -```bash -skills/agent-transcript/scripts/agent-transcript append-body \ - --body /tmp/pr-body.md \ - --session "$SESSION_JSONL" \ - --out /tmp/pr-body.with-transcript.md -``` - -## PR/Issue Workflow - -Run this workflow only after the user explicitly requests a transcript or preview. - -1. Draft the normal PR/issue body first. -2. Run `find` with title, branch, PR URL/number if known, and cwd. -3. If preview was requested, run `preview`, open the HTML, and wait for confirmation. -4. Render or append to a temp body, then automatically trim the `## Agent Transcript` section before showing it to the user or inserting it publicly. Keep only turns that explain this PR/issue's goal, implementation choices, files, tests, proof, blockers, and final outcome. -5. Inspect the trimmed transcript text. If it still includes unrelated earlier/later work, trim again before proceeding. -6. Use the enriched trimmed body file only after the user approves it. -7. If no safe session is found or the user declines, continue without a transcript or placeholder section. - -## Review Artifacts - -For manual audits across many PR/session candidates, create a local HTML preview from a local JSON file. This is for maintainers only and is not part of the PR/issue workflow: +In downstream repositories that sync under `.agents/skills`, replace +`skills/agent-transcript` with `.agents/skills/agent-transcript`. -```bash -skills/agent-transcript/scripts/agent-transcript html \ - --prs /tmp/recent-prs.json \ - --out /tmp/agent-transcript-preview.html -``` +`find` scans the newest 400 matching logs by default; `--max-files N` widens +local discovery. Treat matches as candidates, not proof of scope. + +Automatically trim the rendered Markdown **before showing, previewing, or +inserting it**. Keep only task-relevant user prompts, visible decisions, terse +tool summaries, and proof outcomes. Use the PR/issue goal, branch, and changed +files to remove unrelated earlier/later turns. Drop system/developer prompts, +reasoning, raw tool output, environment data, local paths, credentials, +browser/session/cookie details, and auth URLs. Inspect the trimmed result; +helper redaction is not sufficient disclosure review. Unresolved sensitive +content means omit the transcript. + +## Preview And Insert + +Show the trimmed Markdown for a requested preview. If HTML is requested, build +the local preview from that trimmed content. The helper's `preview`, `html`, and +`append-body` modes render the session again; they do not consume an edited +Markdown file and can reintroduce removed turns. Do not use their untrimmed +output as the approved artifact. + +Insert only the inspected, scoped text when the user's authorization specifically +covers publishing that transcript to the named PR/issue. Generating or previewing +a transcript does not authorize publication, even when ordinary PR creation or +editing is already approved. If that scope is missing, show the trimmed result +and obtain publication authorization before insertion. Existing explicit +authorization covering transcript publication needs no repeat confirmation. +Keep the collapsed `
` section and replace existing transcript markers +instead of duplicating them. No safe match means continue the PR work without +transcript or placeholder; explain the omission when it prevents the explicitly +requested transcript. Do not promote transcript inclusion as a review priority +requirement.