trace-to-skill 0.1.26 → 0.1.35

package/README.md

@@ -3,24 +3,26 @@
 [![CI](https://github.com/grnbtqdbyx-create/trace-to-skill/actions/workflows/ci.yml/badge.svg)](https://github.com/grnbtqdbyx-create/trace-to-skill/actions/workflows/ci.yml)
 [![Codex Readiness](https://github.com/grnbtqdbyx-create/trace-to-skill/actions/workflows/codex-readiness.yml/badge.svg)](https://github.com/grnbtqdbyx-create/trace-to-skill/actions/workflows/codex-readiness.yml)
 [![Release](https://img.shields.io/github/v/release/grnbtqdbyx-create/trace-to-skill)](https://github.com/grnbtqdbyx-create/trace-to-skill/releases)
+[![npm](https://img.shields.io/npm/v/trace-to-skill)](https://www.npmjs.com/package/trace-to-skill)
+[![npm downloads](https://img.shields.io/npm/dm/trace-to-skill)](https://www.npmjs.com/package/trace-to-skill)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 [![Node](https://img.shields.io/badge/node-%3E%3D20-339933.svg)](package.json)
 
 Turn failed AI coding-agent runs into reusable `AGENTS.md` rules, `SKILL.md` files, and eval evidence.
 
 ```bash
-npx github:grnbtqdbyx-create/trace-to-skill doctor .
-npx github:grnbtqdbyx-create/trace-to-skill lint-agents .
-npx github:grnbtqdbyx-create/trace-to-skill analyze ./runs
-npx github:grnbtqdbyx-create/trace-to-skill init --comment --sarif
-npx github:grnbtqdbyx-create/trace-to-skill suggest ./runs --target agents-md
-npx github:grnbtqdbyx-create/trace-to-skill eval ./runs --threshold 80
-npx github:grnbtqdbyx-create/trace-to-skill benchmark
-npx github:grnbtqdbyx-create/trace-to-skill scorecard .
-npx github:grnbtqdbyx-create/trace-to-skill scorecard-comment . --dry-run
-npx github:grnbtqdbyx-create/trace-to-skill guard-github-event "$GITHUB_EVENT_PATH"
-npx github:grnbtqdbyx-create/trace-to-skill comment ./runs --dry-run
-npx github:grnbtqdbyx-create/trace-to-skill compare --before ./runs/before --after ./runs/after
+npx trace-to-skill doctor .
+npx trace-to-skill lint-agents .
+npx trace-to-skill analyze ./runs
+npx trace-to-skill init --comment --sarif
+npx trace-to-skill suggest ./runs --target agents-md
+npx trace-to-skill eval ./runs --threshold 80
+npx trace-to-skill benchmark
+npx trace-to-skill scorecard .
+npx trace-to-skill scorecard-comment . --dry-run
+npx trace-to-skill guard-github-event "$GITHUB_EVENT_PATH"
+npx trace-to-skill comment ./runs --dry-run
+npx trace-to-skill compare --before ./runs/before --after ./runs/after
 ```
 
 AI coding agents are getting good enough to change real repositories, but they still repeat the same workflow mistakes: claiming success without tests, ignoring repo instructions, over-editing, inventing files, leaking secrets into traces, or enabling risky MCP tools.
@@ -33,6 +35,17 @@ failed agent run -> failure class -> reusable rule/skill -> eval gate -> keep or
 
 It is built for maintainers using Codex, Claude Code, Cursor, Copilot coding agent, Gemini CLI, OpenCode, or MCP-enabled workflows.
 
+## Fast Use Cases
+
+Use it when you need to:
+
+- **Gate Codex-ready PRs:** run `trace-to-skill scorecard .` in CI and post a reviewer-friendly readiness comment.
+- **Harden agent instructions:** run `trace-to-skill lint-agents .` to catch missing `AGENTS.md`, conflicting tool instructions, missing includes, nested instruction drift, encoding issues, and risky MCP config.
+- **Protect agent context:** run `trace-to-skill guard-github-event "$GITHUB_EVENT_PATH"` before feeding issue, PR, comment, discussion, check-run, or commit text into an agent.
+- **Share failed traces safely:** run `trace-to-skill redact ./runs --output redacted-runs` before publishing anonymized failure fixtures.
+
+For copy-paste workflows, see [docs/USE_CASES.md](https://github.com/grnbtqdbyx-create/trace-to-skill/blob/main/docs/USE_CASES.md). For crawler-friendly metadata, see [docs/DISCOVERY.md](https://github.com/grnbtqdbyx-create/trace-to-skill/blob/main/docs/DISCOVERY.md) and [llms.txt](https://github.com/grnbtqdbyx-create/trace-to-skill/blob/main/llms.txt).
+
 ## Why This Exists
 
 Open-source maintainers do not need more AI-generated noise. They need agents that learn from concrete failures and produce reviewable evidence.
@@ -112,22 +125,22 @@ Trace analysis detects run-level failures:
 
 ## Installation
 
-The GitHub release is available now:
+Run from npm:
 
 ```bash
-npx github:grnbtqdbyx-create/trace-to-skill analyze ./runs
+npx trace-to-skill analyze ./runs
 ```
 
-After npm publication:
+Or install in a repository:
 
 ```bash
 npm install -D trace-to-skill
 ```
 
-or:
+GitHub source installs also work:
 
 ```bash
-npx trace-to-skill analyze ./runs
+npx github:grnbtqdbyx-create/trace-to-skill analyze ./runs
 ```
 
 Requires Node.js 20+.
@@ -150,7 +163,17 @@ trace-to-skill lint-agents .
 trace-to-skill lint-agents . --format json
 ```
 
-This focused linter checks whether `AGENTS.md` exists as the canonical instruction source, whether validation commands are discoverable, whether `AGENTS.md` / `CLAUDE.md` / Cursor / Copilot guidance conflicts, and whether MCP configs expose risky capabilities or secrets.
+This focused linter checks whether `AGENTS.md` exists as the canonical instruction source, whether validation commands are discoverable, whether `AGENTS.md` / `CLAUDE.md` / Cursor / Copilot guidance conflicts, whether instruction files reference missing paths, missing `@file.md` includes, nested `AGENTS.md` files that the root instructions do not mention, invalid UTF-8, or grow large enough to risk ignored guidance, and whether JSON or `.codex/config.toml` MCP/Codex configs expose risky capabilities, secrets, unresolved commands, missing `cwd` values, placeholder env vars, wrong `mcpServers` casing, unresolved plugin placeholders, deprecated `codex_hooks`, missing `default_permissions` profiles, or synced `projects.* trusted_level` state.
+
+Redact traces before sharing them:
+
+```bash
+trace-to-skill redact ./runs --output redacted-runs
+trace-to-skill redact ./runs/failed-run.md > failed-run.redacted.md
+trace-to-skill redact ./runs --output redacted-runs --format json
+```
+
+This removes common API keys, GitHub/npm/Slack tokens, bearer tokens, email addresses, local home paths, and hidden Unicode controls while preserving enough context for maintainer review.
 
 Scaffold a repo:
 
@@ -246,9 +269,9 @@ trace-to-skill compare --before ./runs/before --after ./runs/after
 
 JSONL traces are normalized by extracting common fields such as `message`, `content`, `text`, `output`, and `error`. Codex-style JSONL traces with `response_item`, `function_call`, `function_call_output`, and `event_msg` payloads are normalized into readable evidence lines.
 
-MCP configs with `mcpServers` are parsed for capability hints such as filesystem, shell, browser, network, database, container, and secret-bearing environment variables.
+MCP configs with `mcpServers`, `.mcp.json`, or project-local `.codex/config.toml` are parsed for capability hints such as filesystem, shell, browser, network, database, container, and secret-bearing environment variables. `lint-agents` also checks static startup inputs such as `command`, `cwd`, env placeholders, unresolved `$VARS`, `${CLAUDE_PLUGIN_ROOT}`-style plugin placeholders, local stdio commands without explicit `cwd`, and the common JSON `mcp_servers` / `mcpServers` casing mismatch. Codex config hygiene checks catch deprecated `[features].codex_hooks`, missing `default_permissions` profile definitions, and machine-local `projects.* trusted_level` metadata in synced config files.
 
-Instruction files such as `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursor/rules`, and `.github/copilot-instructions.md` are checked for obvious contradictions in validation commands, test requirements, and destructive-command approval rules.
+Instruction files such as `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursor/rules`, and `.github/copilot-instructions.md` are checked for obvious contradictions in validation commands, test requirements, destructive-command approval rules, invalid UTF-8, missing include targets, and nested `AGENTS.md` files that may not be loaded automatically.
 
 ## JSON Schemas
 
@@ -257,6 +280,7 @@ Stable machine-readable contracts are published with the npm package and release
 - [`schemas/analysis-result.schema.json`](schemas/analysis-result.schema.json) describes `trace-to-skill analyze --format json`.
 - [`schemas/agents-lint-result.schema.json`](schemas/agents-lint-result.schema.json) describes `trace-to-skill lint-agents --format json`.
 - [`schemas/doctor-result.schema.json`](schemas/doctor-result.schema.json) describes `trace-to-skill doctor --format json`.
+- [`schemas/redact-result.schema.json`](schemas/redact-result.schema.json) describes `trace-to-skill redact --format json`.
 - [`schemas/scorecard-result.schema.json`](schemas/scorecard-result.schema.json) describes `trace-to-skill scorecard --format json`.
 
 These schemas let downstream Codex workflows, dashboards, and CI bots consume reports without scraping Markdown.
@@ -285,7 +309,7 @@ jobs:
       issues: write
     steps:
       - uses: actions/checkout@v5
-      - uses: grnbtqdbyx-create/trace-to-skill@v0.1.26
+      - uses: grnbtqdbyx-create/trace-to-skill@v0.1.35
         with:
           mode: all
           doctor-threshold: "85"
@@ -316,15 +340,15 @@ jobs:
       - uses: actions/setup-node@v5
         with:
           node-version: 20
-      - run: npx github:grnbtqdbyx-create/trace-to-skill analyze ./runs --output agent-learning-report.md
-      - run: npx github:grnbtqdbyx-create/trace-to-skill comment ./runs --token "${{ github.token }}"
-      - run: npx github:grnbtqdbyx-create/trace-to-skill eval ./runs --threshold 80
+      - run: npx trace-to-skill analyze ./runs --output agent-learning-report.md
+      - run: npx trace-to-skill comment ./runs --token "${{ github.token }}"
+      - run: npx trace-to-skill eval ./runs --threshold 80
 ```
 
 Code scanning / SARIF upload:
 
 ```yaml
-- run: npx github:grnbtqdbyx-create/trace-to-skill analyze ./runs --format sarif --output trace-to-skill.sarif
+- run: npx trace-to-skill analyze ./runs --format sarif --output trace-to-skill.sarif
 - uses: github/codeql-action/upload-sarif@v4
   with:
     sarif_file: trace-to-skill.sarif
@@ -334,7 +358,7 @@ Composite action usage:
 
 ```yaml
 - id: trace-to-skill
-  uses: grnbtqdbyx-create/trace-to-skill@v0.1.26
+  uses: grnbtqdbyx-create/trace-to-skill@v0.1.35
   with:
     mode: all
     doctor-threshold: "85"
@@ -376,7 +400,7 @@ Action outputs:
 
 By default, generated reports are also appended to the GitHub Actions Job Summary. Set `job-summary: "false"` to disable that UI output.
 
-Tagged Action releases build and run the CLI from `$GITHUB_ACTION_PATH`, so a workflow pinned to `@v0.1.26` executes that release's checked-out source instead of pulling the default branch at runtime.
+Tagged Action releases build and run the CLI from `$GITHUB_ACTION_PATH`, so a workflow pinned to a release tag such as `@v0.1.35` executes that release's checked-out source instead of pulling the default branch at runtime.
 
 ## Codex Skill
 
@@ -409,7 +433,7 @@ The goal is not to let agents autonomously rewrite project policy. The goal is t
 - Codex session JSONL adapters
 - Claude Code transcript adapters
 - `AGENTS.md` contradiction detector
-- MCP config parser with explicit capability scoring
+- MCP/Codex config parser with explicit capability scoring, JSON/TOML startup diagnostics, and config drift checks
 - GitHub PR comment mode
 - before/after eval runner
 - SARIF output for GitHub code scanning