fix(inspect): clarify engine-view content-gate behavior

.github/workflows/ci.yml

@@ -5,6 +5,10 @@ env:
 
 on:
   pull_request:
+    paths:
+      - "src/**"
+      - "crates/**"
+      - "test/**"
 
 jobs:
   validate:

README.md

@@ -111,6 +111,7 @@ Inspect detector behavior without count output:
 ```bash
 word-counter inspect "こんにちは、世界！これはテストです。"
 word-counter inspect --detector wasm --view engine "This sentence should clearly be detected as English for the wasm detector path."
+word-counter inspect --detector wasm --view engine --content-gate strict "Readers understand this behavior."
 word-counter inspect --detector regex -f json "こんにちは、世界！これはテストです。"
 word-counter inspect --detector regex -f json --pretty "こんにちは、世界！これはテストです。"
 word-counter inspect --detector wasm --content-gate off "mode: debug\ntee: true\npath: logs\nUse this for testing."
@@ -144,6 +145,11 @@ Detector mode notes:
 - Technical-noise-heavy Latin windows stay conservative and may remain `und-Latn` even when the detector produces a wrong-but-confident language guess.
 - inspect/debug disclosure uses `contentGate` as the canonical gate field.
 - legacy debug/evidence payloads still emit `qualityGate` as a compatibility alias derived from `contentGate.passed`.
+- `inspect --view engine` stays raw:
+  - it shows the detector sample plus raw/normalized/remapped Whatlang output
+  - it does not apply `eligibility` or `contentGate` policy decisions
+  - if engine view uses an explicit or effective non-default content-gate mode, the CLI emits a cyan info note and points to `--view pipeline`
+- `inspect --view pipeline` is the inspect surface for `eligibility`, `contentGate`, acceptance, and fallback reasoning.
 - for practical verification, use `inspect` to compare direct mode outcomes across `default`, `strict`, `loose`, and `off`; use `--debug --detector-evidence` when you specifically need counting-flow event details or legacy `qualityGate` compatibility
 - `word-counter inspect` supports:
   - positional text input

docs/plans/jobs/2026-03-31-inspect-engine-content-gate-info-note-implementation.md

@@ -0,0 +1,36 @@
+---
+title: "inspect engine content gate info note implementation"
+created-date: 2026-03-31
+status: completed
+agent: Codex
+---
+
+## Goal
+
+Implement the settled `inspect --view engine` info-note behavior so raw engine inspection stays unchanged while users are explicitly redirected to `--view pipeline` when `contentGate` policy expectations would otherwise be misleading.
+
+## Completed Work
+
+- Updated `src/cli/inspect/run.ts` to emit a cyan `Info:` note to stderr when:
+  - `inspect` is running with `--view engine`
+  - the effective detector is `wasm`
+  - `--content-gate ...` was explicitly passed, including `default`, or config/env resolves the effective mode to a non-default value
+- Kept the note outside the inspect result body so both standard and JSON stdout payloads remain unchanged.
+- Ensured the note is emitted once per inspect invocation, including inspect batch runs.
+- Updated `src/cli/inspect/help.ts` so `--content-gate` is described as pipeline policy inspection behavior.
+- Updated `README.md` and `docs/schemas/detector-inspector-output-contract.md` so engine vs pipeline responsibilities are explicit and the note trigger behavior is documented.
+- Marked the implementation plan complete in `docs/plans/plan-2026-03-31-inspect-engine-content-gate-info-note-implementation.md`.
+
+## Verification
+
+- `bun test test/command-inspect.test.ts test/command-config-inspect.test.ts`
+  - 49 tests passed
+  - 0 tests failed
+
+## Related Research
+
+- `docs/researches/research-2026-03-31-inspect-engine-content-gate-info-note.md`
+
+## Related Plans
+
+- `docs/plans/plan-2026-03-31-inspect-engine-content-gate-info-note-implementation.md`

docs/plans/plan-2026-03-31-inspect-engine-content-gate-info-note-implementation.md

@@ -0,0 +1,110 @@
+---
+title: "inspect engine content gate info note implementation"
+created-date: 2026-03-31
+modified-date: 2026-03-31
+status: completed
+agent: Codex
+---
+
+## Goal
+
+Implement the settled `inspect --view engine` UX refinement so `--content-gate ...` keeps its current raw-engine behavior while the CLI emits a cyan informational note that directs users to `--view pipeline` for eligibility and content-gate restriction diagnosis.
+
+## Context
+
+- The current `engine` view is intentionally raw and reports the diagnostic sample plus Whatlang output without package-level projection.
+- The current `pipeline` view is where `eligibility`, `contentGate`, acceptance, and fallback decisions are evaluated and disclosed.
+- The CLI currently accepts `--content-gate ...` together with `--view engine`, but that flag does not change engine output.
+- The new research settles that the UX gap should be solved with an informational note rather than with validation rejection or engine-view policy semantics.
+
+## Scope
+
+- In scope:
+  - add an inspect-local informational note for `--view engine` combined with a meaningful content-gate setting
+  - keep the note styled as cyan/info rather than warning/error output
+  - define the exact trigger rules for explicit CLI, config, and env-derived content-gate settings
+  - update inspect help and docs so engine vs pipeline responsibilities are explicit
+  - add regression coverage for note emission and non-emission cases
+- Out of scope:
+  - changing `engine` view payloads or output fields
+  - applying `contentGate` policy inside `engine` view
+  - rejecting `--content-gate` together with `--view engine`
+  - changing detector thresholds, route policy behavior, or window selection
+  - broader inspect UX redesign unrelated to this note
+
+## Decisions Settled for This Plan
+
+- `--view engine` remains a raw engine/sample/remap surface.
+- `--content-gate` remains accepted syntax under `inspect --view engine`.
+- The CLI should emit a cyan info note when:
+  - the user explicitly passes `--content-gate ...`, including `default`
+  - the effective inspect content-gate mode comes from config or env and resolves to a non-default value
+- The CLI should not emit the note for ordinary engine-view runs that simply inherit the default content-gate mode with no explicit or effective override.
+- The note should be emitted once per inspect invocation, before single-input or batch rendering begins, so batch runs do not repeat the same message per file.
+- The note should explain both facts:
+  - `--content-gate` does not affect engine-view output
+  - `--view pipeline` is the correct inspect surface for eligibility and content-gate restriction diagnosis
+- The implementation should stay inspect-local rather than introducing a broader shared CLI notice abstraction unless a concrete duplication need appears during coding.
+
+## Phase Task Items
+
+### Phase 1 - Effective-Mode Note Emission
+
+- [x] Identify the inspect command point where config/env application has already resolved the effective detector and content-gate values.
+- [x] Add inspect-local logic that emits the cyan info note before execution when:
+  - `view === "engine"`
+  - `detector === "wasm"`
+  - the note trigger rules are satisfied
+- [x] Keep the note out of the main inspect result body so standard and JSON result payloads remain unchanged.
+- [x] Ensure the note is emitted to stderr rather than being mixed into stdout result output.
+- [x] Ensure the note is emitted once per inspect invocation, including batch runs, rather than once per inspected file.
+
+Validation for this phase:
+
+- command tests for explicit CLI `--content-gate default|strict|loose|off` with `--view engine`
+- command tests proving explicit `--content-gate default` emits the note while inherited default content-gate does not
+- command tests for config/env-derived non-default content-gate modes with `--view engine`
+- command tests proving ordinary default engine runs do not emit the note
+- command tests proving batch engine runs emit the note once per invocation, not once per file
+
+### Phase 2 - Docs And Help Alignment
+
+- [x] Update inspect help text to clarify that `--content-gate` affects pipeline policy inspection, not raw engine view.
+- [x] Update `README.md` inspect guidance so engine vs pipeline responsibilities are explicit at the user-facing command level.
+- [x] Update `docs/schemas/detector-inspector-output-contract.md` to note that engine view ignores content-gate policy and that the CLI may emit an informational note for that combination.
+- [x] Keep the wording aligned with the settled research message and cyan/info intent.
+
+Validation for this phase:
+
+- docs review against the settled research note
+- spot-check command examples so the docs do not imply engine-view gate enforcement
+
+### Phase 3 - Regression And Contract Audit
+
+- [x] Confirm that engine-view stdout output remains unchanged for the same input before and after the note feature.
+- [x] Confirm that inspect JSON output remains schema-identical and free of note text.
+- [x] Confirm that pipeline-view behavior, counting behavior, and detector-subpath inspect library results remain unchanged.
+
+Validation for this phase:
+
+- targeted `test/command-inspect.test.ts` coverage for stdout/stderr separation
+- targeted regression checks for JSON output stability
+- targeted detector inspect tests if implementation touches shared inspect execution code
+
+## Compatibility Gates
+
+- [x] `inspect --view engine` continues to return the same detector result data for the same text.
+- [x] The new informational note does not alter stdout payloads for either `standard` or `json` output.
+- [x] `inspect --view pipeline` remains the only inspect view that exposes `eligibility`, `contentGate`, and fallback reasoning.
+- [x] Existing config/env/CLI precedence for effective content-gate mode remains unchanged.
+
+## Related Research
+
+- `docs/researches/research-2026-03-31-inspect-engine-content-gate-info-note.md`
+- `docs/researches/research-2026-03-25-detector-policy-and-inspector-surface.md`
+- `docs/researches/research-2026-03-25-configurable-content-gate-behavior.md`
+
+## Related Plans
+
+- `docs/plans/plan-2026-03-25-detector-policy-and-inspect-command.md`
+- `docs/plans/plan-2026-03-26-config-content-gate-support.md`

docs/researches/research-2026-03-31-inspect-engine-content-gate-info-note.md

@@ -0,0 +1,67 @@
+---
+title: "inspect engine content gate info note"
+created-date: 2026-03-31
+modified-date: 2026-03-31
+status: completed
+agent: codex
+---
+
+## Goal
+
+Decide how `word-counter inspect --detector wasm --view engine` should behave when `--content-gate ...` is also present, and record the recommended user-facing guidance.
+
+## Key Findings
+
+- The current `engine` view is intentionally raw and does not run the package-level policy path.
+  - In `src/detector/wasm.ts`, `view === "engine"` returns the first ambiguous window through `buildEngineInspectResult(...)`.
+  - That path reports the diagnostic sample, raw Whatlang result, normalized Whatlang result, and public remap values.
+  - It does not compute or disclose `eligibility`, `contentGate`, or final acceptance/fallback decisions.
+- The current `pipeline` view is where `contentGate` actually matters.
+  - In `src/detector/wasm-resolution.ts`, the detector route policy evaluates both `eligibility` and `contentGate` before deciding whether the engine result is accepted or falls back.
+  - This is also the only inspect surface that currently explains why a window was skipped, accepted, or rejected.
+- Because the CLI still accepts `--content-gate` together with `--view engine`, users can reasonably infer that the flag should affect engine output.
+  - In practice, the same text currently produces the same engine-view output across `default`, `strict`, `loose`, and `off`.
+  - The current behavior is technically consistent with the raw-engine contract, but the UX is misleading because the CLI does not explain the limitation at the point of use.
+- Making `contentGate` behavior-changing inside engine view would blur the contract.
+  - A raw engine view should answer: "what sample was sent to Whatlang, and what did it say?"
+  - A policy-aware view should answer: "did the package accept that result, and if not, why?"
+  - Folding policy decisions back into engine view would create ambiguity around window selection, skipped windows, and whether engine output should disappear or be annotated when the window is not policy-eligible.
+
+## Implications or Recommendations
+
+- Keep `engine` view raw.
+  - Preserve the current contract where engine view reports sample construction and Whatlang output without package-level projection.
+- Do not reject `--content-gate` when `--view engine` is requested.
+  - Rejection is defensible, but it is stricter than needed and removes a recoverable learning moment.
+  - A note is sufficient because the requested command still produces valid raw engine diagnostics.
+- Add a cyan informational note when `engine` view is combined with a meaningful content-gate setting.
+  - Recommended message:
+    - `Info: \`--content-gate\` does not affect \`inspect --view engine\`; engine view shows raw detector output. Use \`--view pipeline\` to inspect eligibility and content-gate restrictions.`
+  - Recommended trigger:
+    - show the note when the user explicitly passed `--content-gate ...`, including `default`
+    - also show the note when the effective mode comes from config or env and resolves to a non-default value
+  - Recommended non-trigger:
+    - do not show the note for ordinary engine-view runs that simply inherit the default mode with no explicit or effective override
+- Update inspect-facing docs to make the split explicit.
+  - `--view engine` should be documented as raw engine/sample/remap output only.
+  - `--view pipeline` should be documented as the place to inspect `eligibility`, `contentGate`, and fallback reasoning.
+  - Help text and README examples should steer users toward pipeline view for policy verification.
+
+## Related Plans
+
+- [docs/plans/plan-2026-03-25-detector-policy-and-inspect-command.md](docs/plans/plan-2026-03-25-detector-policy-and-inspect-command.md)
+- [docs/plans/plan-2026-03-31-inspect-engine-content-gate-info-note-implementation.md](docs/plans/plan-2026-03-31-inspect-engine-content-gate-info-note-implementation.md)
+
+## Related Research
+
+- [docs/researches/research-2026-03-25-detector-policy-and-inspector-surface.md](docs/researches/research-2026-03-25-detector-policy-and-inspector-surface.md)
+- [docs/researches/research-2026-03-25-configurable-content-gate-behavior.md](docs/researches/research-2026-03-25-configurable-content-gate-behavior.md)
+
+## References
+
+[^1]: [docs/researches/research-2026-03-25-detector-policy-and-inspector-surface.md](docs/researches/research-2026-03-25-detector-policy-and-inspector-surface.md)
+[^2]: [docs/schemas/detector-inspector-output-contract.md](docs/schemas/detector-inspector-output-contract.md)
+[^3]: [src/detector/wasm.ts](src/detector/wasm.ts)
+[^4]: [src/detector/wasm-resolution.ts](src/detector/wasm-resolution.ts)
+[^5]: [src/cli/inspect/render.ts](src/cli/inspect/render.ts)
+[^6]: [src/cli/inspect/help.ts](src/cli/inspect/help.ts)