p-dev-harness 0.3.0 → 0.3.1

package/workspace-snapshot/files/docs/skills/skill-architecture.md

@@ -0,0 +1,197 @@
+# Skill architecture
+
+**Status:** Implemented — architecture artifact and canonical path. Operator-invoked skills: `issue-intake`, `code-health-audit`, `architecture-evolution-audit`, and `security-audit` are implemented. Runner/agent phase skills: `planner` and `implementation` are implemented.
+
+This document defines the harness skill system. It does **not** create the full skill set.
+
+## What a harness skill is
+
+A harness skill is a **reusable workflow contract** for an agent or operator.
+
+| Concept | What it is |
+|---------|------------|
+| **Skill** | Version-controlled workflow contract with clear inputs, outputs, boundaries, and maturity labels |
+| **Prompt** | Instructions for a single run or client session — not necessarily a durable, reviewable contract |
+| **Tool** | Executable capability (CLI, MCP, API) — not a workflow definition |
+
+A skill is **not** merely a prompt and **not** a tool.
+
+## Canonical layout
+
+Canonical harness skills live at:
+
+```text
+.agents/skills/<skill-name>/SKILL.md
+```
+
+Rules:
+
+- Every canonical skill has **exactly one** primary `SKILL.md`.
+- Additional files exist only when they materially improve clarity, reuse, validation, or execution.
+- Tool-specific locations (`.cursor/skills`, `.claude/skills`, ChatGPT project files, future Codex adapters) are **adapters** — generated copies, symlinks, exports, or client-specific forms. They are **not** the canonical source of truth.
+
+Documentation about the skill system lives under [`docs/skills/`](README.md).
+
+## Skill folder shape
+
+Minimum:
+
+```text
+.agents/skills/<skill-name>/
+  SKILL.md
+```
+
+Optional supporting files, only when needed:
+
+- `examples.md` or `examples/`
+- `references/` — shared reference material consumed by the skill
+- `modes/` — mode-specific instructions when one skill has distinct execution modes
+- `resources/` — static assets or templates
+- `scripts/` — helper scripts used by the skill workflow
+- `adapters/` — client-specific export notes or adapter stubs
+
+Do not add structure before a second or third skill proves it is needed. Prefer a flat folder with one or two markdown files until complexity warrants more.
+
+## Adapter model
+
+Client and provider locations are **adapters**, not canonical sources:
+
+| Location | Role |
+|----------|------|
+| `.agents/skills/<skill-name>/` | **Canonical** repo source |
+| `.cursor/skills/<skill-name>/` | Cursor install/adaptation location |
+| `.claude/skills/<skill-name>/` | Future Claude adapter (not implemented) |
+| ChatGPT project files | Future export/adaptation (not implemented) |
+| Future Codex adapters | Future export/adaptation (not implemented) |
+
+**Do not claim** Claude, Codex, ChatGPT adapter automation, or multi-client skill sync as implemented until an adapter is proven end to end.
+
+## Ownership and promotion
+
+Skill creation and promotion are **human-owned** product/architecture decisions. Agents may propose, draft, or document skill candidates, but must not autonomously create, promote, or enforce skill-creation policy. Repetition or validation history may be useful evidence, but it is not a required gate unless explicitly set by the human operator.
+
+## Skill categories
+
+### Operator-invoked skills
+
+Used directly by the operator in an agent client (Cursor, future clients). The operator chooses when to invoke the skill.
+
+**Implemented:**
+
+| Skill | Purpose |
+|-------|---------|
+| `issue-intake` | Turn a fuzzy product idea into a harness-compatible Linear issue |
+| `code-health-audit` | Report-only inspection of code health |
+| `architecture-evolution-audit` | Report-only inspection of architecture evolution and future-change readiness |
+| `security-audit` | Report-only security risk inspection |
+
+**Planned architecture concepts only** (not implemented):
+
+| Skill | Purpose |
+|-------|---------|
+| `performance-cost-audit` | Report-only performance and cost inspection |
+
+### Runner / agent phase skills
+
+Reusable workflow contracts aligned with harness phases and cloud agent runs. They describe what an agent should do when planning or implementing work; they are distinct from operator-invoked skills.
+
+Runner/agent phase skills are **workflow contracts only** today. They are **not** wired as runner prompt integration — SDK runners continue to use [`src/prompts/*.md`](../src/prompts/). Status routing and Linear transitions remain runner-owned.
+
+**Implemented:**
+
+| Skill | Trigger context | Purpose |
+|-------|-----------------|---------|
+| `planner` | Ready for Planning | Produce durable planning output and reviewable PR slices for operator or runner use |
+| `implementation` | Ready for Build, Needs Revision, integration repair | Scoped code changes on a feature branch |
+
+#### Planner modes (implemented)
+
+- Feature planning
+- Audit-remediation planning (convert audit findings into remediation plans)
+
+#### Shared planner capability (implemented)
+
+- PR slicing — applied inside feature planning or audit-remediation planning when work is too large for one reviewable PR; not a standalone mode
+
+#### Implementation modes (implemented)
+
+- Initial build
+- Revision (same agent, same branch — preserves context continuity)
+- Integration repair (same agent — preserves branch/context continuity)
+
+Revision and integration repair are **modes of the same implementation agent**, not separate agents.
+
+## Audit skill policy
+
+Audit skills are **report-only**. They inspect and produce findings. They do not make code changes.
+
+| Role | Responsibility |
+|------|----------------|
+| Audit skills | Inspect and report findings |
+| Planner | Convert findings into remediation plans and reviewable PR slices |
+| Implementation agent | Make scoped code changes |
+
+Implemented audit skills are `code-health-audit`, `architecture-evolution-audit`, and `security-audit`. Additional audit skills remain planned.
+
+## What is not a skill (for now)
+
+These remain templates, runner behavior, or references — not formal top-level skills:
+
+- UI/design standards (planned future implementation **reference**, not a standalone skill)
+- Reporting contracts and handoff reports
+- PR-readiness review
+- Umbrella release-readiness audit
+
+A dedicated **release** skill is **not implemented**. Use conditional release-impact analysis in the canonical `planner` skill and aligned runtime planning prompt until a future human-owned decision explicitly promotes release orchestration into its own skill.
+
+## Shared references and embedded standards
+
+Some cross-cutting concerns are embedded in skill boundaries rather than promoted to standalone skills:
+
+| Concern | Status |
+|---------|--------|
+| **PR slicing** | Implemented as a shared planner capability — not a standalone skill |
+| **Scope control** | Embedded in planner and implementation skill boundaries |
+| **Validation expectations** | Embedded by role — audit and planner skills are read-only; implementation performs validation and reports results |
+| **UI/design standards** | Planned future implementation reference — not a standalone skill and not implemented in this PR |
+
+## Relationship to runner prompts
+
+SDK runner prompts in [`src/prompts/`](../src/prompts/) are **implementation details** for cloud agent phases today. They are not canonical harness skills.
+
+| Layer | Location | Status |
+|-------|----------|--------|
+| Canonical skills | `.agents/skills/<skill-name>/SKILL.md` | `issue-intake`, `code-health-audit`, `architecture-evolution-audit`, `security-audit`, `planner`, `implementation` implemented |
+| Runner prompts | `src/prompts/*.md` | Implemented for SDK phases |
+| Client adapters | `.cursor/skills`, etc. | Manual install/export only |
+
+Runner prompt contracts may be absorbed or referenced by canonical skills over time, but that migration is not part of this architecture artifact.
+
+## Current implemented state
+
+After this document and the accompanying migration:
+
+| Item | Status |
+|------|--------|
+| `issue-intake` | **Implemented** at [`.agents/skills/issue-intake/SKILL.md`](../../.agents/skills/issue-intake/SKILL.md) |
+| `code-health-audit` | **Implemented** at [`.agents/skills/code-health-audit/SKILL.md`](../../.agents/skills/code-health-audit/SKILL.md) |
+| `planner` | **Implemented** at [`.agents/skills/planner/SKILL.md`](../../.agents/skills/planner/SKILL.md) |
+| `implementation` | **Implemented** at [`.agents/skills/implementation/SKILL.md`](../../.agents/skills/implementation/SKILL.md) |
+| `architecture-evolution-audit` | **Implemented** at [`.agents/skills/architecture-evolution-audit/SKILL.md`](../../.agents/skills/architecture-evolution-audit/SKILL.md) |
+| `security-audit` | **Implemented** at [`.agents/skills/security-audit/SKILL.md`](../../.agents/skills/security-audit/SKILL.md) |
+| `performance-cost-audit` | Planned architecture concept only |
+| Skill registry / package manager | Not implemented — intentionally deferred |
+| Skill manifests | Not implemented — intentionally deferred |
+| Runner-skill / prompt integration | Not implemented — `src/prompts/*.md` remain runner implementation details |
+| Provider/client adapters | Not implemented — documented as future work |
+
+## Compatibility
+
+Older paths under [`skills/`](../../skills/) are compatibility pointers only. See [`skills/README.md`](../../skills/README.md).
+
+## Related docs
+
+- Issue intake operator guide: [`docs/issue-intake.md`](../issue-intake.md)
+- Provider portability: [`docs/provider-portability.md`](../provider-portability.md)
+- Architecture overview: [`ARCHITECTURE.md`](../../ARCHITECTURE.md)
+- Agent guide: [`AGENTS.md`](../../AGENTS.md)

