howhard 2.0.0__tar.gz

howhard-2.0.0/.agents/plugins/marketplace.json

@@ -0,0 +1,11 @@
+{
+  "name": "howhard",
+  "plugins": [
+    {
+      "name": "howhard",
+      "source": {"source": "local", "path": "./"},
+      "policy": {"installation": "AVAILABLE", "authentication": "ON_INSTALL"},
+      "category": "Productivity"
+    }
+  ]
+}

howhard-2.0.0/.antigravity-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://antigravity.google/schemas/v1/plugin.json",
+  "name": "howhard",
+  "displayName": "howhard",
+  "version": "2.0.0",
+  "description": "Recommend model and reasoning effort from task context, then learn from actual feedback through writable semantic memory.",
+  "author": {"name": "howhard contributors"},
+  "repository": "https://github.com/xu-hao/howhard"
+}

howhard-2.0.0/.claude-plugin/marketplace.json

@@ -0,0 +1,12 @@
+{
+  "name": "howhard",
+  "description": "The howhard skill for task-aware model and effort recommendations with feedback and writable memory.",
+  "owner": {"name": "howhard contributors"},
+  "plugins": [
+    {
+      "name": "howhard",
+      "source": "./",
+      "description": "Task-aware model and effort recommendations with feedback and writable memory."
+    }
+  ]
+}

howhard-2.0.0/.claude-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "howhard",
+  "version": "2.0.0",
+  "description": "Recommend model and reasoning effort from task context, then learn from actual feedback through writable semantic memory.",
+  "author": {"name": "howhard contributors"},
+  "repository": "https://github.com/xu-hao/howhard"
+}

howhard-2.0.0/.readthedocs.yaml

@@ -0,0 +1,13 @@
+version: 2
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: true
+python:
+  install:
+    - requirements: docs/requirements.txt
+    - method: pip
+      path: .

howhard-2.0.0/AGENTS.md

@@ -0,0 +1,39 @@
+# howhard contributor instructions
+
+Keep this file limited to repository-wide guardrails. Follow the canonical contracts and
+procedures listed in [docs/index.md](docs/index.md). These guardrails adopt AGCoord's
+contributor workflow for this repository.
+
+- Track every code, test, documentation, or packaging change with a descriptive issue.
+  Pair every issue number with a sentence explaining the work it tracks. Do not file an
+  issue solely for machine-local installation, deployment, configuration, service
+  lifecycle, or other operator state; create one only when that work also requires a
+  repository change or the user explicitly requests an issue.
+- Develop and validate only in an issue-specific Git worktree branched from `main`.
+  Preserve unrelated work and do not develop in the primary checkout.
+- Verify behavior at public boundaries. Start bug fixes with a failing behavioral test;
+  accompany runtime changes with focused tests, affected canonical documentation, and a
+  `CHANGELOG.md` entry when the change is user-facing.
+- A documentation-only change needs no tests or AGCoord gate. It qualifies only when every
+  changed path is `README.md`, `CHANGELOG.md`, `AGENTS.md`, Markdown below `docs/`, or a
+  `.png` or `.svg` image below `docs/assets/` whose provenance is recorded in
+  `docs/assets/README.md`. Verify the exact pull-request file list and diff, then merge it
+  through the forge; the issue, worktree, branch, pull-request, and no-direct-target-push
+  rules still apply.
+- Tests own and stop every process, repository, and temporary state they create.
+  Never inspect or clean another agent's state.
+- Keep the package independent of a parent application or sibling checkout.
+  Put project-specific assumptions in optional configuration; the ordinary workflow
+  must work without configuration or statistical parameter tuning.
+- For every other change after bootstrap, route checks and publication through the local
+  coordinator, declare every scarce resource, and never submit coordinated work from an
+  admitted job. Gate and publish through one `agc land` request; never bypass or separate
+  its verdict from publication.
+- Never upload a howhard distribution to PyPI unless the user explicitly requests it.
+  Permission to implement, test, commit, push, merge, tag, or create a GitHub release
+  does not authorize an upload.
+- End changed work with the four-part [session handoff](docs/session_handoff_format.md);
+  answer read-only questions directly without an empty handoff shell.
+- Follow the [contributor workflow](docs/contributing.md) for commands, bootstrap,
+  recovery, and cleanup. The [model and storage contracts](docs/reference.md) and
+  [release guide](docs/releasing.md) define the corresponding component contracts.

