@bilalimamoglu/sift 0.4.5 → 0.5.0

package/README.md

@@ -21,7 +21,7 @@
 npm install -g @bilalimamoglu/sift
 ```
 
-<sub>Works with pytest, vitest, jest, tsc, ESLint, webpack, Cargo, terraform, npm audit, and more.</sub>
+<sub>Best today on noisy pytest, vitest, jest, `tsc`, ESLint, common build failures, `npm audit`, and `terraform plan` output.</sub>
 
 </div>
 
@@ -33,6 +33,8 @@ When an agent hits noisy output, it can eventually make sense of the log wall, b
 
 `sift` narrows that output locally first. It groups repeated failures, surfaces likely root causes, and points to the next useful step so your agent starts from signal instead of raw noise.
 
+It is not a generic repo summarizer, not a shell telemetry product, and not a benchmark dashboard. It is a local-first triage layer for noisy command output in coding-agent workflows.
+
 Turn 13,000 lines of test output into 2 root causes.
 
 <p align="center">
@@ -53,13 +55,56 @@ With `sift`, the same run becomes:
 - Decision: stop and act.
 ```
 
-In the largest benchmark fixture, sift compressed 198,026 raw output tokens to 129. That is what the agent reads instead of the full log.
+In one large `test-status` benchmark fixture, `sift` compressed 198,026 raw output tokens to 129. That is scoped proof for a noisy test-debugging case, not a promise that every preset behaves the same way.
+
+---
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install -g @bilalimamoglu/sift
+```
+
+Requires Node.js 20+.
+
+### 2. Try the main workflow
+
+If you are new, start here and ignore hook beta and native surfaces for now:
+
+```bash
+sift exec --preset test-status -- pytest -q
+```
+
+Other common entry points:
+
+```bash
+sift exec --preset test-status -- npx vitest run
+sift exec --preset test-status -- npx jest
+sift exec "what changed?" -- git diff
+```
+
+### 3. Zoom only if needed
+
+Think of the workflow like this:
+
+- `standard` = map
+- `focused` = zoom
+- raw traceback = last resort
+
+```bash
+sift rerun
+sift rerun --remaining --detail focused
+```
+
+If `standard` already gives you the likely root cause, anchor, and fix, stop there and act.
 
 ---
 
 ## Benchmark Results
 
-The output reduction above measures a single command's raw output. The table below measures the full end-to-end debug session: how many tokens, tool calls, and seconds the agent spends to reach the same outcome.
+The output reduction above measures a single command's raw output. The table below measures one replayed end-to-end debug loop: how many tokens, tool calls, and seconds the agent spent to reach the same outcome in that benchmarked scenario.
 
 Real debug loop on a 640-test Python backend with 124 repeated setup errors, 3 contract failures, and 511 passing tests:
 
@@ -129,7 +174,7 @@ Every built-in preset tries local parsing first. When the heuristic handles the
 <td width="33%" valign="top">
 
 ### Agent and Automation Friendly
-Use `sift` in Codex, Claude, CI, hooks, or shell scripts so downstream tooling gets short, structured answers instead of raw noise.
+Use `sift` in Codex, Claude, CI, hooks, or shell scripts when you want downstream tooling to receive a short first pass instead of the raw log wall.
 
 </td>
 </tr>
@@ -137,134 +182,69 @@ Use `sift` in Codex, Claude, CI, hooks, or shell scripts so downstream tooling g
 
 ---
 
-## Setup and Agent Integration
-
-Most built-in presets run entirely on local heuristics with no API key required. If you want deeper fallback for ambiguous cases, `sift` also supports OpenAI-compatible and OpenRouter-compatible endpoints.
-
-Start with the guided installer:
-
-```bash
-sift install
-```
-
-During install, pick the mode that matches reality:
-- `agent-escalation`: best if Codex or Claude is already open. `sift` gives the first answer, then your agent keeps going.
-- `provider-assisted`: best if you want `sift` itself to ask a cheap fallback model when needed. This is the API-key path.
-- `local-only`: best if `sift` is working alone and you want everything to stay local.
-
-Then try the normal diagnosis loop:
-
-```bash
-sift exec --preset test-status -- pytest -q
-```
-
-If you choose `provider-assisted` during install, `sift` now continues directly into provider, model, and API-key setup instead of making you run a second command.
-
-Use `sift config setup` later when you want to revisit or change those choices:
-
-```bash
-sift config setup
-sift doctor
-```
-
-OpenAI setup defaults to `gpt-5-nano`, with `gpt-5.4-nano` and `gpt-5-mini` offered as backup choices during setup.
-
-Before pushing release-sensitive changes, run the same shared gate used by CI and the release workflow:
-
-```bash
-npm run verify:release
-```
-
-That gate runs under a CI-like environment on purpose so wrapper-noise regressions show up locally before they embarrass the repo in publish.
-
-If you want one extra paranoid pass before a release or risky push, use the clean-room variant too:
-
-```bash
-npm run verify:release:clean
-```
-
-That copies the repo into a temporary clean directory, runs `npm ci`, then executes the shared core gate there so warm local `node_modules` do not hide CI failures.
-
-If you want pushes to enforce the same core gate automatically inside this repo:
-
-```bash
-npm run setup:hooks
-```
+## Presets
 
-That installs the tracked `.githooks/pre-push` hook, which runs `npm run verify:release:core` before every push.
+| Preset | What it does | Needs provider? |
+|--------|--------------|:---------------:|
+| `test-status` | Groups pytest, vitest, and jest failures into root-cause buckets with anchors and fix suggestions. | No |
+| `typecheck-summary` | Parses `tsc` output and groups issues by error code. | No |
+| `lint-failures` | Parses ESLint output and groups failures by rule. | No |
+| `build-failure` | Extracts the first concrete build error from common toolchains. | Fallback only |
+| `contract-drift` | Detects explicit snapshot, golden, OpenAPI, manifest, or generated-artifact drift without broadening into generic repo analysis. | Fallback only |
+| `audit-critical` | Pulls high and critical `npm audit` findings. | No |
+| `infra-risk` | Detects destructive signals in `terraform plan`. | No |
+| `diff-summary` | Summarizes change sets and likely risks in diff output. | Yes |
+| `log-errors` | Extracts the strongest error signals from noisy logs. | Fallback only |
 
-If you want the older low-level controls, you can still preview, inspect, or remove the managed blocks directly:
+When output already exists in a pipeline, use pipe mode instead of `exec`:
 
 ```bash
