frontend-harness 0.7.10 → 0.8.1

package/README.md

@@ -1,6 +1,6 @@
 # frontend-harness
 
-`frontend-harness` is an Execution Policy Layer for frontend teams using Codex or Claude Code.
+`frontend-harness` is a context and evidence policy layer for frontend teams using Codex or Claude Code.
 
 It does not replace the agent runtime. Codex and Claude Code already provide the loop, tool execution, context handling, permissions, retries, subagents, and skill loading. `frontend-harness` adds the project-level rules those agents should follow inside a frontend repository.
 
@@ -10,16 +10,18 @@ The product goal is simple:
 install once -> inject AGENTS.md / CLAUDE.md -> work normally with AI
 ```
 
-After initialization, team members should not need to manually run the harness loop. They keep asking Codex or Claude Code for frontend work in plain language. The injected project protocol and built-in project skills tell the agent how to plan, edit, verify, and repair.
+After initialization, team members should not need to manually run a heavy harness workflow for every task. They keep asking Codex or Claude Code for frontend work in plain language. The injected project protocol tells the agent when to use the full context, planning, evidence, and repair loop, and when ordinary task guidance is enough.
 
 ## What It Does
 
-`frontend-harness` gives a project a deterministic execution contract:
+`frontend-harness` gives complex frontend tasks a deterministic execution contract:
 
 ```text
 context -> plan -> implement -> record changes -> verify -> repair -> done
 ```
 
+The full loop is intended for work where source material, evidence, or traceability matters: design-backed UI restoration, PRD-derived product knowledge, multi-source frontend changes, and handoffs that need durable verification artifacts. Simple bug fixes, tests, docs, maintenance, and small requirement edits should stay lightweight unless the task includes explicit PRD, API, UI, or audit evidence.
+
 The CLI exists mainly as a protocol API for AI agents. Humans use it to install, initialize, and occasionally check health.
 
 ## What It Is Not
@@ -35,7 +37,7 @@ It should not rebuild:
 - long-running runtime launchers or supervised agent wrappers
 - replacement workflows for Codex or Claude Code
 
-Those belong to the official agent runtimes. This package owns only the frontend project policy around them.
+Those belong to the official agent runtimes. This package owns only the frontend project context, policy, and evidence around them. It should not wrap ordinary agent conversation in process for its own sake.
 
 ## Install
 
@@ -115,7 +117,7 @@ Once those files are present, the normal team workflow is:
 ```text
 Open Codex or Claude Code.
 Ask for the frontend change.
-Let the injected protocol drive planning, verification, and repair.
+Let the injected protocol decide whether the task needs the full harness loop or lightweight project guidance.
 ```
 
 ## Human Commands
@@ -146,9 +148,10 @@ These commands are intended for Codex / Claude Code through the injected protoco
 
 ```bash
 npm run harness -- context --json
+npm run harness -- context task --json "<task>" --prd <prd-file> --api-source <openapi-file-or-url> --ui-source <ui-artifact-or-design-url>
 npm run harness -- proposal check --json --file <agent-proposal.json>
 npm run harness -- plan --json "<task>"
-npm run harness -- plan --json "<task>" --prd <prd-file> --ui-source <ui-artifact-or-design-url>
+npm run harness -- plan --json "<task>" --prd <prd-file> --api-source <openapi-file-or-url> --ui-source <ui-artifact-or-design-url>
 npm run harness -- plan --json "<task>" --agent-proposal <agent-proposal.json>
 npm run harness -- state record-change <file>
 npm run harness -- state record-change --from-git
@@ -162,7 +165,7 @@ npm run harness -- state next --json
 npm run harness -- state explain --json
 ```
 
-The agent should call them automatically while doing work. They persist local state under `.frontend-harness/` and provide deterministic evidence for each step. `evidence template --json` prints the machine-readable evidence entry shape for the current plan; it is a schema aid, not proof. Put real captures, checks, comparisons, and hashes in a project-local evidence input JSON, then use `evidence record --json --file <evidence-input.json>` so the harness validates and writes `.frontend-harness/verification/evidence.json`. Captured evidence and visual comparison files are local intermediate artifacts by default; scaffolded projects ignore them and `clean` may remove them.
+The agent should call them automatically when the task needs harness-managed context, planning, or evidence. They persist local state under `.frontend-harness/` and provide deterministic evidence for each step. `context task --json` emits a compact task packet from workflow policy, selected knowledge cards, explicit PRD/API/UI inputs, candidate project files, and ingest provenance so agents can use PRD/UI/API context without loading entire source materials into the prompt. `evidence template --json` prints the machine-readable evidence entry shape for the current plan; it is a schema aid, not proof. Put real captures, checks, comparisons, and hashes in a project-local evidence input JSON, then use `evidence record --json --file <evidence-input.json>` so the harness validates and writes `.frontend-harness/verification/evidence.json`. Captured evidence and visual comparison files are local intermediate artifacts by default; scaffolded projects ignore them and `clean` may remove them.
 
 `state check --json` verifies that recorded changed files cover the current plan's execution-unit files before verification. `verify --json` runs that contract check first, enforces PRD knowledge coverage when the plan has PRD input, and then discovers the default `typecheck`, `test`, and `build` scripts when present. Projects can also declare custom verification commands in `.frontend-harness/config.json`:
 
@@ -189,7 +192,7 @@ The agent should call them automatically while doing work. They persist local st
 - `documentation`
 - `maintenance`
 
-Each plan includes required knowledge actions, implementation constraints, and verification focus. This keeps generated UI imports, PRD digestion, Swagger/API work, tests, bug fixes, and requirement changes inside the same controlled policy loop without turning skills into executable runtime commands.
+Each plan includes required knowledge actions, implementation constraints, and verification focus. UI restoration, PRD knowledge, explicit source-backed API work, and evidence-heavy changes use the full controlled loop. Ordinary tests, bug fixes, docs, maintenance, and requirement edits are intentionally lightweight policy guidance unless the task supplies PRD/API/UI source material or asks for auditable evidence. Project skills remain guidance, not executable runtime commands.
 
 ### Agent Plan Proposals
 
@@ -251,7 +254,12 @@ These commands expose project-local knowledge and workflow guidance as provenanc
 ```bash
 npm run harness -- skills list --json
 npm run harness -- skills check --json
