p-dev-harness 0.3.0 → 0.3.1

package/workspace-snapshot/files/docs/releases/v0.3.1.md

@@ -0,0 +1,102 @@
+# v0.3.1 — Immutable workspace provisioning
+
+**Release type:** GitHub source release (annotated tag + curated release notes) plus public npm package **`p-dev-harness@0.3.1`**.
+
+## TL;DR
+
+`p-dev-harness@0.3.1` binds each published package version to an **immutable embedded workspace snapshot** and provisions fresh private workspaces from that snapshot without calling the public template repository at runtime. Existing valid `p-dev-harness@0.3.0` managed workspaces reconnect without content rewrite.
+
+**Primary install command:**
+
+```bash
+npx --yes p-dev-harness@0.3.1
+```
+
+Requires Node.js 22+. macOS is the validated packaged platform; use `--no-open` elsewhere.
+
+Full guide: [`docs/p-dev.md`](../p-dev.md)
+
+## What ships
+
+- Embedded `workspace-snapshot/manifest.json` + `workspace-snapshot/files/**` in the npm tarball
+- Package-owned GitHub provisioning (`createUserRepository` + git blob/tree/commit APIs)
+- Managed marker v3 with `createdFromPackageSnapshot` provenance
+- Default blob-upload concurrency **2** with shared rate-limit coordination and automatic retry/pause
+- Legacy reconnect for valid `p-dev-harness@0.3.0` managed workspaces
+- Conditional release-impact guidance in planner/implementation contracts
+
+## What does not ship
+
+- Automatic upgrade of existing managed workspaces to the 0.3.1 snapshot
+- Changes to `weston-uribe/p-dev-harness-template` default branch or tags
+- Provider-agnostic agent support or production SaaS claims
+
+## Embedded snapshot behavior
+
+Each `p-dev-harness@0.3.1` install carries a curated workspace snapshot generated from the release commit. Fresh private `OWNER/p-dev-harness` workspaces are created by uploading snapshot blobs to GitHub and committing the snapshot tree plus a managed marker overlay.
+
+- **Package-to-snapshot immutability:** manifest `sourceCommit`, `snapshotContentId`, `snapshotSha256`, and `gitRootTreeSha1` are recorded in the tarball
+- **First-time provisioning** can take several minutes; Configure shows upload progress
+- **Rate-limit recovery** is automatic — shared pause coordination across concurrent upload workers; no env var required for the default path
+- Optional advanced override: `HARNESS_SNAPSHOT_UPLOAD_CONCURRENCY` (integer `1`–`4`)
+
+## Compatibility
+
+| Workspace type | Behavior |
+|----------------|----------|
+| Fresh install @0.3.1 | Provisions from embedded snapshot |
+| Valid 0.3.0 managed workspace | Reconnects without rewrite |
+| Existing workspace on newer snapshot | Not auto-upgraded |
+
+`weston-uribe/p-dev-harness-template` remains a **frozen** compatibility artifact for `p-dev-harness@0.3.0` only.
+
+## Release-impact agent-contract changes
+
+Planner and implementation skills include conditional release-impact analysis for published artifacts. Agents must classify impact but do **not** authorize publish, tag, or deploy actions.
+
+## Security and mutation boundaries
+
+- Secrets remain in operator workspace, GitHub Actions secrets, and Vercel env vars — never in the published package
+- Published tarball excludes credentials, operator state, and local caches
+- Release validation uses uniquely named private repositories; production `weston-uribe/p-dev-harness` is not mutated
+- External template repository is not mutated for 0.3.1+
+
+## Validation summary
+
+Release validation includes:
+
+- Full test suite, webhook tests, package prepare/pack/inspect
+- Packed npm README and snapshot manifest correctness
+- Exact tarball launcher smoke (`/settings/configure` HTTP 200, stop/relaunch)
+- Real-account provisioning gate from installed tarball at default concurrency 2
+- Registry smoke after npm publication
+
+Immutable npm, tag, and detailed validation evidence are recorded in the post-release finalization PR.
+
+## Known limitations
+
+- Cursor-only agent provider
+- Linear / GitHub / GitHub Actions / Vercel stack
+- macOS validated for packaged browser auto-launch
+- No full isolated npm issue lifecycle validated
+- No automatic private harness workspace upgrade/sync to newer snapshots
+- Not production SaaS or provider-agnostic
+
+## Rollback
+
+- **Unpublished code:** revert merge commit on `main`
+- **Published npm:** follow npm deprecation policy only under explicit operator approval; prefer forward-fix `0.3.2` for defects
+- **Never** overwrite tags or republish the same npm version with different bytes
+
+## Immutable release evidence
+
+Recorded after publication in the post-release finalization PR and below once available:
+
+| Field | Value |
+|-------|-------|
+| **RELEASE_SHA** | _recorded at publication_ |
+| **npm package** | `p-dev-harness@0.3.1` |
+| **GitHub release** | _recorded at publication_ |
+| **Tarball** | `packages/p-dev/p-dev-harness-0.3.1.tgz` |
+
+See [`release-process.md`](release-process.md) for the operator workflow.

