user-habit-pipeline 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+## Unreleased
+
+- Prepared the package for installable distribution by moving default user state to a user data directory with a compatibility fallback for older repo-local overlays.
+- Added runtime path helpers and exported the user-home override constant so installed consumers can resolve or override package-managed state without hardcoded paths.
+- Added a real package-install smoke test that packs, installs into a temporary consumer, validates installed bin shims, and verifies installed library imports before publish.
+- Added a `prepublishOnly` gate so `npm publish` runs the full release check first.
+
+## 0.4.0 - 2026-04-05
+
+- Added a formal Codex current-session contract document covering transcript input, bridge response fields, host responsibilities, and bridge error boundaries.
+- Added realistic Codex session transcript fixtures and regression coverage for noisy current-thread scans through both the suggestion backend and the Codex bridge CLI.
+- Added a formal confidence-scoring document that separates interpreter confidence from session-suggestion confidence and records the current runtime thresholds and bonuses.
+- Added a formal project-principles document that captures the current interpretation-layer boundary, explicit-confirmation model, and the rule that install/config paths must stay configurable rather than hardcoded.
+- Added persistent suggestion suppression so users can ignore a candidate with `忽略第1条`, `--ignore-candidate c1`, or suppress a noisy phrase with `以后别再建议这个短句`.
+- Added `ignored_suggestions` to the user registry state so noisy phrases stay excluded from future suggestion scans without becoming active habits.
+- Added a Codex-facing session bridge CLI so in-app skills can pass the current conversation transcript through `--thread-stdin` and reuse the existing prompt-based management flow.
+- Added documentation for the installed Codex skill entry path and the current-session one-sentence flow inside the Codex app.
+- Cached the latest session suggestion snapshot locally so follow-up apply actions can use `添加第1条` or `--apply-candidate c1` without an explicit suggestions file path.
+- Added apply-time overrides for suggestion candidates so users can confirm with messages such as `把第1条加到 session_close 场景`, or provide `intent` when applying a review-only candidate.
+- Added explicit suggestion-apply support so reviewed session candidates can be written into the user overlay through `--apply-candidate` or prompt requests such as `添加第1条`.
+- Added read-only session habit suggestion scanning from transcript text, including prompt-triggered `suggest` requests through the manage-habits CLI.
+- Added transcript parsing and candidate extraction for explicit add requests, explicit phrase definitions, and repeated short phrases that are not already registered.
+- Added documentation for the Codex-oriented transcript-scan backend and clarified that the remaining app boundary is transcript injection from visible conversation context.
+- Added `--request-stdin` to the habit management CLI so multiline prompt requests work reliably in PowerShell and other shell setups that do not preserve multiline `--request` arguments through `npm run`.
+- Documented the PowerShell here-string testing flow and added regression coverage for stdin-based prompt requests.
+
+## 0.3.0 - 2026-04-01
+
+- Added user overlay import/export support for persistent habit phrase customizations.
+- Added `replace` and `merge` import modes for user registry state management.
+- Expanded lightweight prompt parsing to better handle Chinese management phrasing and multiline add requests.
+- Added CLI coverage and regression tests for import/export and more tolerant prompt parsing.
+
+## 0.2.0 - 2026-04-01
+
+- Added a persistent user-habits overlay on top of the default registry.
+- Added support for user-managed habit phrase add/remove/list operations.
+- Added a lightweight prompt parser so users can manage habits with simple natural-language requests.
+- Added a dedicated `manage-user-habits` CLI and `--user-registry` support on the main interpreter CLI.
+- Added regression tests and documentation for user-managed habit phrases.
+
+## 0.1.0 - 2026-04-01
+
+- Added a minimal habit interpreter with explicit phrase matching, scoring, and clarification rules.
+- Added a `growth-hub` adapter that projects interpretation results into downstream hint fields.
+- Added CLI entrypoints for interpretation and registry validation.
+- Added runtime registry validation plus a formal JSON Schema artifact.
+- Added fixture-driven examples and generated example documentation from a single source.
+- Added workspace editor integration for registry schema hints in VS Code.
+- Added API/reference, versioning, and release-check documentation plus a higher-level `release-check` script.

package/README.md

