frontend-harness 0.7.9 → 0.8.0

package/CHANGELOG.md

@@ -4,6 +4,35 @@ All notable changes to `frontend-harness` are documented here.
 
 This project follows semver while it is pre-1.0: patch releases may include harness policy improvements that tighten validation, and minor releases may change generated protocol expectations.
 
+## 0.7.9 - 2026-05-27
+
+### Fixed
+
+- Hardened harness artifact writes, protocol initialization, visual comparison outputs, and log cleanup against symlink paths that could otherwise write or delete files outside the project.
+- Rejected symlinked state lock files instead of waiting on or inspecting external lock targets.
+- Ignored symlinked project knowledge and skill Markdown files during discovery so external files cannot be injected into project-local planning policy.
+- Ignored symlinked protocol constraint files and PRD discovery roots, and rejected non-POSIX file paths in execution-unit and component-graph artifacts.
+- Rejected duplicate CLI flags instead of letting later values silently override earlier inputs.
+- Rejected malformed or oversized PNG inputs during visual comparison before decoding or allocating diff buffers.
+- Bounded knowledge and PRD markdown scanning by file size, file count, and directory depth so checks fail visibly instead of consuming unbounded resources.
+- Bounded project-local skill markdown scanning by file size, file count, and directory depth so checks fail visibly instead of consuming unbounded resources.
+- Rejected oversized execution-unit and component-graph artifacts before parsing generated harness JSON.
+- Skipped context artifact hashing for oversized harness files so context construction cannot read unbounded artifact contents.
+- Read repair packet log excerpts from bounded tail windows while hashing logs in chunks.
+- Skipped repair decision provenance hashes for oversized repair and verification artifacts.
+- Rejected oversized agent proposal and repair decision input envelopes before JSON parsing.
+- Bounded protocol initialization and check reads for managed protocol files, builtin project skills, and protocol provenance artifacts.
+- Rejected oversized visual evidence artifacts before hash validation and hashed git change baselines in chunks.
+- Failed verification command discovery when package verification scripts are malformed instead of treating invalid script values as runnable commands.
+- Preserved failing verification command exit codes when test output contains phrases such as "not found" instead of misclassifying those failures as command launch errors.
+- Wrote harness JSON and text artifacts through same-directory temporary files and atomic renames to reduce partial-write and symlink race exposure.
+- Wrote visual comparison diff images through the same atomic write path as other harness artifacts.
+- Rejected stale protocol provenance artifact paths instead of treating tampered path metadata as current.
+- Applied scaffold executable modes through non-symlink file handles so generated file mode changes cannot follow replaced symlink targets.
+- Revalidated accepted repair decision summaries before exposing them through context so tampered harness artifacts cannot publish unsafe target paths.
+- Preserved quoted frontmatter scalar values during knowledge and skill parsing, preventing escaped quotes from accumulating during read/update cycles.
+- Made context artifact reporting tolerate malformed artifact paths that exist as directories by reporting a missing hash instead of failing the whole context command.
+
 ## 0.7.8 - 2026-05-26
 
 ### Changed

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,11 @@ 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 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 +269,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 draft` to turn an ingest record into a reviewed `knowledge add` scaffold with placeholders for the atomic fact, coverage, verification, scope, and tags; do not add the scaffold 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 +279,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.
 
@@ -289,6 +296,9 @@ The package writes project-local artifacts under `.frontend-harness/`:
   guidance/
   state.json
   verification/
+  design-sources/
+  evidence/
+  visual/
   logs/
   repair/
   repair-decision/