package/workspace-snapshot/files/docs/research/001-manual-run-retrospective.md

@@ -0,0 +1,64 @@
+# Retrospective: Manual harness run 001
+
+**Run:** [`examples/runs/001-target-app-github-link/`](../examples/runs/001-target-app-github-link/)  
+**Target:** `owner/example-target-app`  
+**Outcome:** PR [#1](https://github.com/owner/example-target-app/pull/1) squash-merged; production deployed  
+**Date:** 2026-07-06
+
+This documents one **manual** v0.1 loop. It does not prove the harness is automated, reusable at scale, or ready for skills.
+
+---
+
+## What worked
+
+- **Bounded issue scope** — single link, one surface; easy to eval and merge in one PR.
+- **Templates gave structure** — issue → plan → scorecard → readiness report stayed aligned without a control plane.
+- **Repo inspection step** — forcing the agent to find contact/link patterns before coding avoided wrong placement guesses from the harness repo alone.
+- **Human gates** — PM review before merge caught nothing blocking, but the gate itself matched the intended workflow.
+- **Three-file diff** — narrow scope made code review and harness artifact updates straightforward.
+
+## What slowed the loop
+
+- **Cross-repo context switching** — harness repo for artifacts, target repo for implementation; manual copy of evidence between them.
+- **Preliminary plan → post-inspection update** — plan started with TBD file list; agent had to discover `contact-section.tsx`, `content.ts`, `breakpoints.ts` during execution.
+- **Icon library surprise** — Lucide `Github` not in pinned version; unplanned inline SVG workaround (acceptable, but added a decision mid-run).
+- **Artifact updates in two passes** — readiness artifacts updated after implementation, then again after merge; no automation linking PR state to harness folder.
+- **Explicit mobile check** — responsive grid implied mobile OK; no dedicated mobile viewport note in validation until follow-up.
+
+## Reusable template improvements (not skills)
+
+| Improvement | Where | Why |
+|-------------|-------|-----|
+| **Repo inspection checklist** | `implementation-plan.md` | Standardize “find link patterns, content source, validation commands” before “Files to touch” |
+| **Icon / dependency check** | `implementation-plan.md` | Prompt: verify icon/component exists in pinned library version before planning Lucide names |
+| **Explicit mobile validation row** | `implementation-plan.md`, `eval-scorecard.md` | Avoid inferring mobile from desktop/grid checks |
+| **Merge / deploy section** | `pr-readiness-report.md` | Fields for main commit SHA, deployment URL, merge method after PR closes |
+
+These are **template edits** for v0.1 — not automations.
+
+## What should not become a skill yet
+
+- **"Add social link to site"** — one data point; pattern may differ on kinterra or non-Next.js repos.
+- **PR → harness artifact sync** — only one run; manual updates worked; automation premature.
+- **Vercel deploy polling** — no repeated pain at scale yet.
+- **Target repo bootstrap** — agent still needs `AGENTS.md` and local conventions; don’t encode until run 002 confirms repetition.
+
+Skills require **validated repetition** across runs, not one successful merge.
+
+## Next hypothesis for run 002
+
+**Candidate:** A slightly larger target-app change that still fits one PR — e.g. copy or content update in an existing case study section, or a small UX fix that touches `lib/content.ts` plus one component.
+
+**Hypothesis to test:**
+
+- Does the repo inspection checklist (if added to templates) reduce plan TBD time?
+- Do the same eval criteria apply, or does content-heavy work need a different scorecard row set?
+- Is the harness artifact folder structure sufficient, or does run 002 need a linked issue ID from Linear/GitHub Issues?
+
+**Explicit non-goals for run 002:** Linear integration, cloud agents, skills, CI eval runners.
+
+---
+
+## Honest maturity statement
+
+Run 001 proves Weston can execute **one structured manual loop** with docs and templates. The harness remains v0.1 documentation scaffold plus example artifacts — not a productized agentic sprint system.

package/workspace-snapshot/files/docs/research/002-linear-cursor-integration-smoke-test.md

@@ -0,0 +1,64 @@
+# Spike: Native Cursor ↔ Linear integration smoke test
+
+**Linear issue:** [WES-6 — Native Cursor integration smoke test](https://linear.app/issue/WES-6)  
+**Target repo:** [`agentic-product-development-harness`](https://github.com/weston-uribe/agentic-product-development-harness)  
+**Date:** 2026-07-06  
+**Outcome:** Cursor cloud agent launched from Linear; docs-only PR opened from this spike.
+
+This note records a **manual integration spike**, not production automation. v0.1 still has no bidirectional Linear sync, skills, or harness automations.
+
+---
+
+## What was tested
+
+Whether assigning or mentioning Cursor from a Linear issue can:
+
+1. Start a Cursor cloud agent against the harness repo
+2. Create a git branch
+3. Open a GitHub pull request
+4. Limit changes to `docs/research/`
+5. Include the originating Linear issue link in the PR
+6. Surface activity back to Linear (comment or status update from Cursor)
+
+## Acceptance criteria (spike)
+
+| Criterion | Result |
+|-----------|--------|
+| Cursor cloud agent starts from Linear issue WES-6 | Pass — this run |
+| Agent creates a branch | Pass — `cursor/linear-cursor-smoke-test-cbd0` |
+| Agent opens a GitHub PR | Pass — see PR linked from this commit |
+| PR modifies only `docs/research/` | Pass — docs-only |
+| PR includes Linear issue link | Pass — WES-6 linked in PR body |
+| Linear receives comment or update from Cursor | Pending human verification in Linear UI |
+| No skills, automations, code, or releases | Pass — documentation only |
+
+## Scope boundaries (honored)
+
+- No Cursor Automations
+- No changes to `example-target-app` or other target repos
+- No new skills under `skills/` (canonical skills now live under `.agents/skills/`)
+- No releases or version bumps
+- No implementation code or CI changes
+
+## Observations
+
+- **Intake path works:** Linear issue assignment/mention can route work to a cloud agent on the correct GitHub repository without manual copy-paste of issue text.
+- **Harness constraints hold:** AGENTS.md scope rules (docs-only, no invented maturity) are compatible with Linear-triggered runs when the issue description is explicit.
+- **Traceability gap remains:** Full PM control plane (v0.3) still requires validated templates and repeatable status sync; this spike proves trigger + PR path only.
+
+## What this does not prove
+
+- Repeatable sprint workflow across multiple repos
+- Automated eval or readiness gates from Linear fields
+- Bidirectional issue status sync
+- That Linear comments always populate without manual verification
+
+## Next step (if spike passes)
+
+Capture friction from the Linear UI (latency, comment format, branch naming) in a follow-up research note before any ROADMAP phase promotion. Do not add skills or automations until a second manual run confirms the same loop.
+
+---
+
+## Honest maturity statement
+
+Native Cursor ↔ Linear **triggering** was exercised once on 2026-07-06. Linear as a **control plane** remains **planned** per [`ROADMAP.md`](../../ROADMAP.md) v0.3 — not implemented in the harness today.

package/workspace-snapshot/files/docs/research/003-cursor-automation-planning-router-spike.md

@@ -0,0 +1,104 @@
+# Spike: Cursor Automation planning router
+
+**Linear issues:** [WES-9 — Planning router automation spike](https://linear.app/issue/WES-9), [WES-10 — Idempotent router fix](https://linear.app/issue/WES-10)  
+**Target repo:** [`agentic-product-development-harness`](https://github.com/weston-uribe/agentic-product-development-harness)  
+**Date:** 2026-07-06  
+**Outcome:** Planning-router Cursor Automation validated; idempotent silent no-op behavior confirmed.
+
+This note records a **Cursor Automations spike**, not production automation. Implementation, revision, and merge/deploy automations remain **planned**.
+
+---
+
+## What was tested
+
+Whether a Linear status-change Cursor Automation can:
+
+1. Trigger on Linear issue status changes
+2. Authenticate to Linear MCP inside the automation environment
+3. Read and write Linear issues (comments, status transitions)
+4. Route on issue status and exit silently when the status does not match
+5. Run the planning flow: **Ready for Planning** → **Planning** → **Ready for Build** with a durable planning comment
+
+---
+
+## WES-9 — Initial planning router spike
+
+### Result
+
+| Criterion | Result |
+|-----------|--------|
+| Linear status-change trigger fires automation | Pass |
+| Linear MCP auth inside automation environment | Pass |
+| Issue read (status, labels, title, description, comments) | Pass |
+| Issue write (status transition, comment) | Pass |
+| Status path: Ready for Planning → Planning → Ready for Build | Pass |
+| Durable planning comment posted | Pass |
+
+### Issue discovered
+
+Broad Linear status-change triggers caused **duplicate automation runs**. When the automation moved the issue through **Planning** and **Ready for Build**, each status transition re-fired the trigger, producing duplicate runs and extra Linear comments.
+
+---
+
+## WES-10 — Idempotent router fix
+
+### Result
+
+| Criterion | Result |
+|-----------|--------|
+| Router inspects current status before acting | Pass |
+| Non-matching / duplicate runs exit silently | Pass |
+| No Linear comments written on no-op exit | Pass |
+| Successful planning run posts one combined planning/report comment | Pass |
+
+The quiet router pattern works: duplicate or self-triggered runs are acceptable **only when they exit without Linear writes**.
+
+---
+
+## Model configuration reality
+
+Cursor Automations currently require a **concrete model selection**. **`Auto` is not available** as an automation model setting at the time of this spike.
+
+| Setting | Policy |
+|---------|--------|
+| **Current automation model** | **Composer 2.5** — configured on the planning-router automation |
+| **Preferred future policy** | **`Auto`**, if Cursor Automations support it |
+| **Mid-run model switching** | **Disallowed** — agents must not change models during a run |
+| **Documentation** | Reports and comments must state the **actual configured model**, not a preferred policy |
+
+---
+
+## What is now validated
+
+- Linear status-change trigger
+- Linear MCP authentication inside automation environment
+- Linear issue read/write (comments, status transitions)
+- Status transition path: **Ready for Planning** → **Planning** → **Ready for Build**
+- Durable planning comment on successful planning run
+- Silent no-op behavior for duplicate and non-matching runs (no Linear comment noise)
+
+---
+
+## What is not yet validated
+
+- Implementation automation (build from **Ready for Build**)
+- Branch creation from automation
+- PR creation from automation
+- Revision loop (**Needs Revision** → **Revising** → **PM Review**)
+- Merge/deploy reporting automation
+
+---
+
+## Scope boundaries (honored)
+
+- Harness repo documentation only for this note
+- No changes to `example-target-app` or other target repos
+- No new skills under `skills/` (canonical skills now live under `.agents/skills/`)
+- No releases or version bumps
+- No implementation code or CI changes
+
+---
+
+## Honest maturity statement
+
+The **planning-router** Cursor Automation spike is **validated** as of 2026-07-06 (WES-9 + WES-10). A **single** planning automation exists in Cursor; implementation, revision, and merge/deploy automations remain **planned** per [`ROADMAP.md`](../../ROADMAP.md).

package/workspace-snapshot/files/docs/research/README.md

@@ -0,0 +1,26 @@
+# Research
+
+Workflow research, experiment notes, and learnings from manual v0.1 runs.
+
+## Purpose
+
+Capture what works and what fails when running the harness loop manually—before encoding anything as skills or automation.
+
+## What to document here
+
+- Manual loop retrospectives (issue → plan → Cursor → eval → PR)
+- Friction points in templates or rubrics
+- Target repo-specific notes (e.g. target-app conventions)
+- Comparisons of tool options (Linear vs GitHub Issues, etc.)
+
+## Entries
+
+| ID | Topic | Status |
+|----|-------|--------|
+| [001](001-manual-run-retrospective.md) | Manual harness run 001 (target-app GitHub link) | Complete |
+| [002](002-linear-cursor-integration-smoke-test.md) | Native Cursor ↔ Linear integration smoke test (WES-6) | Complete |
+| [003](003-cursor-automation-planning-router-spike.md) | Cursor Automation planning router spike (WES-9, WES-10) | Complete |
+
+## v0.1 status
+
+Research notes from manual runs and integration spikes. Skill system architecture: [`docs/skills/skill-architecture.md`](../skills/skill-architecture.md).

package/workspace-snapshot/files/docs/security.md

@@ -0,0 +1,190 @@
+# Security baseline (v0.3.0)
+
+Operator guide for secrets, tokens, logging, and accepted automation risks for the public harness repo.
+
+**Related:** [`docs/linear-watcher-setup.md`](linear-watcher-setup.md), [`docs/decisions/0001-cursor-first-v0.1.md`](decisions/0001-cursor-first-v0.1.md)
+
+---
+
+## Threat model
+
+This repo is **public**. Untrusted users can read code, workflow definitions, and (for public repos) Actions logs. They **cannot** push to `main` or trigger secret-bearing workflows without write access or a dispatch token.
+
+Trusted automation paths:
+
+1. **Linear signed webhook** → Vercel bridge → `repository_dispatch`
+2. **Target repo `main` push** → `production_promoted` dispatch (separate repo)
+3. **`workflow_dispatch`** — limited by GitHub Actions write permission on this repo
+
+**Pass B (implemented):** Branch protection ruleset on `main` — PR required, required status checks, no direct push, no force push. GitHub Actions allowed-actions allowlist is active.
+
+---
+
+## Plain-English security model
+
+The repo is public, but the secrets are not in the repo.
+
+A public reader can see the code and workflow definitions. They cannot push to `main`, trigger trusted secret-bearing automation, write to Linear, or merge target repo PRs unless they have one of the trusted credentials or repo permissions.
+
+The important boundary is credential access:
+
+- Vercel can only dispatch the harness workflow.
+- GitHub Actions holds the live harness secrets.
+- Local `.env` files stay untracked.
+- Target-repo write access comes from `HARNESS_GITHUB_TOKEN`, not from public repo visibility.
+
+---
+
+## Token scope matrix
+
+| Secret | Where stored | Scope / permissions | Can write GitHub? | Can write Linear? | Risk if leaked |
+|--------|-------------|---------------------|-------------------|-------------------|----------------|
+| `LINEAR_WEBHOOK_SECRET` | Vercel | HMAC signing for Linear webhooks | No | Indirect (forge webhook → dispatch) | High |
+| `GITHUB_DISPATCH_TOKEN` | Vercel, target repo | Fine-grained **Contents: write** on harness repo only | Triggers workflows only | No | High |
+| `LINEAR_API_KEY` | GitHub Actions secrets | Linear API as token owner | No | **Yes** | Critical |
+| `CURSOR_API_KEY` | GitHub Actions secrets | Cursor Cloud Agents | No (Cursor-side) | No | High |
+| `HARNESS_GITHUB_TOKEN` | GitHub Actions secrets | Target repos: PR merge/repair | **Yes** (configured target repos) | No | Critical |
+| `HARNESS_CONFIG_JSON_B64` | GitHub Actions secrets | Private harness config JSON (base64) | No | No | High (reveals repo URLs, branch strategy) |
+
+---
+
+## Vercel environment (webhook bridge only)
+
+Store **only**:
+
+| Variable | Required | Notes |
+|----------|----------|-------|
+| `LINEAR_WEBHOOK_SECRET` | yes | Linear webhook signing secret |
+| `GITHUB_DISPATCH_TOKEN` | yes | Harness-repo-scoped dispatch PAT |
+| `HARNESS_TEAM_KEY` | **yes in production** | Set to `WES` — reject non-team issue keys |
+
+Optional: `GITHUB_DISPATCH_REPOSITORY`, `GITHUB_DISPATCH_EVENT_TYPE`, `LINEAR_WEBHOOK_TIMESTAMP_TOLERANCE_MS`.
+
+**Do not** store `LINEAR_API_KEY`, `CURSOR_API_KEY`, or merge-capable `GITHUB_TOKEN` / `HARNESS_GITHUB_TOKEN` in Vercel.
+
+---
+
+## GitHub Actions secrets
+
+| Secret | Used by |
+|--------|---------|
+| `HARNESS_CONFIG_JSON_B64` | All harness jobs (private operator config) |
+| `LINEAR_API_KEY` | All live harness phases |
+| `CURSOR_API_KEY` | planning, implementation, revision, merge repair |
+| `HARNESS_GITHUB_TOKEN` | Mapped to runtime `GITHUB_TOKEN` in workflows |
+
+`HARNESS_GITHUB_TOKEN` must have access to **target repos** in the resolved harness config (classic `repo` or fine-grained **Contents: Read and write** + **Pull requests: Read and write** on each target). Target repos are typically defined in private config via `HARNESS_CONFIG_JSON_B64` — see [`docs/operator-config.md`](operator-config.md).
+
+Do **not** name the Actions secret `GITHUB_TOKEN` — GitHub reserves that for the auto-generated workflow token.
+
+---
+
+## PAT policy
+
+- **Prefer fine-grained PATs** scoped to the minimum repos and permissions.
+- **Classic PATs** are discouraged except as a documented fallback.
+- `GITHUB_DISPATCH_TOKEN`: harness repo only, Contents: write (for `repository_dispatch`).
+- `HARNESS_GITHUB_TOKEN`: target repos only, merge/repair permissions as needed.
+
+---
+
+## Secret handling rules
+
+1. **Rotate immediately** if a secret is exposed (logs, commit, artifact, comment).
+2. **No structured JSON secrets** — store plain string env vars, not JSON blobs.
+3. **Never commit** secrets to the repo, docs, tests, or examples.
+4. **Never log** raw tokens — harness redacts stdout before logs, summaries, and artifacts.
+5. Raw command output may exist only as a **temporary file in the same workflow step**; it must be deleted before artifact upload.
+
+### Local GUI secret handling (Milestone 4–5)
+
+The local Product Development Harness GUI (`npm run harness:gui`) handles secrets with these boundaries:
+
+- Existing `.env.local` secret values are never sent to the browser — only key presence (`Set` / `Missing`).
+- Existing harness repo GitHub Actions secret values are never readable — only `present` / `missing` / `unknown` status.
+- Newly entered secrets exist only in transient form state and POST bodies to the local Next.js server.
+- Preview responses redact secret assignment lines and never include `HARNESS_CONFIG_JSON_B64` generated values.
+- Apply requires explicit confirmation and a matching server-side preview fingerprint per action.
+- Separate confirmations are required for `remote-secret-write` (harness repo Actions secrets) and `remote-repo-write` (target workflow branch/PR install).
+- The GUI does not persist secrets in `localStorage`, `sessionStorage`, cookies, or URL query params.
+- Local GUI apply writes only `.env.local` and `.harness/config.local.json` on the operator machine.
+- Remote GUI apply writes only encrypted harness repo Actions secrets and target-repo install branches/PRs — never directly to target production or `main` branches.
+
+See [`docs/gui-local.md`](gui-local.md) and [`docs/gui-remote-setup.md`](gui-remote-setup.md).
+
+---
+
+## Accepted risks
+
+| Risk | Mitigation |
+|------|------------|
+| `repository_dispatch` is not Linear-signed | Requires possession of `GITHUB_DISPATCH_TOKEN` |
+| `workflow_dispatch` can target arbitrary issue keys | Limited to users with Actions write on this repo; optional `harness-manual` environment |
+| Dispatch bypasses webhook status filter | `resolve-route` uses live Linear state; cannot force wrong phase via fake payload status |
+| Public Actions logs | Redacted harness output only in logs/summaries/artifacts |
+
+---
+
+## Pinned Actions (verified 2026-07-08)
+
+Re-resolve SHAs before updating refs:
+
+| Action | Tag | SHA |
+|--------|-----|-----|
+| `actions/checkout` | v4 | `34e114876b0b11c390a56381ad16ebd13914f8d5` |
+| `actions/setup-node` | v4 | `49933ea5288caeca8642d1e84afbd3f7d6820020` |
+| `actions/upload-artifact` | v4 | `ea165f8d65b6e75b540449e92b4886f43607fa02` |
+| `github/codeql-action` | v3 | `641a925cfafe92d0fdf8b239ba4053e3f8d99d6d` |
+
+Dependabot opens PRs for npm and GitHub Actions updates weekly.
+
+---
+
+## Known transitive vulnerabilities
+
+`npm audit --audit-level=moderate` may report **high** severity issues in `undici` (transitive via `@cursor/sdk` → `@connectrpc/connect-node`). As of v0.3.0, **no fix is available** upstream. Accepted risk — track `@cursor/sdk` releases; do not add force-resolutions without upstream guidance.
+
+---
+
+## OpenSSF Scorecard
+
+**Deferred.** Scorecard uses third-party `ossf/scorecard-action`, which would require expanding the Actions allowlist and adds release noise. CodeQL + CI are the current baseline.
+
+---
+
+## Pass B — branch protection and solo repo policy (implemented)
+
+The following operator settings are **active** on this repo:
+
+| Setting | Status |
+|---------|--------|
+| Ruleset on `main` (PR required, status checks, no force push) | **Implemented** |
+| Required status checks: `test`, `Analyze (javascript-typescript)` | **Implemented** |
+| Actions allowed-actions allowlist | **Implemented** |
+| `.github/CODEOWNERS` for `.github/workflows/**` | **File exists** — documents ownership |
+| Required GitHub approvals | **0** (solo-maintainer mode) |
+| CODEOWNER review enforced | **No** (not required while solo maintainer) |
+| Direct push to `main` | **Blocked** |
+
+### Solo-maintainer automation policy
+
+While Weston is the only maintainer:
+
+- Changes reach `main` via **PR + required checks** — not direct push.
+- **Required GitHub approvals are 0** — merge does not wait for a separate human reviewer.
+- **Linear/status gates remain required** — harness automation respects allowlisted Linear statuses; merge runs only after **Ready to Merge**.
+
+### When to re-enable approvals and CODEOWNER review
+
+Turn on required GitHub approvals and enforce CODEOWNER review when:
+
+- A second engineer joins as maintainer, or
+- The repo begins accepting external contributions
+
+At that point, update the ruleset to require approvals and enable CODEOWNER review for `.github/workflows/**` changes.
+
+### Optional (not required for v0.3.0)
+
+- `harness-manual` environment for `workflow_dispatch` — adds an approval gate for manual cloud runs if desired later.
+
+**Release contract:** [`docs/releases/v0.3.0.md`](releases/v0.3.0.md) (current), [`docs/releases/v0.2.0.md`](releases/v0.2.0.md) (historical)

package/workspace-snapshot/files/docs/skills/README.md

@@ -0,0 +1,7 @@
+# Skills documentation
+
+Canonical harness skills live under [`.agents/skills/`](../../.agents/skills/).
+
+Implemented skills: `issue-intake`, `code-health-audit`, `architecture-evolution-audit`, `security-audit`, `planner`, and `implementation`. `performance-cost-audit` remains planned.
+
+Read [`skill-architecture.md`](skill-architecture.md) for the skill system definition, ownership model, categories, and planned skill map.