diff --git a/.ai/harness/policy.json b/.ai/harness/policy.json index f6a6dc81..964b8b0f 100644 --- a/.ai/harness/policy.json +++ b/.ai/harness/policy.json @@ -1,392 +1,38 @@ { - "version": 1, "tasks": { - "lessons_file": "tasks/lessons.md", - "research_dir": "docs/researches", - "todo_file": "tasks/todos.md", - "contracts_dir": "tasks/contracts", - "reviews_dir": "tasks/reviews", - "notes_dir": "tasks/notes" + "research_dir": "docs/researches" }, "context": { "map_file": ".ai/context/context-map.json", - "capability_registry_file": ".ai/context/capabilities.json", - "capability_match_rule": "longest-prefix; same-length ambiguity fails", - "capability_source": "registry", - "capability_source_rule": "single authority selected by capability_source; registry reads .ai/context/capabilities.json, archcontext reads .archcontext/model/nodes/*.yaml; no dual-read and no fallback", - "profile": "stable-root-progressive-subdir", - "capability_resolver": "repo-harness run capability-resolver", - "capability_config": "repo-harness run capability-config", - "functional_block_selector": { - "script": "repo-harness run select-agent-context-blocks", - "config_file": ".ai/context/agent-context-blocks.txt", - "env": "REPO_HARNESS_CONTEXT_BLOCKS", - "rule": "compatibility selector; capability registry is the source of truth" - } + "capability_source": "registry" }, "worktree_strategy": { - "worktree_dir_template": "{{system_tmp}}/{{repo}}-wt-{{slug}}", "base_branch": "main", "review_base": "main", "merge_back": { - "target": "main", - "requires_clean_check": true, - "preserve_unrelated_changes": true + "target": "main" }, - "auto_on_conflict": true, - "auto_for_contract_tasks": true, - "branch_prefix": "codex/", - "start_script": "repo-harness run contract-worktree start --plan ", - "finish_script": "repo-harness run contract-worktree finish", - "cleanup_script": "repo-harness run contract-worktree cleanup --slug ", - "conflict_signals": [ - "dirty_worktree_overlaps_task_files", - "current_branch_not_suitable_for_task", - "existing_changes_unrelated_but_would_block_review", - "task_requires_clean_validation_surface" - ], - "validation_route": "waza:check" + "branch_prefix": "codex/" }, "harness": { - "policy_file": ".ai/harness/policy.json", - "helper_runtime_dir": ".ai/harness/scripts", - "helper_source": "package", - "checks_file": ".ai/harness/checks/latest.json", - "handoff_file": ".ai/harness/handoff/current.md", - "failure_log_file": ".ai/harness/failures/latest.jsonl", - "events_file": ".ai/harness/events.jsonl", - "runs_dir": ".ai/harness/runs", - "helper_compat_dir": "scripts", - "helper_package_dir": "assets/templates/helpers" - }, - "agent_runtime": { - "mode": "off", - "adapters": { - "herdr-cli-agent": { - "enabled": false - }, - "codex-app-thread": { - "enabled": false - } - } - }, - "operations": { - "dir": "deploy", - "private_dir": "_ops", - "rule": "commit deployment runbooks, submission materials, release checklists, helper scripts, ordered SQL files, and env examples under deploy/; keep deploy SQL in deploy/sql/ with 4-digit ascending prefixes; keep keys, tokens, real env values, provider state, artifacts, logs, and scratch files in ignored _ops/ only", - "tracked": [ - "deploy/README.md", - "deploy/scripts/", - "deploy/submissions/", - "deploy/runbooks/", - "deploy/release-checklists/", - "deploy/sql/", - "deploy/*.md", - "deploy/env/.env.example" - ], - "ignored": [ - "_ops/" - ] + "runs_dir": ".ai/harness/runs" }, + "operations": {}, "documentation": { - "profile": "minimal-agentic", - "language": "en", - "reference_source": "user-level-runtime-docs", - "reference_stub_marker": "", - "reference_resolver": "repo-harness docs path ", - "required": [ - "docs/spec.md", - "docs/architecture/index.md" - ], - "on_demand": [ - "docs/brief.md", - "docs/tech-stack.md", - "docs/decisions.md", - "docs/architecture.md", - "docs/packages.md" - ], - "reference_configs": [ - "harness-overview.md", - "agentic-development-flow.md", - "external-tooling.md", - "sprint-contracts.md", - "heartbeat-triage.md", - "handoff-protocol.md", - "document-generation.md", - "global-working-rules.md" - ], - "rule": "create optional docs only when the agent has concrete repo evidence or the user asks; docs/reference-configs contains repo-local pointer stubs while full generic runtime docs live in the user-level/package repo-harness install" - }, - "external_tooling": { - "herdr": { - "min_version": "0.9.0", - "release_assets": { - "linux-x86_64": { - "url": "https://github.com/herdrdev/herdr/releases/download/v0.9.0/herdr-linux-x86_64", - "sha256": "4fa1a01158dd8043da92d31b270780b0dcc10603038d9b61cac4d81ab63fb71f" - }, - "macos-aarch64": { - "url": "https://github.com/herdrdev/herdr/releases/download/v0.9.5/herdr-macos-aarch64", - "sha256": "fb77c2232a05a8035421382c894392f4174e4e38a18e48af3dd0290157c3a7e2" - }, - "macos-x86_64": { - "url": "https://github.com/herdrdev/herdr/releases/download/v0.9.5/herdr-macos-x86_64", - "sha256": "5fb0a908ec7f6745e3e245738b06bfad56c46391c391ab3c0955fbead01f1369" - } - } - }, - "routing": { - "simple": "waza" - }, - "hosts": [ - "claude-code", - "codex" - ], - "mode": "agent-readiness-required", - "detection": "init-migrate", - "readiness_gate": "repo-harness run check-agent-tooling --host codex --strict-readiness", - "waza": { - "source_repo": "tw93/Waza", - "source_url": "https://github.com/tw93/Waza.git", - "managed_skills": [ - "think", - "hunt", - "check", - "health" - ], - "primary_host": "codex", - "codex_primary_path": "~/.codex/skills", - "staging_cache_path": "~/.agents/skills", - "sync_mode": "stage-upstream-then-copy-to-codex", - "host_drift_policy": "report-per-host-version-staging-and-upstream-drift" - }, - "codex_automation_profile": { - "required_skills": [ - "health", - "check", - "mermaid" - ], - "optional_skills": [], - "mode": "codex-runtime-reference", - "source": "~/.codex/skills", - "routes": { - "workflow_health": "waza:health", - "review_gate": "waza:check", - "architecture_diagram": "mermaid" - }, - "vendoring_policy": "do-not-vendor-skill-body" - }, - "diagram_design": { - "skill_name": "mermaid", - "primary_host": "codex", - "codex_primary_path": "~/.codex/skills/mermaid", - "sync_mode": "external-installed-skill", - "vendoring_policy": "do-not-vendor" - }, - "codegraph": { - "package": "@colbymchenry/codegraph", - "primary_host": "both", - "install_mode": "target-aware-mcp", - "codex_config_path": "~/.codex/config.toml", - "claude_config_path": "~/.claude.json", - "index_dir": ".codegraph", - "readiness": "required-for-agent-code-navigation", - "hook_policy": "do-not-block-hooks", - "install_command": "bun add -g @colbymchenry/codegraph && repo-harness tools configure codegraph --target codex --location global", - "project_init_command": "codegraph init -i .", - "sync_command": "codegraph sync .", - "vendoring_policy": "do-not-add-package-dependency" - } - }, - "agentic_development": { - "routing": { - "product_discovery": "parent-agent:geju", - "complex_engineering_plan": "parent-agent:geju", - "design_plan": "parent-agent:geju", - "design_options_choice": "convention:design-options", - "small_or_medium_plan": "waza:think", - "bug_or_regression": "waza:hunt", - "post_implementation_review": "waza:check" - }, - "due_diligence": { - "levels": [ - "P1_GLOBAL_ARCHITECTURE", - "P2_DATA_FLOW_TRACE", - "P3_DESIGN_DECISION" - ], - "explicit_report_required_for": [ - "complex_engineering_plan", - "hunt", - "risky_refactor", - "deployment", - "auth_payment_data", - "shared_contract" - ] - } - }, - "circuit_breakers": { - "guard_repeat": 2, - "review": { - "lite": 1, - "standard": 1, - "strict": 2 - }, - "semantic_reviews_per_work_package": 1, - "subagents": { - "default": 2, - "strict_explicit_contract": 3 - }, - "repair_loops": 2, - "cross_model_consults_default": 0 - }, - "upgrade": { - "strategy_version": 1, - "remove_only_ownership": "known_generated", - "unknown_files": "preserve-or-archive", - "supported_legacy_versions": [ - "pre-tasks-first", - "tasks-first-without-contract-manifest", - "current-v1" - ], - "action_classes": { - "preserve": "keep user-authored hooks, ignored reference material, private operations state, secrets, and local env files unchanged", - "archive": "move user-authored legacy workflow documents or checklists into archive/research surfaces before refresh", - "reconfigure": "merge managed config defaults without overwriting explicit repo overrides", - "remove": "delete only workflow-contract actions marked ownership=known_generated" - }, - "cleanup": { - "source": ".ai/harness/workflow-contract.json#migrations.upgrade.actions", - "remove_only_ownership": "known_generated", - "unknown_files": "preserve-or-archive", - "custom_hooks": "preserve", - "ignored_reference_material": "preserve", - "local_operations_state": "preserve", - "local_secrets": "preserve" - }, - "reporting": { - "inspector_field": "upgrade_plan", - "dry_run_required": true - } + "language": "en" }, + "external_tooling": {}, "internal_pr_authors": [], - "development_campaign": { - "version": 1, - "mode": "off" - }, - "prds": { - "dir": "plans/prds", - "template_file": ".claude/templates/prd.template.md", - "statuses": [ - "Draft", - "Approved", - "Superseded" - ], - "rule": "PRDs live in plans/prds as the upper planning layer. They decompose docs/spec.md intent into product direction, acceptance scenarios, module behavior, data model, performance targets, and developer handoff. Sprints reference PRDs through Source PRD and decompose them into ordered execution backlogs." - }, - "sprints": { - "dir": "plans/sprints", - "active_marker_file": ".ai/harness/sprint/active-sprint", - "template_file": ".claude/templates/sprint.template.md", - "helper_script": "repo-harness run sprint-backlog", - "statuses": [ - "Draft", - "Approved", - "Executing", - "Done", - "Archived" - ], - "rule": "PRDs live in plans/prds as the upper planning layer. Sprints live in plans/sprints as long-task execution backlogs; each sprint row is expanded with Waza $think into a detailed plans/plan-*.md before the plan -> contract -> worktree flow; tasks/todos.md stays the deferred-goal ledger" - }, - "reference_material": { - "dir": "_ref", - "mode": "external-ignored", - "commit_policy": "never commit _ref contents", - "rule": "use _ref as an occasional ignored external reference checkout cache for upstream/source comparison only; refresh from external sources instead of editing as product code; when it influences a decision, cite the source repo plus commit/tag and path in tasks/notes/ or docs/researches/" - }, - "workstreams": { - "dir": "tasks/workstreams", - "scope": "capability", - "projection": "local-contract-active-pointer-and-current-slice", - "todo_projection": "tasks/todos.md", - "rule": "durable multi-session progress lives under tasks/workstreams//; current plan execution lives in the plan Task Breakdown; tasks/todos.md records deferred goals only" - }, "information_lifecycle": { - "notes": { - "dir": "tasks/notes", - "purpose": "task-local implementation decisions, deviations, tradeoffs, and open questions", - "promotion": "archive on workflow close; promote only repeated or durable findings" - }, - "evidence": { - "latest": ".ai/harness/checks/latest.json", - "snapshots_dir": ".ai/harness/runs", - "purpose": "raw verification records used to audit notes, reviews, and future promotion" - }, - "assets": { - "sources": [ - ".ai/harness/policy.json", - ".ai/harness/workflow-contract.json", - ".ai/hooks/", - "scripts/", - "docs/reference-configs/" - ], - "promotion_rule": "only promote patterns after verified reuse across tasks or fixtures" - }, - "memory": { - "sources": [ - "docs/researches/", - "tasks/lessons.md", - "gbrain" - ], - "rule": "memory is advisory; current repo state and evidence override summaries" - }, "external_knowledge": { - "default_brain_path": "brain//*", "project_path": "brain//*", "manifest_file": ".ai/harness/brain-manifest.json", - "drift_check": "repo-harness run check-brain-manifest", - "sync_script": "repo-harness run sync-brain-docs", - "hook_trigger": "PostToolUse Edit|Write for manifest entries with sync.direction=repo-to-brain", - "rule": "external knowledge stores long-lived explanations, runbooks, and patterns only; repo-local contracts, hooks, scripts, checks, and evidence remain authoritative", - "sync_rule": "only explicitly opted-in repo-to-brain manifest entries may be written to the default brain vault; pointer-only externalized stubs remain check-only" + "sync_script": "repo-harness run sync-brain-docs" } }, - "handoff_resume": { - "resume_packet_file": ".ai/harness/handoff/resume.md", - "global_handoff_dir": "~/.codex/handoffs", - "auto_start_new_session": false - }, "planning": { "pending_orchestration_file": ".ai/harness/planning/pending.json" }, - "sidecar_research": { - "default": true, - "output_dir": "docs/researches", - "preferred_runners": [ - "subagent", - "codex exec --json", - "main-thread trace" - ], - "spawn_decision": "main agent decides from task breadth, context impact, raw-log volume, and callable runner availability; do not ask the user for spawn confirmation", - "fallback_runner": "main-thread trace", - "main_thread_policy": "if spawning is not worthwhile or no sidecar runner is callable, perform bounded research in the main thread; consume conclusions and evidence paths, not raw logs" - }, - "lsp_profiles": { - "default": "typescript-lsp", - "selection": "functional-block-first", - "rule": "use block-level LSP/tooling hints before broad repo assumptions" - }, - "profiles": { - "orchestration": "shared-long-running-harness", - "evaluation": "browser-qa", - "handoff": "artifact-aware", - "recovery": "hybrid", - "state": "file-backed" - }, - "enforcement": { - "worktree_guard": "warn-by-default", - "verification_gate": "contract-and-review", - "completion_requires_checks": true - }, "publication": { "acceptance_merge": "on" } diff --git a/.ai/hooks/README.md b/.ai/hooks/README.md deleted file mode 100644 index 0f002d7a..00000000 --- a/.ai/hooks/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# Workflow Helpers - -Host events use the user-level `repo-harness-hook` typed runtime. Operator helpers run from the installed package: use `repo-harness run `. Init preserves legacy files under `.ai/hooks/lib/`. Run `repo-harness doctor` for migration guidance. diff --git a/.claude/templates/design-brief.template.md b/.claude/templates/design-brief.template.md deleted file mode 100644 index 649ea4a2..00000000 --- a/.claude/templates/design-brief.template.md +++ /dev/null @@ -1,134 +0,0 @@ -# Design Brief: {{TITLE}} -Optional document: use this template only when the task calls for it. Ordinary work records Goal / Scope / Changes / Verification / Risk / Rollback in the PR description. This document is not a merge permit. - -> **Status**: Draft -> **Slug**: {{SLUG}} -> **Owner**: {{OWNER}} -> **Date**: {{TIMESTAMP}} - - - -## Purpose & Audience - -- Page/surface: -- Primary audience: -- Job to be done: - -## UX Feature Guard - -- Requested outcome: -- Frozen behavior / rules that must not change: -- Requested action: -- Exact payload acted on (if none, write `N/A`): -- Forbidden extras / non-goals: - -### Role-aware User-visible Concept Boundary - -- Audience / role for this surface: -- Allowed visible concepts: -- Required outcome/recovery concepts that must stay visible: -- Backstage-only concepts that must never appear as user-visible: -- Role-gated exceptions, or `none`: -- Authority for each exception, or `N/A`: - -`UX-{{SLUG}}-N1` (the negative/non-goal scenario below) derives from the -backstage-only and non-goal fields above: it asserts that a backstage-only -concept or forbidden extra must NOT surface, not merely that some unrelated -input is invalid. - -### Authority & Reuse Map - -Name exact repo paths. A new surface needs a concrete mismatch or cross-module -invariant; “cleaner” and “easier” are not justification. - -| Responsibility / datum | Existing authority or reuse target | Decision (reuse / extend / new) | New-surface justification | -|------------------------|------------------------------------|---------------------------------|---------------------------| -| | | | | - -### Observable & Copy Contract - -- Happy/loading/empty states that can actually occur: -- Invalid/unavailable state: (what happened, where, next action) -- Machine-readable output contract, if any: (required presence and absence) -- Canonical copy source / sync sites: -- Fail-loud rule: (name the authoritative failure; no synthesized fallback) - -### BDD Acceptance Scenarios - -Write concrete Given/When/Then scenarios. These implement the frozen decisions; -they do not invent missing product rules. - -- Positive scenario ID + Given/When/Then: (`UX-{{SLUG}}-P1`) -- Negative / non-goal scenario ID + Given/When/Then: (`UX-{{SLUG}}-N1`) -- Authority-failure scenario ID + Given/When/Then: (`UX-{{SLUG}}-F1`) - -Carry these IDs unchanged into the task contract, test names/tags, and review -evidence. Those surfaces prove the scenarios; they do not redefine them. - -## Reference Sources (what to learn / what to avoid) - -Name concrete products, sites, or design systems — not vague adjectives. Mark unverifiable claims `[UNVERIFIED]`. - -| Source | Learn | Avoid | -|--------|----------------|-----------------| -| | | | - -## Color - -- Palette: -- Usage rules: (which color for which state/action; contrast/accessibility floor) - -## Typography - -- Typeface(s): -- Scale / weights: -- Language-specific notes: (for example CJK pairing, line-height) - -## Layout - -- Grid / breakpoints: -- Spacing scale: -- Key components and hierarchy: - -## Motion - -- Trigger -> effect pairs: -- Duration / easing: -- What must stay static: - -## Anti-patterns - -List concrete things this design must NOT do. Vague taste complaints ("it looks ugly") are not acceptable entries; name the specific pattern. - -- - -## Confirmation Checklist - -Check the applicable items when the task explicitly requests design approval; this checklist is not an ordinary sprint/contract completion gate. - -- [ ] Value proposition is clear -- [ ] Primary reference is decided -- [ ] Color is accurate to the reference -- [ ] Anti-pattern / don't list is explicit -- [ ] Motion spec is explicit -- [ ] Product rules/non-goals are frozen; instruction and payload are separate -- [ ] Existing component/domain authorities have exact reuse paths; every new surface is justified -- [ ] Positive, negative, and authority-failure Given/When/Then scenarios are explicit and fail loudly -- [ ] Role-aware visible/backstage-only concept boundary is explicit; `UX-{{SLUG}}-N1` matches a backstage-only or non-goal concept - -## Preview Attachment - -Optional. Reference an imagegen-generated preview or screenshot here; imagegen-type skills are enhancers for this brief, never a substitute for the checklist above. `design-proposal` can run the peer-research -> boundary-freeze -> STIMULUS-preview -> taste-refinement pipeline ahead of this section; it is an optional enhancer too, never a substitute for this brief or the Confirmation Checklist. - -- Preview path/link: diff --git a/.claude/templates/research.template.md b/.claude/templates/research.template.md deleted file mode 100644 index 5d46f2ec..00000000 --- a/.claude/templates/research.template.md +++ /dev/null @@ -1,25 +0,0 @@ -# {{PROJECT_NAME}} — Research Notes - -> **Last Updated**: {{DATE}} -> **Scope**: (what area of the codebase was researched) -> **Usage**: Store deep codebase findings and hidden contracts here, not in chat-only summaries. - -## Codebase Map -| File | Purpose | Key Exports | -|------|---------|-------------| - -## Architecture Observations -### Patterns & Conventions -### Implicit Contracts -### Edge Cases & Intricacies - -## Technical Debt / Risks - -## Research Conclusions -### What to Preserve -### What to Change -### Open Questions - -## Handoff Notes -### Evidence to Carry Forward -### Risks to Re-check diff --git a/.claude/templates/spec.template.md b/.claude/templates/spec.template.md deleted file mode 100644 index 510e8143..00000000 --- a/.claude/templates/spec.template.md +++ /dev/null @@ -1,31 +0,0 @@ -# Product Spec: {{PROJECT_NAME}} - -> **Status**: Draft -> **Last Updated**: {{TIMESTAMP}} -> **Owner**: Planner - -## Product Outcome - -Describe the stable user or operator outcome this repo should deliver. - -## Success Criteria - -- Primary workflow: -- Quality bar: -- Out of scope: - -## Constraints - -- Technical: -- Compliance: -- Delivery: - -## Acceptance Scenarios - -- Given - When - Then - -## Open Questions - -- ... diff --git a/.gitignore b/.gitignore index 6804c075..a2b63ebd 100644 --- a/.gitignore +++ b/.gitignore @@ -42,6 +42,7 @@ _ref/ !.archcontext/practices/ !.archcontext/projections/ .codegraph/ +.claude/.codegraph-state/ # Local operations state _ops/ @@ -54,43 +55,7 @@ _ops/ # OS metadata .DS_Store -# Runtime evidence and local agent state -.claude/settings.local.json -.claude/.atomic_pending -.claude/.session-handoff.md -.claude/.task-state.json -.claude/.task-handoff.md -.claude/*.tmp -.claude/*.bak -.claude/*.bak.* -.claude/*.backup-* -.ai/harness/checks/ -.ai/harness/checks/*.latest.json -.ai/harness/checks/*.latest.md -.ai/harness/events.jsonl -.ai/harness/archive/ -.ai/harness/backups/ -.ai/harness/failures/latest.jsonl -.ai/harness/standing-orders.md -.ai/harness/capability-context/ -.ai/harness/journal/ -.ai/harness/architecture-projection/ -.ai/harness/security/* -!.ai/harness/security/.gitkeep -.ai/harness/planning/* -!.ai/harness/planning/.gitkeep -.ai/harness/delegation/* -.ai/harness/architecture/events.jsonl -.ai/harness/active-worktree -.ai/harness/worktrees/ -.ai/harness/evidence/ -.ai/harness/runs/ -.ai/harness/state/ -.ai/harness/chatgpt/ -.ai/harness/handoff/gptpro/ -.ai/harness/mcp/ -.ai/harness/triage/* -!.ai/harness/triage/.gitkeep +# Host and tool directories .repo-harness/ .codex/* .claude/worktrees/ diff --git a/docs/architecture/archimap.html b/docs/architecture/archimap.html index bcf48e0c..0636914c 100644 --- a/docs/architecture/archimap.html +++ b/docs/architecture/archimap.html @@ -413,9 +413,9 @@

6.1k LOC of code outside every model footprint

R-A4 · Medium · stale references needs owner decision
-

Harness contract still names retired architecture paths

-

.ai/harness/policy.json and .ai/harness/workflow-contract.json declare the retired requests/snapshots/domains directories and require docs/architecture/index.md; .ai/context/capabilities.json points at deleted module pages. Byte projections of the repo-harness contract — not edited here (#434). Direction: refresh the contract from the repo-harness template.

-
.ai/harness/policy.json:332 · .ai/context/capabilities.json:15
+

Capability context still names deleted module pages

+

.ai/context/capabilities.json points at deleted module pages under docs/architecture/modules/. The repo-harness 0.32 refresh removed the docs/architecture/index.md requirement from .ai/harness/policy.json. Direction: refresh capabilities.json from the repo-harness template.

+
.ai/context/capabilities.json:15
R-A5 · Medium · model gap needs owner decision
diff --git a/docs/prds/prd.template.md b/docs/prds/prd.template.md deleted file mode 100644 index 5c53e425..00000000 --- a/docs/prds/prd.template.md +++ /dev/null @@ -1,172 +0,0 @@ -# PRD: {{PRD_TITLE}} - -> **Status**: Draft -> **Slug**: {{PRD_SLUG}} -> **Created**: {{TIMESTAMP}} -> **Updated**: {{TIMESTAMP}} -> **Source Spec**: `docs/spec.md` -> **Tier**: compact - - - -## AI Quick-Read Card - -- Problem: -- Users: -- Platform: -- P0 surface: -- Core metric: -- Hard constraint: -- Key risk: -- Unknowns: -- Acceptance scenarios: -- Suggested next step: - -## Problem - -### Product Direction - -- Hard Constraints: -- Recommended Defaults: -- Freedoms: - -### Feasibility Boundary - -- Confirmed: -- [UNKNOWN]: -- [UNVERIFIED]: - -## Users - -### Primary Users - -- User: - - Need: - - Success signal: - -### Secondary Users - -- User: - - Need: - - Success signal: - -## Success Criteria - -| Metric | Target | Measurement Method | Degradation Threshold | -|---|---:|---|---:| -| Example metric | 95% | Describe how to measure it | 90% | - -## Acceptance Scenarios - -### Scenario 1 - -- Given: -- When: -- Then: -- Machine-checkable evidence: - -### Scenario 2 - -- Given: -- When: -- Then: -- Machine-checkable evidence: - -### Scenario 3 (negative) - -- Given: -- When: -- Then (must NOT): -- Machine-checkable evidence: - -## Non-goals - -- - -## Module Behaviors (P0) - -### Module 1 - -- Purpose: -- Hard Constraints: -- Recommended Defaults: -- Freedoms: -- Normal path: -- Failure path 1: -- Failure path 2: -- States: - - Empty: - - Loading: - - Ready: - - Error: -- Dependencies: -- Open decisions: None - -## Data Model - -```jsonc -{ - "version": "1", - "entities": [ - { - "id": "example_entity", - "owner": "user", // who owns the data - "fields": { - "id": "string", // stable identifier - "created_at": "datetime" // creation timestamp - } - } - ], - "relationships": [] -} -``` - -## Performance Targets - -| Target | Number | Measurement Method | Degradation Threshold | -|---|---:|---|---:| -| Initial usable response | 2 seconds | Local stopwatch or automated timing | 4 seconds | - -## Known Unknowns - -| Item | Impact | Resolution Path | Owner | -|---|---|---|---| -| [UNKNOWN] Example unknown | Explain impact | Explain how to resolve | Maintainer | - -## Developer Handoff - -You are implementing this PRD. - -- Build first: -- Do not reinterpret: -- You may improve: -- Verify with: - -### Acceptance Scripts - -1. -2. -3. - -## Adjacent Patterns - -Required when the PRD prior-art trigger rule (`repo-harness-product` prd mode) hits (UI/taste, market-convention pattern, library/framework selection, architecture precedent, or an `[UNVERIFIED]` external assumption). Otherwise optional: use in standard tier or when explicitly requested. Prefer adjacent product patterns and common workflow debt. Do not name a competitor, API, platform limit, or package size unless the fact is sourced; otherwise mark it `[UNVERIFIED]`. - -## Commercialization Notes - -Use only when the request involves pricing, packaging, monetization, or buyer/user separation. - -## Frontend Perspective - -Use only when the frontend shape affects product behavior, state ownership, accessibility, or implementation risk. - -## Backend Perspective - -Use only when APIs, persistence, jobs, permissions, or data ownership affect product behavior or implementation risk.