agent-workflow-inspector 1.0.0 → 2.0.0

package/docs/releasing.md

@@ -1,112 +1,23 @@
-# V1.0.0 release procedure
+# Release procedure
 
-This is an approval-gated plan, not an automated publisher. All public actions below are pending explicit maintainer approval. No publish workflow or write credential has been added. Run commands from the repository root in PowerShell, check each exit code, and stop on any failure or unexpected remote state. GitHub CLI (`gh`) and a supported npm CLI must be installed/authenticated before publication; neither is currently available/authenticated in the Windows release shell. Never print credentials or copy them into the repository.
+## v1.0.0 status (verified October 20, 2026)
 
-## Candidate and repository state
+- [GitHub release](https://github.com/jigar48/awi/releases/tag/v1.0.0): published October 19, 2026, neither draft nor prerelease. Assets include the package tarball and `release-candidate.json` (an artifact filename, not the current release status).
+- Annotated tag `v1.0.0` resolves to commit `1baca3ebdcc4da792f11487483abf3f60c22d1fb`. The default branch is `main`.
+- [npm registry version](https://registry.npmjs.org/agent-workflow-inspector/1.0.0): HTTP 200, name `agent-workflow-inspector`, version `1.0.0`, published October 19, 2026.
+- Registry tarball integrity: `sha512-lLYHfyeswXS2mF13a0a0YLKkdC6PSSYBnZM74XuYsqfHIiNTkBFQDk6gmhb3fcaAH3Ebf+W+lDo/LxUKv9CAXw==`.
 
-- Package: `agent-workflow-inspector@1.0.0`, MIT. Source bin `dist/cli/index.js`, ESM export and declarations `dist/index.js` / `dist/index.d.ts`; Node 22.18+ (22.x), 24.11+ (24.x), 26.x.
-- Local `main` preserves audited history through d2514af. The feature branch is retained. No force push, history rewrite, branch deletion or tag creation is required during preparation.
-- At inspection, public origin was `https://github.com/jigar48/awi.git`, default branch `codex/awi-v1`, sole remote commit d2514af, with no tags/releases. Description/homepage were empty and topics were empty.
-- Public branch metadata reported `protected:false`; repository rulesets returned an empty list. The detailed protection endpoint returned 403 to the connected integration, so a maintainer must confirm settings before changing defaults. Do not bypass any rules; use the required review path if protection changes.
-- The npm registry returned 404 on October 19, 2026. The name is not reserved and no ownership is established by that result. Linux npm 11.17.0 `whoami` returned ENEEDAUTH; Windows npm is absent from PATH. Authenticate the intended maintainer account, with 2FA, and recheck availability immediately before publishing. Never overwrite an existing version; if 1.0.0 appears, stop and compare ownership/source before choosing a new version.
-- Historical [CI run](https://github.com/jigar48/awi/actions/runs/39208844432) passed all nine jobs for d2514af only. It does not validate this later candidate.
+These are read-only metadata checks, not a fresh registry installation or byte comparison against GitHub assets. The registry README still contains historical candidate wording; local documentation changes do not modify existing npm metadata or release assets.
 
-## Ordered public actions — approval required
+## Future releases
 
-### 1. Push only the final main candidate
+Publication is a separate maintainer action requiring explicit authorization. Never republish 1.0.0, move its tag, or replace its assets to include these later changes.
 
-```powershell
-git status --porcelain=v1
-git switch main
-$releaseSha = (git rev-parse HEAD).Trim()
-git merge-base --is-ancestor d2514af main
-git ls-remote --symref origin
-git push --set-upstream origin main
-git ls-remote origin refs/heads/main
-```
+1. Choose an unused version and review source, package metadata, changelog and release notes. Confirm current registry ownership and existing tags/releases without exposing credentials.
+2. Run `pnpm install --frozen-lockfile`, `pnpm check`, `pnpm verify:quickstart`, `pnpm format:check`, `pnpm schemas`, `git diff --exit-code -- docs/schemas`, `pnpm audit --prod`, `pnpm audit`, and `pnpm smoke:package`.
+3. Require a successful nine-job hosted matrix for the exact approved source commit. Earlier runs do not validate a later commit.
+4. Pack and inspect the artifact. Record the source SHA and tarball SHA-512 outside the package; validate the isolated installed package, executable, examples and ESM/TypeScript imports.
+5. Only after approval, use the maintainer's authenticated release process with interactive 2FA or a separately reviewed trusted publisher. Never store credentials in this repository. No publishing workflow is provided here.
+6. Verify the published tag/source SHA, GitHub assets and registry integrity against the approved artifact. Test a clean registry consumer, then record the date, URLs, CI run and verification limits.
 
-Require a clean tree, the approved SHA and preserved audited ancestry. If remote main appears or changes, fetch and inspect ancestry before pushing; never force. This push triggers `.github/workflows/ci.yml` on main without changing the default branch.
-
-### 2. Verify fresh main CI
-
-```powershell
-gh run list --repo jigar48/awi --workflow ci.yml --branch main --commit $releaseSha --event push --json databaseId,headSha,status,conclusion,url
-```
-
-Select the matching run ID, then run `gh run watch RUN_ID --repo jigar48/awi --exit-status` and `gh run view RUN_ID --repo jigar48/awi --json headSha,conclusion,jobs`. Require exactly nine successful verify jobs: Windows, macOS and Ubuntu × Node 22.18.0, 24.11.0 and 26. Every install/test/type/lint/build/format/schema/audit/pack/consumer step must pass. Stop publication on a failure or SHA mismatch. Any correction requires a new commit, push, matrix and package validation.
-
-### 3. Set default branch and prepared metadata
-
-Only after successful main CI, inspect branch settings with an admin identity. Apply the prepared description/homepage/topics and default branch:
-
-```powershell
-gh api --method PATCH repos/jigar48/awi --input .github/repository-metadata.json
-gh api --method PUT repos/jigar48/awi/topics --input .github/repository-topics.json
-gh repo edit jigar48/awi --default-branch main
-```
-
-Topics satisfy GitHub's current rules: eight lowercase names using letters/hyphens, each at most 50 characters; maximum allowed is 20. See [GitHub topic requirements](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics). Funding appears from `.github/FUNDING.yml`; no external account settings are changed by the local file.
-
-### 4. Freeze artifact and create annotated tag
-
-Recheck HEAD equals the successful CI SHA and clean status. Preserve the exact locally validated tarball and its external SHA-512 integrity manifest. Do not rebuild or substitute it after approval; if regenerated, repeat the clean consumer check and recompute the manifest. Inspect `git ls-remote --tags origin` and ensure no v1.0.0 exists.
-
-```powershell
-git tag -a v1.0.0 $releaseSha -m 'Agent Workflow Inspector v1.0.0'
-git push origin refs/tags/v1.0.0
-git rev-parse 'v1.0.0^{}'
-git ls-remote origin 'refs/tags/v1.0.0*'
-```
-
-Require the peeled remote tag to equal `$releaseSha`. A tag push also triggers CI; do not confuse it with the already required main run. Do not move an existing tag.
-
-### 5. Publish GitHub release
-
-The prepared notes use absolute version-tagged documentation URLs. Remove the candidate status line only in the temporary publication body after approval; preserve the source notes as a preparation record.
-
-```powershell
-$notes = Get-Content docs/releases/v1.0.0.md -Raw
-$notes = $notes.Replace('Release notes prepared for approval. This version has not been published.', 'Initial public release.')
-[IO.File]::WriteAllText((Join-Path $PWD '.awi-audit/release-body.md'), $notes)
-gh release create v1.0.0 agent-workflow-inspector-1.0.0.tgz .awi-audit/release-candidate.json --repo jigar48/awi --verify-tag --title 'Agent Workflow Inspector v1.0.0 — Deterministic AI Agent Trace Diagnostics' --notes-file .awi-audit/release-body.md
-```
-
-The release body labels npm installation as conditional until registry publication succeeds, so an npm authentication failure does not falsely advertise availability. No GitHub release has been created during preparation.
-
-### 6. Publish npm securely
-
-For the first version, prefer interactive npm web login/2FA on the maintainer's trusted machine. The current npm [trust CLI prerequisites](https://docs.npmjs.com/cli/v11/commands/npm-trust/) require the package to exist before a trusted publisher can be configured. Therefore this unpublished name cannot yet use that setup path. Do not create a bootstrap/dummy version, or a long-lived npm automation token.
-
-Install a current supported npm CLI and use the intended maintainer account. Commands below are pending approval and human authentication:
-
-```powershell
-npm login --auth-type=web --registry=https://registry.npmjs.org
-npm whoami --registry=https://registry.npmjs.org
-npm view agent-workflow-inspector versions maintainers --json --registry=https://registry.npmjs.org
-npm publish ./agent-workflow-inspector-1.0.0.tgz --access public --registry=https://registry.npmjs.org --ignore-scripts
-```
-
-Expected pre-publication registry response is E404. Any other response needs review; if version 1.0.0 exists, stop. Human authentication is intentionally outside agent logs. Publish the already validated tarball with lifecycle scripts disabled. Local interactive publication does not create GitHub OIDC provenance; do not claim it does.
-
-GitHub-hosted OIDC trusted publishing is suitable for subsequent versions: public repository/package, pinned actions, protected manual publish workflow, explicit immutable source SHA/tag, passing CI gate, protected environment, `contents: read` and job-scoped `id-token: write`, no write token or release-build cache. npm documents Node >=22.14 and npm >=11.5.1 for OIDC; the trust CLI needs npm >=11.15. A future reviewed `publish.yml` must exist before npm configuration names it. Configure `jigar48/awi`, that exact workflow filename and environment in package settings; stage-only permission with maintainer 2FA approval is preferred. Current npm documentation also requires a new trusted configuration's first successful publish within two days. See [trusted publishing](https://docs.npmjs.com/trusted-publishers/). Do not enable any publisher or add a live workflow during this preparation.
-
-### 7. Verify registry and clean registry consumer
-
-```powershell
-npm view agent-workflow-inspector@1.0.0 name version license engines bin exports types repository homepage bugs dist --json --registry=https://registry.npmjs.org
-npm owner ls agent-workflow-inspector --registry=https://registry.npmjs.org
-```
-
-Require registry `dist.integrity` to equal `.awi-audit/release-candidate.json` tarballIntegrity. Download the registry tarball, verify its SHA-512 and compare bytes with the approved artifact. Never accept matching version strings alone. The tarball manifest records the source SHA; the annotated tag and successful CI must identify that same SHA. Reject any payload difference.
-
-Create a new temporary directory outside the checkout, `npm init -y`, then `npm install --ignore-scripts --save-exact agent-workflow-inspector@1.0.0 --registry=https://registry.npmjs.org`. Execute its installed `node_modules/.bin/awi` (`awi.cmd` on Windows) with --help, --version and all four shipped examples using resolved package paths; expected results match `scripts/package-smoke.mjs`. Check JSON output, exit codes, ESM public imports and strict TypeScript imports, using only declared consumer tooling. Clean up the temporary directory after inspection. This registry-based check cannot run before publication; the local tarball equivalent has already run.
-
-### 8. Verify release links and record outcome
-
-Use `gh release view v1.0.0 --repo jigar48/awi --json url,tagName,targetCommitish,assets,body` and repository metadata to confirm the default main branch, tag, notes and downloadable artifact. Open version-tagged documentation URLs and npm package page. Match the release tarball to the same SHA-512 manifest and record the successful main run URL and release commit. A registry/release mismatch is a release incident, not grounds to force-move a tag or overwrite a version.
-
-After successful publication, a separate documentation-only follow-up may replace the README's candidate notice, add the actual publication date to the changelog, and record registry/release URLs and integrity. Such a follow-up is not part of the v1.0.0 source tag and must not be represented as its published contents.
-
-## Approval gate
-
-Local preparation is complete only after full validation and tarball consumer smoke pass. Publication remains blocked on approval, fresh main CI and authenticated npm ownership/name checks. Approval must explicitly cover main push, remote metadata/default-branch changes, annotated tag push, GitHub release and npm publication. The previous feature-branch push authorization does not authorize these actions.
+See [verification](verification.md) for historical results and the [release notes](releases/v1.0.0.md) for v1.0.0 behavior.

package/docs/report-schema.md

@@ -1,22 +1,29 @@
-# JSON report v1
+# JSON report v2
 
-[Machine schema](schemas/report.schema.json). Fields: version 1, fingerprintVersion awi-sha256-v1, complete, summaries, findings, warnings. No clock or absolute paths. Optional content requires explicit opt-in.
+The [machine schema](schemas/report.schema.json) and the exported `Report` type use `version: 2`. The `fingerprintVersion` remains `awi-sha256-v1`. The envelope also includes `complete`, `summaries`, `findings`, and `warnings`. Optional `content` requires explicit opt-in. Reports contain no generation timestamp or absolute input path.
 
-Summary fields: traceId, operations, toolCalls, maxDepth, optional durationMs and recorded leaf usage. Unknown resources stay absent. Finding fields: ruleId, severity, confidence, title, description, explanation, remediation, traceId, operationIds, structured evidence. References contain operationId and adapter source format/index when available. traceId + operationId is authoritative across merged files; source index preserves adapter recorded order, not causal order. AWI005 is trace-wide with no individual operation list.
+Summaries include `traceId`, `operations`, `toolCalls`, `maxDepth`, and, when available, `durationMs` and recorded leaf `usage`. Findings include `ruleId`, `severity`, `confidence`, `title`, `description`, `explanation`, `remediation`, `traceId`, `operationIds`, and structured `evidence`. `evidence.references` repeats the operation aliases and includes the adapter's source format and index when available. A source index describes recorded order in its input, which can repeat across merged files. AWI005 is trace-wide and has empty operation and reference lists.
 
-Findings sort by descending severity, trace ID, rule ID, then operation ID list using lexical comparison. Warnings deduplicate and sort. CLI filesystem inputs enumerate deterministically. Operations and resource evidence use stable ID ordering after ingestion; timing rules use exact timestamps. Adapter source indices retain recorded order, so ingesting a reordered raw export changes those evidence indices deliberately. Direct-library trace fragments produce the same findings regardless of fragment order.
+`traceId` uses `trace-N`. `operationIds` and `evidence.references[].operationId` use `op-N`. Join on `traceId` within a report and on the pair `(traceId, operationId)` for operation references. Ordinals start at 1 and follow the lexical order of recorded trace IDs and the recorded operation IDs within each merged trace. They can shift when inputs are added, removed, or renamed. Findings retain descending severity and the existing lexical order of underlying trace IDs, rule IDs, and operation ID lists. Source indices still depend on the order in the original export. Warnings deduplicate and sort.
 
 ```json
 {
-  "version": 1,
+  "version": 2,
   "fingerprintVersion": "awi-sha256-v1",
   "complete": true,
   "summaries": [
-    { "traceId": "demo", "operations": 0, "toolCalls": 0, "maxDepth": 0 }
+    { "traceId": "trace-1", "operations": 0, "toolCalls": 0, "maxDepth": 0 }
   ],
   "findings": [],
   "warnings": []
 }
 ```
 
-complete:false means truncation and is never clean success. Eligibility warnings identify unavailable timing/argument evidence. Complete means all applicable analysis finished, not that absent information was reconstructed. Incompatible contracts require a version change. Evidence fields are rule-specific and additive; consumers should not parse prose.
+`complete: false` indicates truncation and produces a CLI operational failure. Eligibility warnings identify unavailable timing or argument evidence. Consumers should use structured fields for integrations and allow additive evidence fields.
+
+## Migrating from v1
+
+- Update consumers to recognize `version: 2`. The v2 validator rejects v1, and v1 validators reject v2. Trace input and configuration versions are independent of the report version.
+- Replace joins to raw input IDs with report-local joins. For private debugging, `--show-content` and `analyze(traces, config, true)` add `content[].recordedTraceId` alongside the report alias `content[].traceId`. The normalized operation at zero-based index `N - 1` in `content[].operations` corresponds to `op-N` and contains the recorded ID, subject to output sanitization. Findings and summaries keep the same aliases. See [privacy limits](security.md).
+- AWI006 `evidence.recordedCosts` groups amounts by `currency-N` in lexical order of recorded currency labels within the finding. These aliases have finding-local scope.
+- AWI007 remains disabled by default. Once enabled, it reports `failedCalls`, `distinctArgumentFingerprints` and `references`, with operation IDs in run order. V2 omits `toolName` and `errorCode` from evidence even when recorded content is enabled.

package/docs/schemas/config.schema.json

@@ -10,7 +10,12 @@
         "AWI003": { "enabled": true, "minRepetitions": 3, "maxCycleLength": 6 },
         "AWI004": { "enabled": true, "threshold": 5, "windowSeconds": 30 },
         "AWI005": { "enabled": true, "maxOperations": 100, "maxDepth": 20 },
-        "AWI006": { "enabled": true }
+        "AWI006": { "enabled": true },
+        "AWI007": {
+          "enabled": false,
+          "threshold": 4,
+          "minDistinctArguments": 3
+        }
       },
       "type": "object",
       "properties": {
@@ -117,9 +122,42 @@
           "properties": { "enabled": { "default": true, "type": "boolean" } },
           "required": ["enabled"],
           "additionalProperties": false
+        },
+        "AWI007": {
+          "default": {
+            "enabled": false,
+            "threshold": 4,
+            "minDistinctArguments": 3
+          },
+          "type": "object",
+          "properties": {
+            "enabled": { "default": false, "type": "boolean" },
+            "threshold": {
+              "default": 4,
+              "type": "integer",
+              "minimum": 4,
+              "maximum": 100
+            },
+            "minDistinctArguments": {
+              "default": 3,
+              "type": "integer",
+              "minimum": 3,
+              "maximum": 100
+            }
+          },
+          "required": ["enabled", "threshold", "minDistinctArguments"],
+          "additionalProperties": false
         }
       },
-      "required": ["AWI001", "AWI002", "AWI003", "AWI004", "AWI005", "AWI006"],
+      "required": [
+        "AWI001",
+        "AWI002",
+        "AWI003",
+        "AWI004",
+        "AWI005",
+        "AWI006",
+        "AWI007"
+      ],
       "additionalProperties": false
     },
     "fingerprint": {

package/docs/schemas/report.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {
-    "version": { "type": "number", "const": 1 },
+    "version": { "type": "number", "const": 2 },
     "fingerprintVersion": { "type": "string", "const": "awi-sha256-v1" },
     "complete": { "type": "boolean" },
     "summaries": {
@@ -10,7 +10,7 @@
       "items": {
         "type": "object",
         "properties": {
-          "traceId": { "type": "string" },
+          "traceId": { "type": "string", "pattern": "^trace-[1-9][0-9]*$" },
           "operations": {
             "type": "integer",
             "minimum": 0,
@@ -60,7 +60,15 @@
         "properties": {
           "ruleId": {
             "type": "string",
-            "enum": ["AWI001", "AWI002", "AWI003", "AWI004", "AWI005", "AWI006"]
+            "enum": [
+              "AWI001",
+              "AWI002",
+              "AWI003",
+              "AWI004",
+              "AWI005",
+              "AWI006",
+              "AWI007"
+            ]
           },
           "severity": { "type": "string", "enum": ["low", "medium", "high"] },
           "confidence": { "type": "string", "enum": ["high", "moderate"] },
@@ -68,11 +76,43 @@
           "description": { "type": "string" },
           "explanation": { "type": "string" },
           "remediation": { "type": "string" },
-          "traceId": { "type": "string" },
-          "operationIds": { "type": "array", "items": { "type": "string" } },
+          "traceId": { "type": "string", "pattern": "^trace-[1-9][0-9]*$" },
+          "operationIds": {
+            "type": "array",
+            "items": { "type": "string", "pattern": "^op-[1-9][0-9]*$" }
+          },
           "evidence": {
             "type": "object",
-            "propertyNames": { "type": "string" },
+            "properties": {
+              "references": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "operationId": {
+                      "type": "string",
+                      "pattern": "^op-[1-9][0-9]*$"
+                    },
+                    "source": {
+                      "type": "object",
+                      "properties": {
+                        "format": { "type": "string", "enum": ["awi", "otel"] },
+                        "index": {
+                          "type": "integer",
+                          "minimum": 0,
+                          "maximum": 9007199254740991
+                        }
+                      },
+                      "required": ["format", "index"],
+                      "additionalProperties": false
+                    }
+                  },
+                  "required": ["operationId"],
+                  "additionalProperties": false
+                }
+              }
+            },
+            "required": ["references"],
             "additionalProperties": {}
           }
         },
@@ -97,10 +137,11 @@
       "items": {
         "type": "object",
         "properties": {
-          "traceId": { "type": "string" },
+          "traceId": { "type": "string", "pattern": "^trace-[1-9][0-9]*$" },
+          "recordedTraceId": { "type": "string" },
           "operations": { "type": "array", "items": {} }
         },
-        "required": ["traceId", "operations"],
+        "required": ["traceId", "recordedTraceId", "operations"],
         "additionalProperties": false
       }
     }

package/docs/security.md

@@ -2,10 +2,33 @@
 
 All trace content is inert untrusted JSON. AWI never obeys embedded instructions. Analysis uses no eval, shell execution, URL fetching, telemetry, network, database or intermediate content files. Fixed limits apply to parsing, files, spans, nesting, strings, traversal, cycles, findings and default report amplification. Shared native values count once per occurrence against the processed-content budget.
 
-Ordinary reports include trace/operation IDs, measurements, rule IDs, source indices and explanations. Raw tool names, names, arguments, results, prompts, metadata, error messages and hashes are omitted. IDs can themselves contain secrets; export opaque safe IDs. JSON output escapes terminal formatting and control characters while preserving identifiers on JSON parsing. Human output replaces Unicode controls, formatting controls and line/paragraph separators including ANSI escape and bidirectional controls. Human output colors severity only on supported interactive terminals, honors NO_COLOR and --no-color, and never relies solely on color.
+Default JSON and human reports generated by AWI use report-local ordinal references such as `trace-1` and `op-1`. The references encode rank in a deterministic order. They contain no raw identifier bytes or hashes and are scoped to one report (`op-N` is scoped to one trace within that report). AWI007 still compares exact tool names and error codes internally. Its report gives the number of failures, number of distinct argument fingerprints, and operation references. Default reports omit raw names, codes, arguments, results, prompts, metadata, error messages and fingerprint values. AWI006 uses `currency-N` keys in place of recorded currency labels and preserves each currency group's amount.
 
---show-content includes content and can expose private data. Recursive redaction replaces values by keys matching authorization, password, secret, token, API key, cookie, credential, prompt, message, output or result. It cannot recognize every secret, especially arbitrary argument strings and IDs. Review locally before sharing. AWI never transmits content. Default reports also contain sensitive workflow correlations.
+Reports still expose counts, timing, usage, cost amounts, source indices, relative identifier order, and relationships within the workflow. Those details can be sensitive or allow inference when combined with other data. Review them before sharing. These guarantees apply to reports produced by AWI analysis. The public renderers format the report supplied by the caller and can display strings the caller inserts.
+
+`--show-content` and the third argument to `analyze(traces, config, true)` add a separate `content` section with the recorded trace ID and normalized operations, including recorded operation and parent IDs, names, tool names, error codes, and arguments. Recursive redaction of operations replaces values under keys matching authorization, password, secret, token, API key, cookie, credential, prompt, message, output or result. Arbitrary strings and keys can still reveal private data. Keep these reports private. AWI never transmits trace content.
+
+JSON serialization escapes control and formatting characters where needed. Human output replaces terminal controls, bidirectional formatting and line/paragraph separators. Severity color is limited to supported interactive terminals and honors `NO_COLOR` and `--no-color`.
 
 Parsing rejects `__proto__`, `constructor` and `prototype` object keys. No prototype merging occurs. Files are size-checked before parsing, decoded as strict UTF-8 (optional BOM accepted), and read in bounded chunks even if they grow. Aggregate limits count bytes actually read. CLI rejects symlink entries and symlink components of trace/configuration/output paths. Resolve legitimate OS aliases (including macOS /var temporary paths) to real paths first. POSIX opens also use O_NOFOLLOW, and all platforms compare the opened file identity with the checked file. This is not a filesystem sandbox against concurrent replacement of directory components: use trusted directories and OS permissions. Reports use an adjacent temporary file with mode 0600 on POSIX (Windows uses inherited filesystem ACLs), fsync and atomic exclusive hard-link publication. Existing targets are never overwritten. Cleanup is attempted on ordinary failures; OS errors can prevent removal. Filesystems without hard links fail closed. Crashes or cleanup failures may leave .tmp files to inspect/remove locally under the same filesystem permissions.
 
-Broken stdout pipes produce a controlled operational failure, without an uncaught stack trace. Errors omit raw parser content, OS filenames and stacks. Schema errors show field paths/codes. No general anonymization guarantee exists for identifiers or opt-in content. See SECURITY.md for private disclosure guidance.
+Broken stdout pipes produce a controlled operational failure, without an uncaught stack trace. Errors omit raw parser content, OS filenames and stacks. Schema errors show field paths/codes. See [the security policy](../SECURITY.md) for private disclosure guidance.
+
+## Synthetic before and after
+
+Run the same fixture with the AWI007 opt-in configuration on the previous source revision and on the v2 source:
+
+```sh
+node dist/cli/index.js inspect examples/suspicious/argument-drift.json --config examples/argument-drift.config.json --format json
+```
+
+Selected fields from the AWI007 finding:
+
+| Field                                   | Previous report v1                         | Report v2                      |
+| --------------------------------------- | ------------------------------------------ | ------------------------------ |
+| `traceId`                               | `argument-drift`                           | `trace-1`                      |
+| `operationIds`                          | `drift-0`, `drift-1`, `drift-2`, `drift-3` | `op-1`, `op-2`, `op-3`, `op-4` |
+| `evidence.toolName`                     | `search`                                   | Omitted                        |
+| `evidence.errorCode`                    | `INVALID_QUERY`                            | Omitted                        |
+| `evidence.failedCalls`                  | `4`                                        | `4`                            |
+| `evidence.distinctArgumentFingerprints` | `4`                                        | `4`                            |

package/docs/verification.md

@@ -2,11 +2,17 @@
 
 Audit date: October 19, 2026. Package manager: pnpm 11.25.0. Baseline implementation: 9bc61c1. See the historical [audit findings](audit.md) and current [release procedure](releasing.md).
 
-## Hosted CI and release candidate
+## Quickstart documentation check — October 20, 2026
+
+On Windows, Node 24.19.0 / pnpm 11.25.0: frozen-lockfile installation, `pnpm check` (72 tests: 69 existing plus two README process-exit checks and one documentation encoding check; typecheck, lint and JS/declaration build), `pnpm verify:quickstart`, `pnpm format:check`, schema regeneration with no drift, isolated `pnpm smoke:package`, and `git diff --check` passed. README/getting-started synthetic JSON traces also parsed and analyzed with zero findings.
+
+The quickstart verifier checks complete JSON reports, no warnings, healthy exit 0 with no findings, and retry exit 2 with exactly `AWI002`, `AWI004`, `AWI006`. It uses `process.execPath`, script-relative paths and no shell or network operations. The existing nine-job workflow now runs it; this change has not yet run on hosted CI, macOS, Linux or the other supported Node versions. No runtime source, dependencies or lockfile changed. The README gate exits 0 for the healthy fixture and 1 for the retry fixture; the CLI retains its existing exit codes. Registry/GitHub status was checked read-only; see [release status and limits](releasing.md). No push, tag, release, publish or deployment was performed during this check.
+
+## Historical hosted CI and release preparation
 
 The [nine-job hosted CI run](https://github.com/jigar48/awi/actions/runs/39208844432) completed successfully for `d2514af3e9d4a7b11a53308a77ab2ca40333d8ce`. Windows, macOS and Ubuntu each passed on Node 22.18.0, 24.11.0 and 26, including all 69 tests, typecheck/lint/build, formatting, schema consistency, production dependency audit, packing and isolated package installation/API checks.
 
-The platform table below records the earlier local audit only. The hosted run resolves that audit's platform gate for d2514af. Later local release-preparation changes affect documentation/package metadata, not runtime source or dependencies. They require a fresh nine-job main run before publication; earlier CI does not validate them. No tag, GitHub release or npm publication has been performed.
+The platform table below records the earlier local audit only. The hosted run resolves that audit's platform gate for d2514af. Later local release-preparation changes affect documentation/package metadata, not runtime source or dependencies. They require a fresh nine-job main run before publication; earlier CI does not validate them. At that preparation stage, no tag, GitHub release or npm publication had been performed; publication was subsequently confirmed on October 20, 2026 (see [current release status](releasing.md)).
 
 Release-preparation validation on Windows Node 24.19.0: `pnpm install --frozen-lockfile`, `pnpm check` (69 passing tests, typecheck, lint, JS/declaration build), `pnpm format:check`, `pnpm schemas` (before/after schema hashes unchanged), full `pnpm audit` (no known vulnerabilities), `pnpm smoke:package` (clean external consumer, all shipped examples/options, ESM and strict TypeScript imports), and `git diff --check` passed. Runtime source, tests, dependencies, lockfile and CI workflow remain identical to d2514af. Local documentation links and prepared GitHub topic syntax were checked; version-tagged release links intentionally await tag creation. Maintainer GitHub/portfolio/support links responded successfully; LinkedIn rejects HEAD checks, so that supplied URL is retained without claiming live content verification. Candidate artifact byte counts, SHA-256/SHA-512 and source SHA are recorded outside the package in the local release manifest.
 
@@ -35,4 +41,4 @@ WSL uses real Linux Node distributions and independent Linux dependencies. Downl
 
 A cold-filesystem declaration compilation timeout and a multi-process CLI test timeout were diagnosed as test-harness I/O budgets, not waived product assertions. CLI setup compiles runtime JS with a bounded setup timeout; full builds/consumer typechecks still verify declarations. CLI subprocesses and end-to-end I/O cases have explicit budgets; detector performance checks remain unchanged.
 
-During the original local audit, no remote mutations occurred. The later authorized feature-branch push produced the successful hosted run above. **Publication remains blocked until approval, a fresh successful matrix on the final main candidate, and npm authentication/name checks.** See [release procedure](releasing.md).
+During the original local audit, no remote mutations occurred. The later authorized feature-branch push produced the successful hosted run above. At that stage, publication required approval, a fresh successful matrix on the final main candidate, and npm authentication/name checks. The current published status is recorded separately. See [release procedure](releasing.md).

package/examples/argument-drift.config.json

@@ -0,0 +1,9 @@
+{
+  "rules": {
+    "AWI007": {
+      "enabled": true,
+      "threshold": 4,
+      "minDistinctArguments": 3
+    }
+  }
+}

package/examples/suspicious/argument-drift.json

@@ -0,0 +1,62 @@
+{
+  "version": 1,
+  "traceId": "argument-drift",
+  "operations": [
+    {
+      "id": "drift-0",
+      "type": "tool",
+      "name": "search",
+      "arguments": {
+        "query": "synthetic-0"
+      },
+      "status": "error",
+      "error": {
+        "code": "INVALID_QUERY"
+      },
+      "startTime": "2023-11-14T22:13:20.000Z",
+      "endTime": "2023-11-14T22:13:20.500Z"
+    },
+    {
+      "id": "drift-1",
+      "type": "tool",
+      "name": "search",
+      "arguments": {
+        "query": "synthetic-1"
+      },
+      "status": "error",
+      "error": {
+        "code": "INVALID_QUERY"
+      },
+      "startTime": "2023-11-14T22:13:21.000Z",
+      "endTime": "2023-11-14T22:13:21.500Z"
+    },
+    {
+      "id": "drift-2",
+      "type": "tool",
+      "name": "search",
+      "arguments": {
+        "query": "synthetic-2"
+      },
+      "status": "error",
+      "error": {
+        "code": "INVALID_QUERY"
+      },
+      "startTime": "2023-11-14T22:13:22.000Z",
+      "endTime": "2023-11-14T22:13:22.500Z"
+    },
+    {
+      "id": "drift-3",
+      "type": "tool",
+      "name": "search",
+      "arguments": {
+        "query": "synthetic-3"
+      },
+      "status": "error",
+      "error": {
+        "code": "INVALID_QUERY"
+      },
+      "startTime": "2023-11-14T22:13:23.000Z",
+      "endTime": "2023-11-14T22:13:23.500Z"
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-workflow-inspector",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "Local-first, deterministic linter for AI agent traces: detect suspicious retries, repeated tool calls, execution cycles, and resource burn.",
   "type": "module",
   "license": "MIT",
@@ -75,6 +75,7 @@
     "format:check": "prettier --check .",
     "check": "pnpm typecheck && pnpm lint && pnpm test && pnpm build",
     "schemas": "pnpm build && node scripts/schemas.mjs",
-    "smoke:package": "node scripts/package-smoke.mjs"
+    "smoke:package": "node scripts/package-smoke.mjs",
+    "verify:quickstart": "node scripts/verify-quickstart.mjs"
   }
 }