dsh-intent-formation

Readme

# Intent Formation

[![CI](https://github.com/rrrrrredy/intent-loop/actions/workflows/ci.yml/badge.svg)](https://github.com/rrrrrredy/intent-loop/actions/workflows/ci.yml)
[![Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[Legacy v0.2 downloads](https://github.com/rrrrrredy/intent-loop/releases) · [中文入门](docs/simple-guide.zh-CN.md)

Intent Formation helps Codex follow what you want as you see results and change your mind. Clear tasks continue normally. When a choice genuinely changes the next useful action, Codex asks one focused question, shows two or three concrete directions, or makes a tiny sample you can react to. With local state enabled, short sourced records retain the current goal and distinguish fixing the work from changing the goal.

There is no form to fill in and no separate chat app. Talk to Codex as usual.

**Experimental source, not a v0.3 release:** the natural-feedback/state connection is implemented and the candidate passed all 18 cross-platform CI jobs. The final confirmation attempted 160 conversations but produced only 79/80 usable pairs; its diagnostic final-match gain was 1.58 percentage points against the unchanged 10-point gate. That study is closed and its failure is preserved. Source maintenance and bounded usability checks continue; efficacy is not established. See the [complete results](evidence/final-confirmation-20260907/README.md), [current goals](docs/current-goals.md) and [release decision](docs/release-decision.md).

## What it feels like

- “Translate this paragraph.” → Codex translates it directly.
- “Design the product so it feels premium.” → If plausible meanings would produce materially different work, Codex asks one useful tradeoff question.
- “I know this screen is wrong, but I cannot describe why.” → Codex shows a few small alternatives so you can point to what fits.
- “The button is broken; keep the design.” → Codex treats that as an implementation correction, not a new preference.

The product stays inside the current task. Codex still owns planning, tools, permissions, implementation, testing, and delivery.

## Installation status

There is no v0.3 release or installer. The v0.2 downloads belong to the earlier product; do not uninstall a working v0.2 setup to follow a nonexistent v0.3 tag.

Prerequisites: [Codex CLI](https://developers.openai.com/codex/cli) and Node.js 20 or newer on `PATH`.

For developers who already use Codex, the [fixed-commit source trial](docs/source-trial.md) gives an executable, isolated test path. It is experimental, not a recommendation for production use. If you are new to terminals or Codex setup, start with the [plain-language explanation](docs/simple-guide.zh-CN.md); a beginner-ready installation is still unfinished.

After source installation, start a new Codex task and review the plugin Hook when Codex asks. The core plugin receives no prompt text through its MCP tool and writes no intent records.

This core-only mode supplies interaction guidance without persistent continuity. Give Codex a task in your own words. To retain the evolving goal across processes, enable State below.

## Optional local memory and controls

After configuring the source trial marketplace, install the State companion only when you want a small task-local record that can survive compaction or a later process:

~~~shell
codex plugin add intent-formation-state@intent-loop
~~~

Start a new task, review the two local Hooks, then type:

~~~text
/intent start
~~~

Once enabled, continue in ordinary language: “Keep the purpose; fix the spacing,” or “I changed my mind; make it for volunteers.” The development Hook supplies existing records and the current turn reference; Codex uses the existing MCP tools to save material changes. You do not need to copy record IDs for normal feedback. The [latest source-use check](evidence/source-usability-20260908/README.md) includes actual file creation and revisions, a retained stale-feedback defect, and a separate targeted repair regression. Earlier [source-bound observations](evidence/continuous-intent-loop-20260907/README.md) include a fresh-process resume and a non-activated task. These are synthetic implementation checks, not measured user benefit or a released capability.

Use `/intent show` to check what was actually retained and `/intent off` to stop. The remaining controls are optional explicit overrides:

| Message | Effect |
| --- | --- |
| `/intent remember <one short goal>` | In standard mode, save one explicit goal with a receipt; `constraint:`, `preference:`, `success:`, and `tradeoff:` prefixes are optional. |
| `/intent show` | Show the active task records and their source. |
| `/intent correct <record-id> => <replacement>` | After `show`, copy the record ID and replace its current statement; the old record remains auditable. |
| `/intent export` | Write an integrity-checked JSON export and report its opaque export ID and SHA-256. |
| `/intent private` | Purge persisted task content; new record text lives only in the current MCP process. |
| `/intent off` | Stop implicit intent intervention and state updates for this task. |
| `/intent forget` | Physically purge this task from plugin-managed state and managed exports. |

`/intent off` is confirmed only when the reviewed State UserPromptSubmit Hook returns an `IF-...` receipt. Noninteractive `codex exec` cannot perform Codex's Hook review; do not treat its model-only fallback as an off switch. Release automation uses the bypass flag only after reviewing the exact packaged Hook.

Successful controls return a short receipt such as `IF-12AB34CD`. No receipt means no success claim.

Exports are stored under `<CODEX_HOME>/plugin-data/intent-formation/exports/<export-id>`. The plugin does not place an absolute local path into model context.

The reported SHA-256 is the structured content digest, not the hash of the complete formatted file. Import verifies it automatically; see [export verification](docs/export-verification.md) for the exact calculation.

After `/intent start`, Codex may save short atomic paraphrases of material user goals and feedback; the ordinary-prompt Hook only reads existing state and does not parse or persist the prompt. Complete prompts, transcripts, assistant responses, workspace files, and tool output must not be copied into records. This content-minimization rule relies on the host for semantic writes; personal information deliberately placed in a statement can still remain. This is not a secret vault or general DLP system. On Unix-like systems, managed directories/files use `0700`/`0600`; Windows relies on the current account's inherited filesystem ACLs.

Local storage is not local-only processing: enabled State supplies selected records to Codex as context, where the host and configured model provider may process them. The plugin has no direct upload or telemetry client.

The trusted short-lived Hook refuses private remember, feedback, show, and correction commands: it cannot retain writes or retrieve another process's private memory. Private records can still be managed through the State MCP tools and last only for that MCP process. Private mode never stores a custom task title or workspace hash. Returning to standard mode with `/intent start` restores the reliable slash-command path.

See the [plain-language Chinese guide](docs/simple-guide.zh-CN.md), [privacy policy](docs/privacy-policy.md), and [threat model](docs/privacy-threat-model.md).

## DeepSeek Harness

The repository also contains `dsh-intent-formation`, a thin adapter for the official DeepSeek Harness developer preview. It shares the exact interaction policy and exposes the optional state tools through a session-bound local MCP process. Setting a session to `off` removes the policy on the next Harness system-prompt assembly, including after adapter restart.

The new Codex UserPromptSubmit continuity connection is not a claim of equivalent natural-feedback behavior in DeepSeek. The adapter's current claim remains compatibility and local tool lifecycle.

DeepSeek Harness currently requires Node.js `^22.19.0` or `>=24.0.0` and `pnpm`. The adapter is pinned to Harness `0.1.2-rc.1`; prerelease API changes may require a new Intent Formation prerelease. See [dsh/README.md](dsh/README.md).

## Evidence status

An earlier 80-scenario run is preserved as a [development regression](evidence/development-regression-v8/README.md). Because the policy was iterated against that corpus, its strong result is not used as release-efficacy evidence.

The [development ablation report](docs/ablation-report.md) records which policy and architecture elements were removed, which removals caused real Hook failures, and the observed model boundary. It is also excluded from release-efficacy claims.

The independently sealed v6 holdout was run to completion and returned `STOP`: clear-task paired latency, wrong-intervention rate, and inference-denial rate missed their fixed thresholds. A post-run audit also found at least eleven scenarios whose final-match checklist contained facts absent from the user-visible turns, so the run is retained only as a [failed diagnostic](evidence/failed-holdout-v6/README.md), never as efficacy evidence.

The [v7 primary run](evidence/failed-holdout-v7/README.md) produced 155 usable conversations out of 160, leaving 75 complete pairs. Four explicit model-capacity failures and one timeout were retained without primary replacement. The available-pair diagnostic is ineligible for release and also retains failed inference-denial and premature-action gates. A separate [case audit](docs/v7-case-audit.md) distinguishes real rule-selection and delivery-scope problems from hindsight grading; original scores remain unchanged.

The final independent confirmation has finished and did not establish the required benefit. No replacement holdout is queued, and maintenance or source usability checks do not clear the failed efficacy gate. A v0.3 release remains blocked by the [release decision](docs/release-decision.md). DeepSeek support has a separate compatibility and lifecycle boundary; Codex observations are not DeepSeek efficacy results.

## Platform boundary

Source and packaging checks run on Windows, Ubuntu, and macOS with supported Node versions. The release gate requires all 18 jobs to pass: 9 Codex package combinations, 6 DeepSeek adapter combinations, and a real temporary DeepSeek package/add/compose/boot-help/remove lifecycle on all three operating systems. Native GUI behavior is outside this headless claim.

## Uninstall

If State is installed and you want its current task data removed, run `/intent forget` first and keep the receipt. Close Codex tasks using these plugins. Before removal, confirm this terminal still uses the same disposable `CODEX_HOME` and that `codex plugin marketplace list --json` reports the trial source, not your daily v0.2 environment. Then run:

~~~shell
codex plugin remove intent-formation-state@intent-loop
codex plugin remove intent-formation@intent-loop
codex plugin marketplace remove intent-loop
~~~

On Windows, if removal reports a file in use or `os error 32`, close the trial processes. If you open a separate terminal, select and verify the same disposable `CODEX_HOME` again before retrying. An active MCP process can hold the installed directory open. Do not delete the source checkout or terminate unrelated Node processes.

The DeepSeek source lifecycle check removes its own temporary installation; do not run another uninstall afterward. For a separately installed adapter, select and verify the original `DSH_HOME` and profile before using its removal command. This example applies only to an original `headless` installation; replace `headless` with the original profile for any other installation:

~~~shell
dsh plugin --profile headless remove dsh-intent-formation
~~~

Removing a package does not remove operating-system backups or exports copied outside the managed plugin-data directory.

Users of the older Intent Loop v0.2 beta should read the [v0.2 migration note](docs/migration-v0.2.md). This release deliberately does not import old state silently.

## Develop and verify

~~~shell
cd packages/intent-formation
npm ci
npm test

cd ../..
npm ci
npm test
~~~

The core build creates exact, dependency-contained Codex distributions in `plugins/intent-formation` and `plugins/intent-formation-state`. The root suite verifies published study hashes, DeepSeek tool generation, credential isolation, real MCP behavior, and the exact package allowlist.

See [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), and the [release evidence report](docs/verification-report.md).

## License

Apache License 2.0. You may use, modify, and redistribute the project, including commercially, while retaining the required license and notices. The license includes an explicit patent grant. See [LICENSE](LICENSE) and the package-specific third-party notices.