package/workspace-snapshot/files/docs/target-repo-branch-setup.md

@@ -0,0 +1,80 @@
+# Target repo branch setup
+
+The harness merges pull requests into an **integration branch** configured per repo (`repos[].baseBranch`, e.g. `dev`). Production promotion (`dev` → `main`) is a **manual git step** followed by an explicit harness sync.
+
+**Release contract:** [`docs/releases/v0.3.0.md`](releases/v0.3.0.md)
+
+## Config fields
+
+| Field | Purpose |
+|-------|---------|
+| `baseBranch` | Integration branch PRs target and merge into |
+| `productionBranch` | Production branch (default `main`) used for merge success routing |
+| `integrationPreviewUrl` | Stable dev/staging preview link for merge comments |
+| `integrationSuccessStatus` | Linear status after integration merge (default `Merged to Dev`) |
+| `productionSuccessStatus` | Linear status after production merge (default `Merged / Deployed`) |
+
+When `baseBranch === productionBranch`, behavior matches the original single-branch workflow: merge success moves the issue to **`Merged / Deployed`** and production deployment polling runs as before.
+
+When `baseBranch !== productionBranch`, merge success moves the issue to **`Merged to Dev`**, merge comments note the change is **not yet in production**, and production deployment polling is skipped. After manually promoting `dev` → `main`, run production sync:
+
+```bash
+npm run harness:sync-production -- --repo target-app
+```
+
+For a single issue:
+
+```bash
+npm run harness:sync-production -- --issue WES-19
+```
+
+**Automatic sync:** after `main` is updated, the target repo can dispatch `production_promoted` to the harness GitHub Actions workflow (see [`docs/production-sync-automation.md`](production-sync-automation.md)). Manual CLI remains the fallback.
+
+Harness Actions also supports **`workflow_dispatch`** with input **`sync_repo=target-app`** on **Harness Auto Runner**. Use **`sync_dry_run=true`** (default) to validate sync routing without Linear writes; set **`sync_dry_run=false`** only for live updates.
+
+**Promotion guidance:** prefer merge or fast-forward when promoting `dev` → `main`. Squash promotion may make the original dev merge commit unreachable; sync will correctly no-op with `production_not_promoted`.
+
+## Linear setup (before changing target repo `baseBranch`)
+
+1. Add workflow status **`Merged to Dev`** on the team used by harness issues.
+2. Set `linear.transitionalStatuses.mergedToDev` in `harness.config.json` if your team uses a different label.
+3. Optionally set repo-level `integrationSuccessStatus` / `productionSuccessStatus` overrides.
+
+## GitHub setup
+
+1. Create the integration branch on the target repo (e.g. `dev` from `main`).
+2. Set `repos[].baseBranch` to that branch.
+3. Run `npm run harness:doctor -- --profile merge` with `GITHUB_TOKEN` set — doctor verifies each mapped repo has the configured base branch and that the token can write PR head branches for integration repair.
+
+## Validation
+
+- **Preflight / doctor:** `assertBaseBranchExists()` and PR head-branch write permission checks when `GITHUB_TOKEN` is available.
+- **Implementation / handoff / revision / merge:** PR base must match `repos[].baseBranch` (`wrong_pr_base_branch` if not).
+
+## Concurrent issues
+
+Multiple issues can run planning, implementation, handoff, and revision in parallel (per-issue GitHub Actions concurrency). Merge into the same integration branch is serialized: the auto-runner gate resolves `repoConfigId` and `baseBranch`, then routes merge work to a queue group `harness-merge-{repoConfigId}-{baseBranch}` with `queue: max`. A second issue waiting to merge into integration branch runs only after the first merge completes; the runner re-inspects PR mergeability before merging.
+
+If a queued PR becomes `behind` or `dirty` after another PR lands, the merge runner now attempts automatic integration repair while the issue remains **Merging**:
+
+1. Deterministic GitHub update-branch merges the latest base branch into the PR branch.
+2. If GitHub reports conflicts, a Composer 2.5 repair agent starts on the PR branch, fetches `origin/<baseBranch>`, runs the local base-into-head merge, resolves conflicts, commits, validates, and pushes the PR branch.
+3. If validation and PR checks pass, the runner returns directly to merge without PM Review.
+4. If repair fails, is ambiguous, or needs broader product judgment, the issue moves to **Blocked** with a clear reason.
+
+Repair may edit conflict files and direct dependency-closure files required for validation. It must not push to the integration or production branch directly.
+
+## Example (target-app)
+
+```json
+{
+  "id": "target-app",
+  "targetRepo": "https://github.com/owner/example-target-app",
+  "baseBranch": "dev",
+  "productionBranch": "main",
+  "integrationPreviewUrl": "https://staging.example.com",
+  "productionUrl": "https://www.example.com",
+  "integrationSuccessStatus": "Merged to Dev",
+  "productionSuccessStatus": "Merged / Deployed"
+}
+```