-sift agent show codex
-sift agent install codex --dry-run
-sift agent status
-sift agent remove codex
+pytest -q 2>&1 | sift preset test-status
+npm audit 2>&1 | sift preset audit-critical
 ```
 
-Command-first details live in [docs/cli-reference.md](docs/cli-reference.md).
-
 ---
 
-## Quick Start
-
-### 1. Install
-
-```bash
-npm install -g @bilalimamoglu/sift
-```
-
-Requires Node.js 20+.
+## Setup and Agent Integration
 
-### 2. Get a useful first pass before your agent reads the full log
+If you want deeper integration after the first successful `sift exec` run, start with:
 
 ```bash
-sift exec --preset test-status -- pytest -q
+sift install
 ```
 
-Other common entry points:
+Most built-in presets run entirely on local heuristics with no API key required. If you want deeper fallback for ambiguous cases, `sift` also supports OpenAI-compatible and OpenRouter-compatible endpoints.
 
-```bash
-sift exec --preset test-status -- npx vitest run
-sift exec --preset test-status -- npx jest
-sift exec "what changed?" -- git diff
-```
+During install, pick the mode that matches reality:
+- `agent-escalation`: `sift` gives the first answer, then your agent keeps going
+- `provider-assisted`: `sift` itself can ask a cheap fallback model when needed
+- `local-only`: keep everything local
 
-### 3. Zoom only if needed
+Runtime-native files are small guidance surfaces, not a second execution system:
+- Codex: managed `AGENTS.md` block plus a generated `SKILL.md`
+- Claude: managed `CLAUDE.md` block plus a generated `.claude/commands/sift/` command pack
+- Cursor: optional `.cursor/skills/sift/SKILL.md` path when you want an explicit native Cursor skill
 
-Think of the workflow like this:
+Default rule:
+- use `sift exec` for the normal first pass
+- use `sift hook` only as an optional beta shortcut for a tiny known-command set
 
-- `standard` = map
-- `focused` = zoom
-- raw traceback = last resort
+Optional local evidence surfaces:
 
 ```bash
-sift rerun
-sift rerun --remaining --detail focused
+sift gain
+sift discover
 ```
 
-If `standard` already gives you the likely root cause, anchor, and fix, stop there and act.
+- `gain` shows local, metadata-only first-pass history
+- `discover` stays quiet unless your own local history is strong enough to justify a concrete suggestion
 
----
+If you want the full install, ownership, and touched-files details, see [docs/cli-reference.md](docs/cli-reference.md). The short version: `sift` does **not** write shell rc files, PATH entries, git hooks, or arbitrary repo files during install.
 
-## Presets
-
-| Preset | What it does | Needs provider? |
-|--------|--------------|:---------------:|
-| `test-status` | Groups pytest, vitest, and jest failures into root-cause buckets with anchors and fix suggestions. | No |
-| `typecheck-summary` | Parses `tsc` output and groups issues by error code. | No |
-| `lint-failures` | Parses ESLint output and groups failures by rule. | No |
-| `build-failure` | Extracts the first concrete build error from common toolchains. | Fallback only |
-| `audit-critical` | Pulls high and critical `npm audit` findings. | No |
-| `infra-risk` | Detects destructive signals in `terraform plan`. | No |
-| `diff-summary` | Summarizes change sets and likely risks in diff output. | Yes |
-| `log-errors` | Extracts the strongest error signals from noisy logs. | Fallback only |
-
-When output already exists in a pipeline, use pipe mode instead of `exec`:
+If you want this repo's tracked pre-push verification hook to actually run on your machine, you still need to activate it once:
 
 ```bash
-pytest -q 2>&1 | sift preset test-status
-npm audit 2>&1 | sift preset audit-critical
+npm run setup:hooks
 ```
 
 ---
@@ -294,6 +274,8 @@ sift exec --preset test-status --goal diagnose --format json -- pytest -q
 sift rerun --goal diagnose --format json
 ```
 
+Diagnose JSON is summary-first on purpose. If `read_targets.anchor_kind=traceback` and `read_targets.context_hint.kind=exact_window`, read that narrow range first. If the read target is lower-confidence or `search_only`, treat it as a representative hint rather than exact root-cause proof.
+
 ---
 
 ## Limitations
@@ -301,6 +283,7 @@ sift rerun --goal diagnose --format json
 - sift adds the most value when output is long, repetitive, and shaped by a small number of root causes. For short, obvious failures it may not save much.
 - The deepest local heuristic coverage is in test debugging (pytest, vitest, jest). Other presets have solid heuristics but less depth.
 - sift does not help with interactive or TUI-based commands.
+- sift is not a generic repo summarizer or broad mismatch detector. It works best when the command output itself carries strong failure or drift evidence.
 - When heuristics cannot explain the output confidently, sift either falls back to a provider or returns the strongest local first pass it can, depending on how you choose to use it.
 
 ---