@@ -0,0 +1,499 @@
+# User Habit Pipeline
+
+A reusable user-habit interpretation layer that turns repeated shorthand expressions into structured, reviewable intent hints for downstream workflows.
+
+---
+
+## 1. Purpose
+
+This project exists to reduce repeated interpretation cost for stable, high-frequency user expressions.
+
+It is designed for cases where a user repeatedly uses short prompts such as:
+
+- `继续`
+- `下一条`
+- `入板`
+- `更新入板`
+- `验收`
+- `session-close`
+- `收口`
+
+Without a habit layer, downstream systems repeatedly spend effort re-inferring the same meaning.
+This project aims to make that interpretation cheaper, more stable, and easier to review.
+When a proposed next step becomes obviously low-return relative to the user's effort, the preferred behavior is to say so early and offer an easy stop/skip path rather than dragging the user through low-value follow-up work.
+
+---
+
+## 2. Product Position
+
+This project is an **interpretation layer**.
+
+It does:
+
+- interpret repeated shorthand expressions
+- normalize likely user intent
+- return structured hints
+- help downstream workflows reduce ambiguity
+
+It does **not**:
+
+- decide workflow actions
+- write files
+- update boards
+- approve tasks
+- switch roles
+- replace explicit workflow rules
+
+Core rule:
+
+- this project explains
+- downstream workflows decide
+
+---
+
+## 3. MVP Goal
+
+The MVP should prove one thing:
+
+> A small, explicit, inspectable habit layer can reduce misunderstanding of repeated user shorthand without taking over workflow decisions.
+
+The MVP does **not** need to support broad coverage.
+The MVP does **not** need to learn automatically.
+The MVP does **not** need to be smart in a general sense.
+
+It only needs to be useful, stable, and easy to inspect.
+
+---
+
+## 4. Hard Scope Boundary
+
+The MVP must remain inside this boundary:
+
+### In scope
+
+- interpret current user message
+- use limited recent context when needed
+- map repeated phrases to normalized intent hints
+- return explicit, inspectable structured output
+- recommend clarification when confidence is low
+
+### Out of scope
+
+Anything that directly changes workflow state, files, approvals, or role behavior is out of scope for MVP.
+
+Specifically, MVP must not:
+
+- write status boards
+- update files
+- trigger execution
+- choose reviewer vs executor behavior
+- replace handoff or other explicit source-of-truth documents
+- infer personality, emotion, hidden motives, or psychological traits
+- require full-thread replay to work
+- become a hidden rule engine
+
+---
+
+## 5. Input Contract
+
+### Required input
+
+- `message: string`
+
+### Optional input
+
+- `recent_context: string[]`
+- `scenario: string | null`
+
+### Input guidance
+
+- `message` is the main interpretation target
+- `recent_context` should stay short
+- `scenario` is only a bias hint, not a hard rule
+
+Suggested `scenario` examples:
+
+- `reviewer`
+- `executor`
+- `status_board`
+- `session_close`
+- `general`
+
+---
+
+## 6. Output Contract
+
+The MVP must return a structured object with stable fields.
+
+### Required fields
+
+- `normalized_intent`
+- `habit_matches`
+- `disambiguation_hints`
+- `confidence`
+- `should_ask_clarifying_question`
+
+### Optional fields
+
+- `preferred_terms`
+- `notes`
+
+### Field contract
+
+#### `normalized_intent`
+- type: `string`
+- required
+- may be `unknown`
+- should stay generic enough to reuse across projects
+
+Examples:
+- `continue_current_track`
+- `move_to_next_item`
+- `add_or_update_board_item`
+- `review_acceptance`
+- `refresh_latest_board_state`
+- `close_session`
+- `draft_text_artifact`
+- `unknown`
+
+#### `habit_matches`
+- type: `array`
+- required
+- each item should describe one matched phrase or rule
+
+Each match item should contain:
+- `phrase: string`
+- `meaning: string`
+- `confidence: number`
+
+#### `disambiguation_hints`
+- type: `array[string]`
+- required
+- empty array allowed
+
+#### `confidence`
+- type: `number`
+- required
+- range: `0.0` to `1.0`
+
+#### `should_ask_clarifying_question`
+- type: `boolean`
+- required
+
+#### `preferred_terms`
+- type: `array[string]`
+- optional
+
+#### `notes`
+- type: `array[string]`
+- optional
+
+### Output example
+
+```json
+{
+  "normalized_intent": "add_or_update_board_item",
+  "habit_matches": [
+    {
+      "phrase": "帮我入板",
+      "meaning": "add_or_update_board_item",
+      "confidence": 0.94
+    }
+  ],
+  "disambiguation_hints": [
+    "Prefer board action over general planning."
+  ],
+  "confidence": 0.94,
+  "should_ask_clarifying_question": false,
+  "preferred_terms": [
+    "status_board"
+  ],
+  "notes": [
+    "High-confidence shorthand mapping."
+  ]
+}
+```
+
+---
+
+## 7. Usage
+
+### Install As A Package
+
+If you want to consume this project from another local environment without treating the repository itself as the runtime home, use the packed tarball:
+
+```powershell
+npm pack
+npm install .\user-habit-pipeline-<version>.tgz
+```
+
+After installation, prefer the installed bin commands instead of `npm run` wrappers:
+
+```powershell
+user-habit-pipeline --message "继续" --scenario general
+manage-user-habits --list
+codex-session-habits --request "列出用户习惯短句"
+```
+
+Runtime user state is stored in a user data directory by default, not in the installed package directory.
+On existing repository-based setups, the runtime keeps using the legacy repo-local overlay file if that file already exists.
+Repository releases also validate a real tarball install path through `npm run package-install-smoke`, so packaged bin commands and runtime-path behavior are checked before publish.
+
+### Library
+
+```js
+const { interpretHabit, toGrowthHubHint } = require("./src");
+
+const interpreted = interpretHabit({
+  message: "继续",
+  scenario: "general",
+  recent_context: ["继续当前评审", "review the next issue after this"]
+});
+
+const growthHubHint = toGrowthHubHint(interpreted);
+```
+
+Use a different registry without changing the interpreter:
+
+```js
+const { interpretHabit, loadHabitsFromFile } = require("./src");
+
+const altRules = loadHabitsFromFile("./tests/fixtures/alt_habits.json");
+
+const interpreted = interpretHabit(
+  { message: "归档一下", scenario: "session_close" },
+  { rules: altRules }
+);
+```
+
+### CLI
+
+Run the interpreter directly:
+
+```powershell
+npm run interpret -- --message "更新入板" --scenario status_board
+```
+
+Show CLI help:
+
+```powershell
+npm run interpret -- --help
+```
+
+Provide recent context by repeating `--context`:
+
+```powershell
+npm run interpret -- --message "继续" --scenario general --context "继续当前评审" --context "review the next issue after this"
+```
+
+Use a custom registry file:
+
+```powershell
+npm run interpret -- --message "归档一下" --scenario session_close --registry .\tests\fixtures\alt_habits.json
+```
+
+Use a custom user-habits overlay file:
+
+```powershell
+npm run interpret -- --message "收尾一下" --scenario session_close --user-registry .\data\user_habits.json
+```
+
+Validate a registry file before using it:
+
+```powershell
+npm run validate-registry -- .\tests\fixtures\alt_habits.json
+```
+
+Show validator help:
+
+```powershell
+npm run validate-registry -- --help
+```
+
+The registry format is also described by a JSON Schema artifact:
+
+- [registry.schema.json](/E:/user-habit-pipeline/docs/registry.schema.json)
+- [editor-integration.md](/E:/user-habit-pipeline/docs/editor-integration.md)
+- [api-reference.md](/E:/user-habit-pipeline/docs/api-reference.md)
+- [confidence-scoring.md](/E:/user-habit-pipeline/docs/confidence-scoring.md)
+- [project-principles.md](/E:/user-habit-pipeline/docs/project-principles.md)
+- [versioning.md](/E:/user-habit-pipeline/docs/versioning.md)
+- [release-checklist.md](/E:/user-habit-pipeline/docs/release-checklist.md)
+- [cross-repo-release-runbook.md](/E:/user-habit-pipeline/docs/cross-repo-release-runbook.md)
+- [manual-e2e-acceptance.md](/E:/user-habit-pipeline/docs/manual-e2e-acceptance.md)
+- [release-notes-v0.4.0.md](/E:/user-habit-pipeline/docs/release-notes-v0.4.0.md)
+- [session-habit-suggestions.md](/E:/user-habit-pipeline/docs/session-habit-suggestions.md)
+- [codex-current-session-contract.md](/E:/user-habit-pipeline/docs/codex-current-session-contract.md)
+- [codex-skill-integration.md](/E:/user-habit-pipeline/docs/codex-skill-integration.md)
+- [freeze-assessment-0.1.0.md](/E:/user-habit-pipeline/docs/freeze-assessment-0.1.0.md)
+- [user-habit-management.md](/E:/user-habit-pipeline/docs/user-habit-management.md)
+
+Regenerate the examples document after changing the example fixtures:
+
+```powershell
+npm run generate-examples-doc
+```
+
+Run the bundled end-to-end smoke script:
+
+```powershell
+npm run manual-e2e-smoke
+```
+
+Run a quick end-to-end demo of the current package scope:
+
+```powershell
+npm run demo
+```
+
+Project the output through the `growth-hub` adapter:
+
+```powershell
+npm run interpret -- --message "验收" --scenario reviewer --adapter growth-hub
+```
+
+### User-Managed Habit Phrases
+
+Add a user habit with structured flags:
+
+```powershell
+npm run manage-habits -- --add --phrase "收尾一下" --intent close_session --scenario session_close --confidence 0.86
+```
+
+Remove a phrase from the effective registry:
+
+```powershell
+npm run manage-habits -- --remove --phrase "验收"
+```
+
+Suppress a noisy suggestion phrase without making it an active habit:
+
+```powershell
+npm run manage-habits -- --ignore-phrase "收工啦"
+```
+
+List the current user-defined additions and removals:
+
+```powershell
+npm run manage-habits -- --list
+```
+
+Export your current user overlay:
+
+```powershell
+npm run manage-habits -- --export .\backup\user_habits.json
+```
+
+Import a saved overlay:
+
+```powershell
+npm run manage-habits -- --import .\backup\user_habits.json
+npm run manage-habits -- --import .\backup\user_habits.json --mode merge
+```
+
+Use a lightweight prompt-like request instead of flags:
+
+```powershell
+npm run manage-habits -- --request "添加用户习惯短句: phrase=收尾一下; intent=close_session; 场景=session_close; 置信度=0.86"
+npm run manage-habits -- --request "删除用户习惯短句: 收尾一下"
+npm run manage-habits -- --request "以后别再建议这个短句: 收工啦"
+npm run manage-habits -- --request "列出用户习惯短句"
+npm run manage-habits -- --request "导出用户习惯短句: path=.\backup\user_habits.json"
+npm run manage-habits -- --request "导入习惯短句 路径=.\backup\user_habits.json; 模式=merge"
+```
+
+For multiline prompt requests in PowerShell, prefer piping a here-string into `--request-stdin`:
+
+```powershell
+@'
+新增习惯短句 phrase=收尾一下
+intent=close_session
+场景=session_close
+置信度=0.86
+'@ | npm run manage-habits -- --request-stdin
+```
+
+This writes user-managed phrases into a separate overlay file and leaves the default registry untouched.
+
+### Session Habit Suggestions
+
+Scan a current-thread transcript for habit candidates without writing anything to the overlay:
+
+```powershell
+npm run manage-habits -- --suggest --transcript .\data\thread.txt
+```
+
+You can also trigger the same scan through a natural-language request:
+
+```powershell
+npm run manage-habits -- --request "扫描这次会话里的习惯候选" --transcript .\data\thread.txt
+```
+
+For PowerShell here-string input:
+
+```powershell
+@'
+user: 以后我说“收尾一下”就是 close_session
+assistant: 收到。
+user: 收尾一下
+'@ | npm run manage-habits -- --suggest --transcript-stdin
+```
+
+For Codex-side in-app triggering, use the session bridge CLI so the current conversation can be piped in directly:
+
+```powershell
+@'
+user: 以后我说“收尾一下”就是 close_session
+assistant: 收到。
+user: 收尾一下
+'@ | npm run codex-session-habits -- --request "扫描这次会话里的习惯候选" --thread-stdin
+```
+
+The current host/skill integration boundary is documented separately in:
+
+- [codex-current-session-contract.md](/E:/user-habit-pipeline/docs/codex-current-session-contract.md)
+
+This suggestion flow is intentionally read-only.
+It returns candidate phrases and evidence, but it does not automatically add them to the user overlay.
+It also saves the latest suggestion snapshot into a local hidden cache so the next apply step does not need a manual file path.
+Each returned candidate now also includes `confidence_details`, so a Codex skill or other host can explain why that score was assigned instead of only showing a bare number.
+
+After reviewing the candidates, you can explicitly add one:
+
+```powershell
+npm run manage-habits -- --apply-candidate c1
+```
+
+Prompt-style confirmation is also supported:
+
+```powershell
+npm run manage-habits -- --request "添加第1条"
+npm run manage-habits -- --request "把第1条加到 session_close 场景"
+npm run manage-habits -- --request "忽略第1条"
+npm run codex-session-habits -- --request "添加第1条"
+npm run codex-session-habits -- --request "把第1条加到 session_close 场景"
+```
+
+If a candidate is review-only, you can still apply it by supplying an explicit intent:
+
+```powershell
+npm run manage-habits -- --apply-candidate c1 --intent close_session --scenario session_close
+```
+
+If a candidate is noisy and should not be suggested again, suppress it instead of adding it:
+
+```powershell
+npm run manage-habits -- --ignore-candidate c1
+npm run manage-habits -- --request "忽略第1条"
+```
+
+### CLI contract
+
+- `--message` is required
+- `--scenario` is optional
+- repeat `--context` to supply short recent-context items
+- `--adapter growth-hub` projects the interpretation into downstream hint fields
+- `--registry <path>` loads a different habit registry file for this invocation
+- `--user-registry <path>` loads a user-habits overlay file for this invocation
+
+The CLI prints JSON only.

package/data/.gitkeep

@@ -0,0 +1 @@
+