package/workspace-snapshot/files/evals/README.md

@@ -0,0 +1,31 @@
+# Evals
+
+Human-readable readiness rubrics and eval contracts for the agentic product development harness.
+
+## v0.1 approach
+
+Evals start as **manual scorecards**, not automated test suites. Use [`templates/eval-scorecard.md`](../templates/eval-scorecard.md) to record pass / partial / fail / N-A per criterion with evidence and human sign-off.
+
+## Why manual first
+
+Automated evals are only useful when the criteria are stable. v0.1 runs against real issues (starting with the target repo) will reveal which criteria repeat and which are one-offs.
+
+## Future direction (planned)
+
+| Phase | Eval capability |
+|-------|-----------------|
+| v0.1 | Manual rubrics in markdown |
+| v0.3 eval contract | **Deferred** — manual rubrics remain; see [`docs/releases/v0.3.0.md`](../docs/releases/v0.3.0.md) |
+| Later | Optional automated checks (lint, tests, preview smoke) tied to scorecard rows |
+
+## What belongs here
+
+- Standard criteria sets by work type (when validated)
+- Example completed scorecards from real runs
+- Notes on criteria that failed or were ambiguous
+
+## What does not belong here yet
+
+- CI scripts or test runners
+- Auto-grading agents
+- Production gate enforcement