howhard-2.0.0/CHANGELOG.md

@@ -0,0 +1,219 @@
+# Changelog
+
+## Unreleased
+
+## 2.0.0 — 2026-11-07
+
+This source version prepares the 2.0.0 release. Until the corresponding GitHub release
+is published, it remains a release candidate. A GitHub tag, release and attached
+distributions are separate from PyPI publication; this entry asserts neither.
+
+- Add portable, bounded, offline usage collection for explicitly owned Codex exec/session
+  and Claude SDK/session artifacts. Append usage to an existing execution through
+  idempotent measurement amendments; preserve the original outcome on collection failure.
+- Normalize nonoverlapping token categories, retain unknown coverage and provenance,
+  refuse duplicate source claims including exact native parent-session/agent mappings, and keep client cost estimates separate from billed
+  charges and historical costs with an unspecified basis. Keep task outcome, token
+  coverage, bounded client estimates and authoritative billing independently recorded.
+- Accept explicit category rate cards and prospective token-category forecasts. Omit
+  worker money uniformly for unknown or mixed price bases; never infer host charges.
+- Require decision v5, agent request v4 and semantic state v3. Older receipts cannot
+  be replayed, while historical raw observations remain retained. Synchronize backend
+  and native plugin versions at 2.0.0; see the [upgrade guide](https://github.com/xu-hao/howhard/blob/main/docs/upgrading-2.0.md).
+- Extend the host skill with owned artifact capture, rate-card provenance, honest
+  partial usage, attachment retries and explicit child-session binding limits.
+
+## 1.0.0 — 2026-10-31
+
+### Compatibility
+
+This is a breaking release of the LLM-only routing workflow, not a compatible patch
+to the 0.6 maintenance series. See the
+[upgrade guide](https://github.com/xu-hao/howhard/blob/v1.0.0/docs/upgrading-1.0.md).
+
+- Remove statistical routing, its CLI/API/configuration surfaces and generic prior
+  transfer. Native routing requires explicit host model/effort candidates and an
+  independent LLM forecast; unavailable inference stops selection.
+- Require `howhard-decision-v4`, `howhard-agent-request-v3` and
+  `howhard-semantic-v2`. Older requests and receipts cannot be reused; no automatic
+  state migration or deletion occurs. Preserve historical evidence and reprepare
+  current requests; unsupported persisted inputs are refused explicitly.
+- Local retrieval adds FastEmbed, ONNX Runtime and USearch dependencies and lazily
+  downloads pinned models for larger searches. Qwen remains an optional extra.
+- Synchronize Python and all native plugin manifests at 1.0.0. Upgrade the backend
+  and installed skills separately; old GitHub releases remain available.
+
+### Changes
+
+- Add the portable `attribute-failure` skill for bug-fixing agents to investigate
+  escaped defects through reproductions, Git history/blame and optional bisection,
+  connect supported findings to original executions, and amend outcomes with explicit
+  memory learning. Retain commit/PR provenance in existing artifacts and observation
+  notes; uncertain attribution remains unscored. Native plugins discover both skills.
+
+- Fix a native-runtime import-order crash in hybrid retrieval by initializing ONNX
+  Runtime before USearch at the lazy dense-search boundary. Fresh and cached HNSW
+  searches work without caller pre-imports; small corpora still load neither runtime.
+
+- Add optional fixed `[retrieval]` settings for the fast ONNX or Qwen reranker,
+  pinned model/artifact overrides and runtime controls. Apply the policy to routing,
+  memory and evidence search; reject invalid combinations before creating state.
+  Agent retrieval tools cannot change the tier, model or configuration, and no
+  automatic upgrade/fallback is introduced. Policy changes invalidate pending requests.
+
+- Use a pinned MiniLM-L4 INT8 ONNX cross-encoder as the default CPU reranker. A
+  two-thread check of 200 pairs took 0.32–0.41 seconds for short inputs and 8.34–8.55
+  seconds for full 512-token windows. Keep the 200-to-eight pipeline and calling-agent
+  forecasts; retain instruction-aware Qwen through the optional `qwen` install extra.
+  The compact default has a 512-token combined window and no instruction tuning.
+
+- Retrieve transferable execution experience with local BM25 and HNSW, RRF fusion
+  to 200 candidates and pretrained instruction-aware Qwen3-Reranker-0.6B selection
+  of up to eight precedents. Keep observed model/effort/outcome/cost attached, include
+  relevant failures and broader/narrower tasks, and retain the calling agent for final
+  forecasts. Make every retrieval/reranking stage independently replaceable in Python.
+- Expose observed runs as read-only memory experts with prospective predictive credit.
+  Normalize decision support over participating experts so unrelated history cannot
+  dilute retrieved experience. Rebuild derived indexes on edits/amendments without
+  changing canonical evidence. Larger searches lazily download local pretrained models.
+
+- Add an opt-in pytest-probability diagnostic benchmark comparing whole-rule versus
+  applicability-condition embeddings, with and without cross-encoder reranking.
+  Forty authored tasks cover paraphrases, misleading action words, exceptions,
+  missing prerequisites and conjunctions. Retain labels separately, report candidate
+  recall/ranking metrics and latency, and keep real-model runs outside the ordinary gate.
+
+- Remove statistical-only routing, the internal statistical expert/risk floor, lexical
+  features, outcome/resource fitting, posterior caches and generic prior transfer.
+  Routing now requires independent LLM forecasts and semantic memory; missing or failed
+  inference stops explicitly. Remove `--llm`, `HOWHARD_LLM`, `--cache`, prior commands,
+  statistical Python APIs and configuration. State/protocol commands require no provider.
+- Use LLM-reference predictive memory weights and a labeled weighted forecast envelope
+  for risk checks. New receipts/requests use v4/v3 and semantic state v2; old artifacts
+  remain untouched and old forecasts are unscored. Fresh-engine observations leave
+  writer work pending for explicit provider/calling-agent learning.
+
+- Clarify portable skill feedback attribution when native host APIs accept explicit
+  model/effort overrides: completed execution can match the requested decision receipt
+  without provider attestation; known mismatches use raw feedback and unknown cells
+  remain unscored.
+- Allow append-only measured-usage corrections with a validated amendment-only
+  `measurement_corrections` map and CLI JSON input. Explicit replacements or null clears
+  update effective regressions, worker costs and learning once while preserving raw history.
+- Document a copyable coordinating-agent instruction requiring howhard before authorized
+  worker delegation, with actual feedback, an independent-baseline recursion exception
+  and an explicit distinction between agent instructions and host enforcement.
+- Remove registry-only routing and the Python family/effort candidate filter. Every
+  routing request now requires the host's native inventory; prices come only from that
+  inventory. Remove packaged API prices, token mixes, family activation flags and
+  unresolved default-effort handling.
+- Remove checkout-local Git store discovery and old SQLite adoption inspection. Git
+  worktrees use the common Git directory's store; explicit configuration/store selection
+  and plain-folder state remain supported. Existing checkout data is left untouched.
+- Require timestamped contextual original records, identity/inventory/cost-bound v3
+  decision receipts and worktree-bound v2 agent requests. Only contextual v2 priors are
+  imported/exported, including empty-store exports. Superseded records, receipts,
+  requests and priors are refused rather than upgraded or read through compatibility paths.
+- Explain automatic task-based Codex skill activation and optional explicit invocation.
+  The coordinating agent selects a worker before spawning; subagent startup does not
+  itself guarantee skill activation. Remove retired installation guidance.
+
+## 0.6.1 — 2026-10-30
+
+- Allow append-only measured-usage corrections with a validated amendment-only
+  `measurement_corrections` map and `observe --measurement-corrections FILE`. Explicit
+  replacements or null clears update effective regressions, worker costs and learning
+  once while preserving the raw original, context and receipt identity.
+- Preserve existing 0.6 persistence/API behavior. This additive row-semantics expansion
+  leaves existing data readable; older readers refuse rows containing the new field.
+- Link the live Read the Docs site from the README and release guide.
+
+## 0.6.0 — 2026-10-30
+
+- Accept actual native model/control inventories before forecasts, with distinct neutral
+  families for new identities, persistent historical metadata and exact categorical efforts.
+  The portable skill calls native CLI/API primitives without project bridges or tuning.
+- Label unknown worker pricing explicitly and omit worker money uniformly when any native
+  candidate is unpriced; preserve known costs and null unknowns without API-price assumptions.
+- Separate current project capture from durable state, share fresh Git worktree state,
+  retain valid legacy/explicit stores and refuse cross-project store reuse. Expose paths
+  and intentional state selection; preserve identity on project moves, exclude resolved
+  state from source capture/retrieval, and bind prepared requests to their originating worktree.
+- Add direct evidence lookup, matching stable-ID feedback retries and validated raw native
+  execution admission without retrospective forecasts. Include all correction notes in
+  writer context while retaining amendment scoring and learning-event idempotence.
+- Existing logs, receipts and prior formats remain readable. Native metadata/efforts and
+  new receipts with project identity/native cost-policy fields require 0.6.0 or later;
+  old unbound pending requests must be prepared again. No old state is migrated
+  or deleted automatically, and generic prior exports exclude native identity-specific terms.
+
+## 0.5.0 — 2026-10-30
+
+- Move the canonical skill to standard `skills/howhard` discovery, with thin portable,
+  Codex marketplace, Claude Code and Antigravity manifests for first-party installation.
+- Retire the bespoke 0.4 `howhard skills install` command and `howhard.skill_install`
+  API before 1.0. The source distribution retains the skill; the Python wheel supplies
+  the backend without another skill copy. Preserve edited old copies before migration.
+- Complete the existing Quickstart with source backend installation, native plugin
+  setup/invocation, backend executable visibility, actual feedback and memory learning.
+- Add explicit native validation and an optional third-party `skills` CLI smoke;
+  keep native installations and npm downloads out of the ordinary Python gate.
+
+## 0.4.0 — 2026-10-30
+
+- Package one reusable howhard skill with progressive references for actual task/context
+  reasoning, host-compatible delegation, outcome corrections and writable memory.
+- Add offline `skills install` for Codex, Claude Code and Antigravity, with explicit
+  project/user scopes, deduplicated discovery paths, identical-install reuse and
+  preflight conflict refusal. Installation leaves model/provider settings unchanged.
+- Document source and pinned Git installation, host capability gaps and optional
+  project adapters; verify skill installation from a clean wheel.
+
+## 0.3.1 — 2026-10-30
+
+- Allow append-only outcome amendments to clean, loud or silent, retaining the original
+  run's context and measurements and replacing Bayesian and semantic evidence once.
+  Row keys and cache/prior formats are unchanged; earlier versions cannot read clean
+  or loud amendments.
+- Give every correction its own idempotent memory-learning event, including corrections
+  back to an earlier result, and reject writer responses prepared before a correction.
+
+## 0.3.0 — 2026-10-30
+
+- Add LLM reasoning over original task/project text, persistent semantic memory and
+  bounded evidence retrieval, with an isolated stateless forecast baseline.
+- Support add, edit, remove, restore, merge and split memory operations through the
+  CLI, Python API and LLM writer, with transactional edits and preserved history.
+- Update approximate predictive weights from actual selected-action forecasts and
+  effective outcomes, including resource evidence, amendments and fresh edit versions.
+- Reuse an authenticated Claude CLI with tools disabled, accept custom adapters and
+  expose a calling-agent protocol. Explicit LLM errors remain explicit; automatic
+  statistical fallback is labeled.
+- Preserve semantic forecasts and memory versions in receipts, audit inference and
+  writer usage, and report observed-action forecast metrics and unknown costs honestly.
+- Add a real-project evaluation protocol. Keep correctness fixtures separate from
+  routing-quality evidence; defer Read the Docs publishing.
+
+## 0.2.0 — 2026-10-29
+
+- Condition predictions on task descriptions and project snapshots that are captured
+  afresh for every decision, including working-tree changes and optional measured coverage.
+- Learn shared, family-specific and effort-specific contextual outcome effects, plus
+  contextual token and time effects, using a deterministic local lexical encoder.
+- Save decision receipts so later observations keep the original task and project
+  context. Add task-text/file inputs and `observe DECISION_ID OUTCOME` to the CLI.
+- Preserve missing context in legacy rows, retain original context on amendments,
+  and version caches and prior transfers without exporting raw text or snapshots.
+- Marginalize inactive coefficients exactly to keep fitting practical on small logs.
+
+## 0.1.0 — 2026-10-29
+
+- Start without configuration: packaged registry, prices, risk policies and priors,
+  automatic local learning, and a standard policy for new task names.
+- Choose model and effort with Bayesian clean/loud/silent outcomes, exact log-normal
+  cost/time regressions, Thompson sampling, a silent-failure cap and explanations.
+- Record outcomes in a strict append-only journal, amend escaped failures and flush
+  into the outcome log. Cache posteriors and refit from all evidence with warm starts.
+- Transfer shared learning between projects without exporting run records or project effects.
+- Add the Python API, six CLI commands, acceptance tests, wheel checks, canonical
+  documentation, contributor guardrails and release versioning.

howhard-2.0.0/MANIFEST.in

@@ -0,0 +1,12 @@
+include AGENTS.md CHANGELOG.md
+include .readthedocs.yaml
+include plugin.json
+include .agents/plugins/marketplace.json
+include .claude-plugin/plugin.json .claude-plugin/marketplace.json
+include .antigravity-plugin/plugin.json
+recursive-include docs *.md *.py *.txt
+recursive-exclude docs/_build *
+recursive-include scripts *
+recursive-include skills *.md
+recursive-include tests *.py
+recursive-include benchmarks *.py *.json

howhard-2.0.0/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: howhard
+Version: 2.0.0
+Summary: Choose an agent's model and reasoning effort, and learn from outcomes.
+Project-URL: Repository, https://github.com/xu-hao/howhard
+Project-URL: Issues, https://github.com/xu-hao/howhard/issues
+Project-URL: Changelog, https://github.com/xu-hao/howhard/blob/main/CHANGELOG.md
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.24
+Requires-Dist: fastembed==0.9.1
+Requires-Dist: usearch<3,>=2.21
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: build; extra == "test"
+Requires-Dist: pytest-probability==0.3.0; extra == "test"
+Provides-Extra: docs
+Requires-Dist: sphinx>=8; extra == "docs"
+Requires-Dist: myst-parser>=4; extra == "docs"
+Requires-Dist: furo; extra == "docs"
+Provides-Extra: bench
+Requires-Dist: pytest-probability==0.3.0; extra == "bench"
+Requires-Dist: fastembed==0.9.1; extra == "bench"
+Provides-Extra: qwen
+Requires-Dist: sentence-transformers<7,>=5.4; extra == "qwen"
+
+# howhard
+
+*How hard should the agent think?*
+
+[Read the documentation](https://howhard.readthedocs.io/en/latest/).
+
+`howhard` chooses the model and reasoning effort for a task delegated to an AI
+agent. An LLM reads the actual task, current project and writable semantic memory,
+forecasting clean completion, caught failures, escaped failures, tokens and time for
+each candidate. Recorded outcomes update the predictive support for memories.
+
+Selection balances worker cost, expected failure cost and waiting time. Its risk cap
+uses a weighted envelope of LLM forecasts; these estimates are not a calibrated
+failure guarantee. Without a usable LLM forecast, routing fails explicitly. There is
+no statistical prediction model or statistical fallback.
+
+## Quickstart
+
+You need Python 3.11+, Git and a current Codex, Claude Code or Antigravity client
+with native plugin support. No parameter tuning or Node/npm setup is
+required by howhard. Once the `v2.0.0` GitHub tag is published, install the Python
+backend from that tagged source in your project directory. Before publication, use
+the verified local-checkout alternative below.
+
+```sh
+python3 -m venv .venv-howhard
+. .venv-howhard/bin/activate
+python -m pip install "git+https://github.com/xu-hao/howhard.git@v2.0.0"
+howhard --version
+```
+
+Expect `howhard 2.0.0`. Read the [2.0 upgrade guide](docs/upgrading-2.0.md) when moving
+from 1.0; upgrades from 0.6.x also need the [1.0 compatibility changes](docs/upgrading-1.0.md).
+This command installs from GitHub source and does not require a PyPI release.
+Keep this environment active and start your coding agent from the same shell so
+it can find `howhard`. Install the skill through **your agent's native plugin manager**;
+choose the matching block below.
+An existing GUI session may need the absolute path to `.venv-howhard/bin/howhard`
+in your project; reopening a GUI alone does not activate this terminal's environment.
+
+Version 2.0.0 adds portable execution accounting and category rate cards. Before the
+tag is published, install from a verified local checkout with
+`python -m pip install /path/to/howhard` and check for `howhard 2.0.0`. Load the native
+plugin from that same checkout: substitute its path for the repository source in the
+commands below. A source version or changelog entry does not assert publication.
+GitHub release assets and their checksums are separate from PyPI publication.
+See the [accounting contract](docs/reference.md#portable-execution-accounting)
+for `usage collect`, `usage attach` and `observe --execution-usage` availability.
+
+Codex:
+
+```sh
+codex plugin marketplace add xu-hao/howhard
+codex plugin add howhard@howhard
+```
+
+Claude Code:
+
+```sh
+claude plugin marketplace add xu-hao/howhard
+claude plugin install howhard@howhard
+```
+
+Antigravity (`agy`):
+
+```sh
+agy plugin install https://github.com/xu-hao/howhard
+agy plugin list
+```
+
+These native flows use the user's plugin environment. Claude Code also supports explicit
+`--scope project` or `--scope local` on both marketplace addition and plugin installation.
+Choose the intended scope before running those commands. Reopen the agent if necessary.
+All three load the same skills: `howhard` for routing and learning, and
+`attribute-failure` for investigating escaped defects. They share common Agent Skills
+content with thin host-specific plugin metadata; see [skill installation](docs/skills.md).
+
+In Codex, the installed skill can activate automatically when a task matches its
+model-selection or feedback-learning description. Explicit invocation is optional:
+use `$howhard` or `/skills` in Codex, `/howhard:howhard` in Claude Code, or `/howhard`
+in Antigravity to request it directly. [Codex skill activation](https://learn.chatgpt.com/docs/build-skills)
+is based on the task; starting a subagent alone does not guarantee activation.
+The coordinating agent uses howhard **before** spawning a worker so it can choose that
+worker's model and effort. The plugin supplies instructions, with no subagent-start hook.
+To request the complete workflow explicitly, give it your real task:
+
+> Use howhard for this task: repair transaction rollback and verify its failure
+> boundary. Read the current project context, obtain an independent baseline, consult
+> memory, and recommend a model and effort supported by this host. Execute the authorized
+> work with that cell, then record the actual result and measured usage under a stable
+> execution ID and update memory. Report any unsupported controls or identity mismatch.
+
+For persistent use before worker delegation, copy the
+[coordinating-agent instruction](docs/skills.md#require-howhard-before-delegation)
+into your agent's project instructions (`AGENTS.md` in Codex). The skill guide explains
+the instruction's scope and the host enforcement needed for a hard guarantee.
+
+The skill discovers the host's executable model/control inventory, creates temporary
+protocol inputs, obtains an independent baseline and uses memory-conditioned forecasts.
+It calls the native howhard CLI/API directly. You do not write a project bridge, add a
+dependency-lock feature, maintain a separate ledger, map models to families
+or tune parameters. Unknown native identities get distinct identity labels;
+unsupported or unknown execution controls are reported honestly.
+
+Your host's existing LLM supplies the calling-agent reasoning without another API key.
+An independent baseline needs a fresh context without memory/history; if unavailable,
+the agent reports routing unavailable until an independent LLM forecast is available. Unknown worker
+prices stay unknown. If any candidate is unpriced, every candidate is compared without
+worker money; the partial objective is labeled rather than treating unknown charges as
+free or assuming API list prices apply to the host.
+
+The JSON decision includes `chosen.model`, `chosen.effort`, `decision_id`, `cap_met`,
+`needs_review` and the native `cost_policy`. A recommendation does not execute the task.
+Honor required review. When the native host accepts explicit model and effort overrides
+and the task completes, use the matched decision receipt for the requested cell unless
+the host reports a launch failure, ignored control, substitution or contradictory
+metadata; note that host-API provenance when no resolved identity is returned. Otherwise,
+match only on exact reported actual identity/control, use raw feedback for a known
+mismatch, and leave feedback unscored only when that identity/control is unknown.
+Fresh Git worktrees automatically share repository state while capturing the current
+checkout; plain folders use local `.howhard`, and explicit store selection is available.
+Inspect the resolved roots with:
+
+```sh
+howhard paths --json
+```
+
+Only after execution, replace `DECISION_ID` with the returned receipt ID, `EXECUTION_ID`
+with a stable ID for that actual invocation, and `OUTCOME` with `clean`, `loud` or `silent`:
+
+```sh
+howhard observe DECISION_ID OUTCOME --id EXECUTION_ID --json
+howhard evidence EXECUTION_ID --raw --json
+howhard memory learn-context EXECUTION_ID --json
+howhard memory list --json
+howhard report --json
+```
+
+`clean` means no observed defect; `loud` means a gate/review caught a failure; `silent`
+means a failure escaped and was discovered later. Supply `--tokens`, `--seconds` and
+`--cost-usd` only when measured; unknown usage stays null. Never record an unrun action
+or attach a different executed cell to the selected receipt. A verified different cell
+is recorded as raw native feedback with the original frozen context and provenance; an
+unknown actual identity/control stays unscored when neither accepted overrides nor exact
+reported identity establishes a match. Matching stable-ID retries return the first row,
+while conflicting feedback is refused. The skill uses the returned
+learning context, including the original and correction notes, to revise mutable memory. After the host prepares a temporary `writer-response.json`
+with `operations` and `reason` grounded in that result, apply it using `N` and `EVENT_KEY`
+from `memory learn-context`:
+
+```sh
+howhard memory learn EXECUTION_ID --file writer-response.json --expected-revision N --event-key EVENT_KEY --json
+```
+
+An empty operations list is valid. New lessons receive no retrospective predictive
+credit. Retry learning for the same effective event, and append changed feedback with
+`--amends` instead of creating another original run.
+
+Standalone `pick` can reuse an authenticated Claude CLI or `HOWHARD_LLM_COMMAND`.
+Calling-agent commands need no provider configuration and never start nested inference.
+Observations made without a provider adapter return a pending memory update; use the
+explicit writer workflow above or `memory learn RUN_ID` to invoke a provider. The
+[skill guide](docs/skills.md) covers native lifecycle commands, native feedback/mismatch handling and local/pinned sources.
+A third-party cross-agent `npx skills` route is optional, not a prerequisite.
+Python backend upgrades and skill updates are separate.
+
+See the [quickstart](docs/quickstart.md), [documentation index](docs/index.md),
+[model and storage contracts](docs/reference.md), and [changelog](CHANGELOG.md).
+The [context architecture](docs/context.md) explains original text, changing project
+snapshots and decision receipts. Evaluate routing quality with the
+[real-project protocol](docs/evaluation.md); unit fixtures establish implementation
+behavior rather than product-quality evidence.
+Python 3.11+ and a POSIX platform are required. Run tests with
+`python -m pip install -e '.[test]'` followed by `python -m pytest`;
+contributors use [AGCoord and isolated worktrees](docs/contributing.md).