+npm run harness -- ingest record --json --kind prd|openapi|ui-package --id <source-id> --source <file-or-url> --summary "<summary>"
+npm run harness -- ingest list --json
+npm run harness -- ingest show --json --ref ingest://<kind>/<source-id>
 npm run harness -- knowledge add --json --kind rule --subject "<subject>" --rule "<rule>"
+npm run harness -- knowledge outline --json --ref ingest://<kind>/<source-id>
+npm run harness -- knowledge draft --json --ref ingest://<kind>/<source-id>
 npm run harness -- knowledge promote --json --title "<title>" --body "<body>"
 npm run harness -- knowledge update --json --id <knowledge-id> --source "docs/prd/<file>.md"
 npm run harness -- knowledge index --json
@@ -262,7 +270,7 @@ npm run harness -- knowledge show --json --id <knowledge-id>
 npm run harness -- knowledge check --json
 ```
 
-Prefer `knowledge add` for PRD digestion. It stores small atomic entries such as rules, workflows, permissions, terms, decisions, conventions, and pitfalls with `source_paths` pointing back to the original PRD. Use `knowledge update` when a requirement changes so existing cards are merged instead of duplicated. `knowledge index` writes `.frontend-harness/knowledge/index.json`, a deterministic manifest grouped by PRD source, card id, scope, and tag. `knowledge coverage` verifies active PRD semantics remain traceable to source documents. `knowledge promote` remains available for authored Markdown cards, but raw PRD prose should stay in source documents instead of being copied into knowledge.
+Prefer `knowledge add` for PRD digestion. It stores small atomic entries such as rules, workflows, permissions, terms, decisions, conventions, and pitfalls with `source_paths` pointing back to a project file, external reference, or `ingest://...` provenance record. Use `ingest record` when PRD, OpenAPI, or UI package material is temporary but the distilled knowledge needs a lightweight source proof. Use `knowledge outline` for project-file PRD Markdown to turn the source heading structure into a deterministic checklist with suggested knowledge kinds and extraction-required hints. Use `knowledge draft` to turn an ingest record into reviewed `knowledge add` / `knowledge module` scaffolds; for PRD Markdown, `extractionItems` is the source checklist and each required block should be added, updated, or explicitly skipped with a reason. Do not add scaffolds unchanged. When existing cards already point at the same ingest record, produced card IDs, or source file, draft output includes `knowledge update` candidates so agents can merge before adding duplicates. Use `knowledge update` when a requirement changes so existing cards are merged instead of duplicated. `knowledge index` writes `.frontend-harness/knowledge/index.json`, a deterministic manifest grouped by PRD source, card id, scope, and tag. `knowledge coverage` verifies active PRD semantics remain traceable to source documents or ingest provenance. `knowledge promote` remains available for authored Markdown cards, but raw PRD prose should stay in source documents or temporary ingest inputs instead of being copied into knowledge.
 
 ## Runtime Boundary
 
@@ -272,7 +280,7 @@ The boundary is strict:
 - `frontend-harness` owns policy.
 - The project owns durable state and knowledge.
 
-Project skills under `.frontend-harness/skills/` are policy guidance and provenance for planning. They are intentionally separate from Codex or Claude runtime skills installed in the developer environment.
+Project skills under `.frontend-harness/skills/` are policy guidance and provenance for planning. They are intentionally separate from Codex or Claude runtime skills installed in the developer environment. For simple tasks, they should be enough on their own; the harness should not force a full stateful loop when direct agent conversation plus local verification is cheaper.
 
 That means `frontend-harness` should stay small and focused. Its job is to make frontend work repeatable, not to become a second runtime.