package/workspace-snapshot/files/examples/README.md

@@ -0,0 +1,32 @@
+# Examples
+
+Documented harness runs against real target repositories.
+
+## Available examples
+
+**Run 001 (target app):** [`runs/001-target-app-github-link/`](runs/001-target-app-github-link/) — manual v0.1 loop documented with artifacts and retrospective in [`docs/research/001-manual-run-retrospective.md`](../docs/research/001-manual-run-retrospective.md).
+
+## Target repo
+
+**Primary target:** [`owner/example-target-app`](https://github.com/owner/example-target-app)
+
+**Expected artifacts per run:**
+
+- Filled `linear-issue.md` (or equivalent issue export)
+- `implementation-plan.md`
+- `eval-scorecard.md`
+- `pr-readiness-report.md`
+- Short retrospective in `docs/research/`
+
+## What to include in an example
+
+- Issue summary and scope
+- What the agent changed (high level)
+- Eval results and open questions
+- What would change in templates or rubrics next time
+
+## What not to include
+
+- Secrets, tokens, or private URLs
+- Unreviewed code dumps
+- Claims that the run was fully automated

package/workspace-snapshot/files/examples/runs/001-target-app-github-link/README.md

@@ -0,0 +1,49 @@
+# Run 001: Target app GitHub link
+
+First manual v0.1 harness run against [`example-target-app`](https://github.com/owner/example-target-app).
+
+**Run status: completed** — merged and deployed. This proves one manual loop, not full harness automation.
+
+## Current status
+
+| Item | State |
+|------|-------|
+| Run | **Completed** |
+| PR | **Merged** — [#1](https://github.com/owner/example-target-app/pull/1) (squash merge) |
+| Main commit | `9a58a7e283b1bee07fc33894174830e2578e08b5` |
+| Feature branch | Kept — local and `origin/feat/target-app-github-link` |
+| Production deployment | **Success** — [Vercel deployment](https://vercel.com/kinterra-team-url/example-target-app/8TPFTiY79nviGt95rwFWMi2DVeqq) |
+| PM / product sign-off | **Pass** |
+| Retrospective | [`docs/research/001-manual-run-retrospective.md`](../../docs/research/001-manual-run-retrospective.md) |
+
+## Why this was chosen as the first v0.1 harness test
+
+- **Small, bounded scope** — one product surface (contact or footer), one outbound link, easy to eval.
+- **Real target-app value** — hiring managers reviewing the live site can reach the public repo without hunting on GitHub.
+- **Exercises the full loop** — issue → plan → repo inspection → implementation → eval → PR readiness → merge, without touching backend, auth, or case-study content.
+- **Forces repo discovery** — the implementation agent must inspect the target app codebase before choosing placement (contact vs footer) and matching existing link patterns.
+
+## What success means
+
+1. A GitHub link to `https://github.com/owner/example-target-app` appears in the appropriate contact/footer area. **Done** — contact section.
+2. The link is visually consistent, accessible, and does not break existing contact, resume, or LinkedIn behavior. **Done**
+3. Lint/build pass; scope stays narrow (no unrelated refactors). **Done**
+4. All run artifacts filled through merge and retrospective. **Done**
+5. Retrospective captured in `docs/research/` — **not** encoded as skills yet. **Done**
+
+## What should be learned before creating reusable skills
+
+See [`docs/research/001-manual-run-retrospective.md`](../../docs/research/001-manual-run-retrospective.md) for findings from this run.
+
+## Artifacts in this folder
+
+| File | Status |
+|------|--------|
+| [`linear-issue.md`](linear-issue.md) | Defined |
+| [`implementation-plan.md`](implementation-plan.md) | Execution complete — contact section placement confirmed |
+| [`eval-scorecard.md`](eval-scorecard.md) | Complete — all Pass; PM sign-off recorded |
+| [`pr-readiness-report.md`](pr-readiness-report.md) | Complete — merged and deployed |
+
+## Next step
+
+Plan **run 002** — see retrospective for suggested hypothesis. Do not create skills or automations until a second manual loop validates repeated patterns.

package/workspace-snapshot/files/examples/runs/001-target-app-github-link/eval-scorecard.md

@@ -0,0 +1,63 @@
+# Eval scorecard: Add GitHub link to site contact or footer
+
+<!-- Run 001 — complete; merged and deployed. Based on templates/eval-scorecard.md -->
+
+## Run metadata
+
+| Field | Value |
+|-------|-------|
+| Issue | [`linear-issue.md`](linear-issue.md) |
+| Target repo | `owner/example-target-app` |
+| Target local path | `/Users/weston/Code/example-target-app` |
+| Branch / PR | `feat/target-app-github-link` / [PR #1](https://github.com/owner/example-target-app/pull/1) — **merged** |
+| Feature commit | `1a4a4e3406bc9e8e7f86c85fc2660ad71263e92a` — Add GitHub contact link |
+| Main commit (post-merge) | `9a58a7e283b1bee07fc33894174830e2578e08b5` |
+| Production deployment | [Success](https://vercel.com/kinterra-team-url/example-target-app/8TPFTiY79nviGt95rwFWMi2DVeqq) |
+| Agent / executor | Cursor (manual v0.1 loop) |
+| Date | 2026-07-06 |
+
+## Scoring legend
+
+| Score | Meaning |
+|-------|---------|
+| **Pass** | Criterion fully met; evidence attached |
+| **Partial** | Mostly met; minor gaps documented |
+| **Fail** | Not met; blocks readiness |
+| **N/A** | Not applicable to this work type |
+
+## Criteria
+
+| # | Criterion | Score | Evidence |
+|---|-----------|-------|----------|
+| 1 | GitHub link exists and points to `https://github.com/owner/example-target-app` | **Pass** | Shipped on `main`; live in contact section |
+| 2 | Link is visually consistent with existing contact/social links | **Pass** | Card pattern; inline GitHub SVG (Lucide unavailable) — accepted at merge |
+| 3 | Link is accessible (keyboard focus, visible name or aria-label, sufficient contrast) | **Pass** | Manual inspection; no post-merge accessibility issues reported |
+| 4 | No existing contact, resume, or LinkedIn behavior breaks | **Pass** | Verified pre-merge and post-deploy |
+| 5 | `npm run lint` passes | **Pass** | Pre-merge |
+| 6 | `npm run build` passes | **Pass** | Pre-merge |
+| 7 | Scope stayed narrow — no unrelated file changes | **Pass** | Three files only |
+| 8 | Matches acceptance criteria from issue (placement, new tab, mobile check) | **Pass** | Contact section; production deployment success |
+
+## Known deviation (acceptable)
+
+| Deviation | Resolution |
+|-----------|------------|
+| Planned Lucide `Github` icon unavailable in `lucide-react@^1.20.0` | Inline GitHub SVG; merged and deployed without issue |
+
+## Summary
+
+- **Overall readiness:** **Complete** — merged, deployed, PM/product sign-off recorded
+- **Blocking failures:** None
+
+## Human sign-off
+
+- [x] PM / owner reviewed scorecard
+- Sign-off: Weston Uribe (PM/product)
+- Date: 2026-07-06
+
+## Follow-ups
+
+Carried to [`docs/research/001-manual-run-retrospective.md`](../../docs/research/001-manual-run-retrospective.md):
+
+- Add icon/library availability check to implementation plan template
+- Add explicit mobile viewport step to validation plan for UI runs

package/workspace-snapshot/files/examples/runs/001-target-app-github-link/implementation-plan.md

@@ -0,0 +1,79 @@
+# Implementation plan: Add GitHub link to site contact or footer
+
+<!-- Run 001 — PRELIMINARY. Human approval required before execution. Based on templates/implementation-plan.md -->
+
+## Issue reference
+
+- Issue: [`linear-issue.md`](linear-issue.md)
+- Target repo: `owner/example-target-app`
+- Target local path: `/Users/weston/Code/example-target-app`
+- Branch name (proposed): `feat/target-app-github-link`
+
+## Context
+
+Add a GitHub link so hiring managers can reach `https://github.com/owner/example-target-app` from the live target app site. Scope is limited to one new outbound link integrated with existing contact/social patterns.
+
+**This plan is preliminary.** The implementation agent **must inspect the target repo** before writing final file-level changes. Do not guess paths or components from the harness repo alone.
+
+## Required repo inspection (before implementation)
+
+The agent must determine:
+
+1. **Placement** — Whether the link belongs in the contact section, footer, or both (issue allows either; choose the pattern that matches how resume/LinkedIn are surfaced).
+2. **Source of truth** — Where site contact/social links are defined (e.g. `components/custom/contact-section.tsx`, `lib/content.ts`, footer layout, or similar).
+3. **Existing link patterns** — How external links are implemented (icons, labels, `target`, `rel`, styling utilities, marquees vs inline lists).
+4. **Validation commands** — What scripts exist in `package.json` (`lint`, `build`, `dev`) and any repo-specific checks in `AGENTS.md`.
+
+Document findings in this plan (update the **Files to touch** table) before making edits.
+
+## Approach (high level)
+
+1. **Inspect** — Read contact/footer components and content modules; list candidate insertion points.
+2. **Decide placement** — Pick contact, footer, or both; note rationale in PR description.
+3. **Implement** — Add GitHub link using the same pattern as existing social links (no new design language).
+4. **Validate** — Run lint/build; manual desktop + mobile check; verify resume/LinkedIn/contact unchanged.
+5. **Report back** — Update harness run artifacts (`eval-scorecard.md`, `pr-readiness-report.md`) in this repo after implementation.
+
+## Files to touch
+
+| File / area | Change |
+|-------------|--------|
+| _TBD after repo inspection_ | Add GitHub link entry and/or UI |
+| _TBD after repo inspection_ | Icon/asset if pattern uses SVG logos in `public/` |
+
+## Files explicitly out of scope
+
+- Case study routes under `app/work/`
+- Site narrative content unrelated to contact links
+- `next.config`, deployment config, env files
+- Harness repo (`agentic-product-development-harness`)
+- Dependencies unless an existing social icon pattern requires a shared asset only
+
+## Risks
+
+| Risk | Mitigation |
+|------|------------|
+| Wrong placement breaks visual hierarchy | Follow existing contact/footer structure; PM review on preview |
+| Duplicate links if both contact and footer add GitHub | Prefer single canonical placement unless site already duplicates social links in both |
+| Accessibility regression | Match focus/aria patterns from LinkedIn or resume links |
+| Broken external URL | Hard-code canonical repo URL; verify in browser |
+
+## Validation plan
+
+- [ ] Manual check: GitHub link visible in chosen section(s) on desktop and mobile
+- [ ] Manual check: Link opens correct repo in new tab
+- [ ] Manual check: Resume, LinkedIn, and contact behavior unchanged
+- [ ] `npm run lint` — pass
+- [ ] `npm run build` — pass
+- [ ] Preview URL review (local or Vercel) — PM sign-off
+
+## Rollback
+
+Revert the feature branch commit(s) or remove the added link entries and icon asset. No migrations or data changes expected.
+
+## Approval
+
+- [ ] Repo inspection complete; **Files to touch** table updated
+- [ ] Plan reviewed by human before execution
+- Approved by: _______________
+- Date: _______________

package/workspace-snapshot/files/examples/runs/001-target-app-github-link/linear-issue.md

@@ -0,0 +1,74 @@
+# Issue: Add GitHub link to site contact or footer
+
+<!-- Run 001 — manual v0.1 harness. Based on templates/linear-issue.md -->
+
+## Problem
+
+Hiring managers and technical reviewers visiting the live target app site cannot easily reach the public GitHub repository from the site. The repo was recently renamed and publicized (`owner/example-target-app`); the target app should surface that link where contact and professional links already live so reviewers can inspect code, commit history, and harness-related work without leaving the site context.
+
+## User / job story
+
+As a **hiring manager or technical reviewer**, I want **a clear GitHub link on the target app site** so that **I can open the public repository directly and evaluate how the candidate builds and documents product work**.
+
+## Acceptance criteria
+
+- [ ] A visible GitHub link is present in the target app **contact section and/or footer** (exact placement TBD after repo inspection).
+- [ ] The link URL is `https://github.com/owner/example-target-app`.
+- [ ] The link opens in a new tab with appropriate `rel` attributes (e.g. `noopener noreferrer`) consistent with other external links on the site.
+- [ ] Visual treatment matches existing contact/social link patterns (icon, label, spacing, hover/focus states).
+- [ ] Link is keyboard-focusable and has an accessible name (visible text and/or `aria-label` consistent with site patterns).
+- [ ] Existing contact, resume, and LinkedIn links continue to work unchanged.
+- [ ] `npm run lint` and `npm run build` pass in the target repo.
+
+## Out of scope
+
+- Changing copy or layout of unrelated unrelated site sections (hero, case studies, about narrative).
+- Adding links to other GitHub repos or private repositories.
+- Redesigning the entire contact or footer component.
+- Analytics, tracking, or new dependencies unless required by an existing link pattern.
+- Updating Vercel or GitHub repo settings.
+- Implementing harness automation, skills, or Linear integration.
+
+## Context and links
+
+- **Target repo (GitHub):** `owner/example-target-app`
+- **Target local path:** `/Users/weston/Code/example-target-app`
+- **Live site:** https://www.example.com (or local dev preview)
+- **Harness run folder:** `examples/runs/001-target-app-github-link/`
+- Related: repo rename from `wedge-1`; public repo readiness work on `main`
+
+## Product review method
+
+- **Primary:** Local preview via `npm run dev` in the target repo (desktop + mobile viewport).
+- **Optional:** Vercel preview URL on the PR branch for hiring-manager-style review.
+
+## Human approval gates
+
+| Gate | Owner | When |
+|------|-------|------|
+| Issue + preliminary plan approved | PM / product | Before implementation |
+| Implementation complete + scorecard | PM / product | Before PR |
+| Code review | Engineering | Before merge |
+| Product review on preview | PM / product | Before or with merge |
+
+## Eval hints
+
+Criteria for [`eval-scorecard.md`](eval-scorecard.md):
+
+| Criterion | Priority |
+|-----------|----------|
+| GitHub link exists and points to correct repo URL | Required |
+| Link visually consistent with existing social/contact links | Required |
+| Link accessible (focus, name, contrast) | Required |
+| No regression to contact / resume / LinkedIn | Required |
+| Lint and build pass | Required |
+| Scope stayed narrow (no drive-by changes) | Required |
+| Looks correct on mobile | Nice-to-have |
+
+## Definition of ready
+
+- [x] Problem and acceptance criteria are clear
+- [x] Out of scope is documented
+- [x] Target repo identified
+- [ ] PM / owner assigned for review — Weston Uribe
+- [ ] Implementation plan approved after target repo inspection