codex-genesis-harness 0.1.7 → 0.1.9

package/.codebase/RECOVERY_POINTS.md

@@ -1,83 +1,85 @@
 # Recovery Points
 
-**Purpose**: Document where harness architecture implementation can be paused and resumed without losing context or creating inconsistencies.
-
-**Use When**: Evolution of the Codex harness (verification loops, CLI tools, scripts) needs to be paused, or when a rollback is necessary due to environment breakage.
-
----
-
-## Quick Reference: Current Recovery Points
-
-| Phase | Status | Resumption File | Last Updated |
-|-------|--------|-----------------|--------------|
-| TUI Mockup Viewer Integration | ✓ Complete | `.codebase/CURRENT_STATE.md` | 2026-06-01 |
-| Harness Verification Streamlining | ✓ Complete | `.codebase/CURRENT_STATE.md` | 2026-06-01 |
-| Bead Memory Regression Tests | ✓ Complete | `scripts/run-evals.sh` | 2026-06-01 |
-| Harness Engineering Overhaul | ⏸️ Idle (Stable) | `scripts/verify.sh` | 2026-06-01 |
-
----
-
-## Phase: Harness Verification Streamlining & Memory Evals
-
-**Status**: ✓ Complete  
-**Last Updated**: 2026-06-01  
-
-### What Happened
-
-- Cleaned up legacy/deprecated skills (e.g., `genesis-mvp-planning`, `genesis-release-orchestration`) from `scripts/verify.sh`, `scripts/uninstall.sh`, and `scripts/run-evals.sh`.
-- Removed hard-coded skill name mappings (`expected_name` switch statements), enabling dynamic mapping directly based on directory names.
-- Added test coverage in `run-evals.sh` for the local bead memory commands (`remember`, `recall`, `prime`, `forget`).
-- Enforced `state-machine.md` presence in `verify_harness_skill()`.
-
-### Safe State Confirmation
-
-The harness currently passes all structural tests cleanly.
-```bash
-# Verify structure
-./scripts/verify.sh
-
-# Verify regression
-./scripts/run-evals.sh
-
-# Dry-run package integrity
-npm run pack:check
-```
-
----
-
-## Rollback Points
-
-### If A Future Harness Evolution Breaks the CLI/Environment
-
-**Rollback Level 1: Last Stable Run (Current State)**
-If a new change to `bin/genesis-harness.js` or `scripts/verify.sh` creates infinite loops or immediate failures:
-```bash
-git checkout -- bin/genesis-harness.js scripts/verify.sh scripts/run-evals.sh
-npm install
-./scripts/verify.sh
-```
-
-**Rollback Level 2: Full Repository Reset**
-If tests are failing in a manner that contaminates local fixtures or memory:
-```bash
-git reset --hard HEAD
-git clean -fd
-npm install
-./scripts/verify.sh
-```
-
----
-
-## Checklist: Before Pausing Work on Harness Evolutions
-
-- [ ] `scripts/verify.sh` passing cleanly (Exit Code 0)
-- [ ] `scripts/run-evals.sh` passing cleanly (Exit Code 0)
-- [ ] Script files verified for POSIX/LF line endings
-- [ ] No uncommitted changes in core scripts that break existing workflows
-- [ ] `.codebase/CURRENT_STATE.md` updated with exact phase details
+A reverse-chronological log of stable states to return to if the current task corrupts the project.
 
 ---
 
-## Contact For Questions
-**Owner**: Codex Harness Engineering Team
-**Last Validated**: 2026-06-01
+## 2026-06-12: End-to-End Project Lifecycle
+- **Status**: Stable
+- **Git State**: Multi-feature orchestration, project verification, release-ready handoff, append-only events, and lifecycle audit are implemented and covered by integration tests.
+- **Why it's stable**: `cli-smoke.test.js` exercises idea bootstrap through two feature completions, project proof, final completion, idempotency, event history, and audit; the canonical `verify-gate` passes and is now the single completion gate.
+- **How to recover**: Use `.runs/<session-id>/STATE.json`, `RESUME.md`, and `EVENTS.jsonl`; run `pipeline-audit` before resuming the command reported by `next`.
+- **Files changed**: CLI, lifecycle state machine, project registry contract, pipeline fixtures/tests, orchestration skill, plugin prompt, README files, and repository memory.
+
+## 2026-06-12T16:50:17+07:00: Lifecycle Pipeline + Repository Hygiene
+- **Status**: Stable
+- **Git State**: Lifecycle and hygiene changes verified locally; tracked `node_modules/` entries are staged for removal while local installed dependencies remain available.
+- **Why it's stable**: `run --idea` creates a project feature registry, `next` resolves executable work, and `complete-feature` requires a passing command plus explicit evidence before closing state. Repository verification blocks tracked dependencies and generated package artifacts, while tarball smoke tests reject generated `scripts/bin/` binaries.
+- **How to recover**: Reapply this checkpoint if `.planning/FEATURE_REGISTRY.json` stops being generated, completion bypasses verification, evidence or metrics disappear, or `node_modules/` becomes tracked again.
+- **Files changed**: `bin/genesis-harness.js`, `scripts/check-repository-hygiene.js`, `scripts/verify.sh`, `scripts/run-evals.sh`, lifecycle contracts/fixtures/tests, README files, and `.codebase/*`.
+
+## 2026-06-10T10:05:00Z: Feature Execution Bootstrap
+- **Status**: Stable
+- **Git State**: Working tree verified after `run`/`resume` orchestration started auto-scaffolding the first execution-ready feature.
+- **Why it's stable**: `tests/integration/cli-smoke.test.js`, `scripts/verify.sh`, `scripts/run-evals.sh`, and `genesis-harness verify-gate` now cover the handoff from discovery into `IMPLEMENTATION` with `active_feature` persisted in `.runs/`.
+- **How to recover**: Reapply from this point if `run --idea` falls back to `PLANNING`, if `.planning/features/<NNN>-...` stops being created automatically, or if `resume` loses the active feature checkpoint.
+- **Files changed**: `bin/genesis-harness.js`, `tests/integration/cli-smoke.test.js`, `fixtures/pipeline/run-to-feature-execution-fixture.md`, and `.codebase/*.md`.
+
+## 2026-06-10T10:25:00Z: Typed First-Slice Contract Bootstrap
+- **Status**: Stable
+- **Git State**: Working tree verified after the first feature scaffold started emitting API/UI-specific contracts and fixtures.
+- **Why it's stable**: `run --idea` now creates `contracts/ui`, `contracts/api`, `playwright/fixtures`, and `fixtures/api` artifacts when the discovery answers imply those surfaces, and `tests/integration/cli-smoke.test.js` locks the generated paths and tailored values.
+- **How to recover**: Reapply from this point if the first feature loses typed contract scaffolding, if generated routes/endpoints regress to generic placeholders, or if `TEST_CONTRACT.md` stops referencing the generated contract paths.
+- **Files changed**: `bin/genesis-harness.js`, `tests/integration/cli-smoke.test.js`, `fixtures/pipeline/run-to-feature-execution-fixture.md`, `tests/fixtures/fixture-index.md`, and `.codebase/*.md`.
+
+## 2026-06-10T08:34:56Z: Workflow Consolidation + Trusted Publish Hardening
+- **Status**: Stable
+- **Git State**: Working tree verified after CI workflow consolidation, registry cleanup, and release-path hardening.
+- **Why it's stable**: GitHub Actions now reuse a single `verify-gate` path, release publishing expects OIDC trusted publishing with provenance, and workflow contract tests block drift back to placeholder CI logic.
+- **How to recover**: Reapply from this point if CI starts bypassing `verify-gate`, if docs-sync regains custom placeholder logic, or if npm publishing falls back to long-lived tokens and mutable CI version rewrites.
+- **Files changed**: `.github/workflows/*.yml`, `tests/unit/workflow_contracts.test.js`, `features/REGISTRY.md`, and `.codebase/*.md`.
+
+## 2026-06-10T16:45:00+07:00: Resume + Run Artifact Hardening
+- **Status**: Stable
+- **Git State**: Working tree verified after resumable run-artifact and state-invariant changes.
+- **Why it's stable**: `run` now writes per-session `.runs/<session-id>` artifacts, `resume` can backfill and report from them, and state metadata tests block stale timestamps.
+- **How to recover**: Reapply from this point if mid-project resume loses the next task, if `.runs/` stops being populated, or if `completed_at` drifts behind the active session.
+- **Files changed**: `bin/genesis-harness.js`, `.codebase/state.json`, `.codebase/*.md`, `scripts/run-evals.sh`, and CLI/unit test coverage.
+
+## 2026-06-10T14:20:00+07:00: Auto-init + Discovery Bootstrap
+- **Status**: Stable
+- **Git State**: Working tree verified after init bootstrap changes.
+- **Why it's stable**: `tests/integration/cli-smoke.test.js`, `scripts/verify.sh`, `scripts/run-evals.sh` (with temporary npm cache override), and `npm run pack:check` pass.
+- **How to recover**: Reapply from this point if init stops creating `.planning/INIT_QA.md`, `01-discovery-and-qa`, or `.codebase/PHASE_DEPENDENCY_MAP.md`.
+- **Files changed**: `bin/genesis-harness.js`, `init-planning.sh`, `genesis-harness` skill routing docs, and init smoke coverage.
+
+## 2026-06-10T14:55:00+07:00: Idea-Seeded Planner Bootstrap
+- **Status**: Stable
+- **Git State**: Working tree verified after brief-to-planning bootstrap changes.
+- **Why it's stable**: `init --idea "<brief>"` now fills planning docs and planner state, and verification still passes on `cli-smoke`, `verify.sh`, `run-evals.sh`, and `pack:check`.
+- **How to recover**: Reapply from this point if user brief content stops propagating into `PROJECT.md`, `REQUIREMENTS.md`, `STACK.md`, `SUMMARY.md`, or `.codebase/state.json`.
+- **Files changed**: `bin/genesis-harness.js`, `init-planning.sh`, `genesis-harness` prompt/routing docs, and init smoke coverage.
+
+## 2026-06-10T15:05:00+07:00: Runtime Pipeline + Verification Hardening
+- **Status**: Stable
+- **Git State**: Working tree verified after runtime pipeline, gate hardening, and metadata drift fixes.
+- **Why it's stable**: `genesis-harness run --idea ... --yes` now advances a blank repo into planning with persisted discovery answers, and `verify-gate` now matches the required completion contract.
+- **How to recover**: Reapply from this point if `run` stops filling planning docs, if `verify-gate` stops executing evals/docs/pack checks, or if plugin/package/state metadata drift returns.
+- **Files changed**: `bin/genesis-harness.js`, `init-planning.sh`, `.codex-plugin/plugin.json`, `.codebase/*.md`, `.codebase/state.json`, `scripts/run-evals.sh`, and CLI/unit/integration tests.
+
+## 2026-06-03T09:55:00+07:00: Full Score Harness Fix (110/110)
+- **Status**: Stable
+- **Git State**: Everything committed + new features added.
+- **Why it's stable**: All tests (`tests/unit/*.test.js`), `verify.sh`, `run-evals.sh`, and `cold-start-check.js` pass with exit code 0.
+- **How to recover**: `git reset --hard HEAD` (assuming commit happens immediately after this)
+- **Files added**: `features/REGISTRY.md`, `scripts/cold-start-check.js`, `scripts/check-scope.sh`, observability schemas/samples.
+
+## 2026-06-03T09:30:00+07:00: LeanCTX + CLI Postinstall Seed
+- **Status**: Stable
+- **Why it's stable**: `npm run verify` and `npm run eval` pass. `context-policy.json` successfully bootstrapped.
+- **How to recover**: Return to commit before the evaluation score fixes.
+
+## 2026-06-03T08:35:00+07:00: Harness Drift Gate Hardening
+- **Status**: Stable
+- **Why it's stable**: `npm run verify`, `npm run eval`, and `npm run pack:check` all pass.
+- **How to recover**: Revert to branch state before LeanCTX introduction.

package/.codebase/TECH_DEBT.md

@@ -0,0 +1,6 @@
+# Tech Debt Ledger
+
+This file logs structural rule violations, skipped tests, and out-of-scope modifications that were bypassed using `VIBE_MODE`.
+The AI and developers should periodically review this file to pay down technical debt.
+
+---

package/.codebase/TEST_MATRIX.md

@@ -2,10 +2,15 @@
 
 Required checks:
 
-- `scripts/verify.sh`: repository harness structure, skill metadata, contracts, fixtures, and harness smoke test.
-- `scripts/run-evals.sh`: install/verify/uninstall regression checks.
+- `scripts/verify.sh`: repository harness structure, skill metadata, contracts, fixtures, harness smoke test, and `SKILL.md` progressive-disclosure line limit.
+- `scripts/run-evals.sh`: install/verify/uninstall regression checks, manifest route checks, sync-generated Mermaid relationship checks, hook docs-gate checks, LeanCTX policy checks, handoff/state freshness checks, `tests/unit/*.test.js`, and `tests/integration/*.test.js`.
+- `tests/integration/cli-smoke.test.js`: package CLI smoke for install/postinstall LeanCTX seeding, deterministic idea bootstrap, resumable run artifacts, multi-feature queue promotion, evidence-gated feature completion, project-wide verification, release-ready handoff, idempotent project completion, append-only events, lifecycle audit, metrics, and observability output.
+- `tests/unit/repository_hygiene.test.js`: prevents tracked dependency or generated artifacts from returning.
+- `tests/unit/prompt_sentinel.test.js`: LeanCTX-backed prompt sentinel threshold and truncation behavior.
+- `tests/unit/state_metadata.test.js`: keeps `.codebase/CURRENT_STATE.md` and `.codebase/state.json` aligned for session, TTFV, legal state enums, and non-stale completion timestamps.
+- `tests/unit/verify_gate.test.js`: verifies that `verify-gate` includes evals, docs-gate, pack dry-run, and LeanCTX checks.
+- `tests/unit/workflow_contracts.test.js`: verifies CI workflows delegate to the reusable `verify-gate` path, pin critical actions, and use trusted npm publishing with provenance.
 - `npm run pack:check`: package contents dry-run.
 - Skill validation: run `quick_validate.py` for changed skills when available.
 
 Feature rule: add or update fixtures and expected output before implementation.
-

package/.codebase/VISUAL_GRAPH.md

@@ -0,0 +1,127 @@
+# Visual Project Graph
+
+## Harness Relationship Map
+
+```mermaid
+flowchart LR
+  manifest[".codex-plugin/plugin.json"] --> skills[".codex/skills/*"]
+  package["package.json"] --> cli["bin/genesis-harness.js"]
+  package --> verify["scripts/verify.sh"]
+  package --> evals["scripts/run-evals.sh"]
+  cli --> install["install / postinstall"]
+  cli --> hooks["setup-hooks"]
+  hooks --> docsgate["genesis-harness docs-gate"]
+  docsgate --> docsync["check-docs-sync.sh"]
+  docsgate --> specsync["check-spec-changelog.sh"]
+  skills --> contracts["contracts/"]
+  skills --> fixtures["fixtures/"]
+  skills --> tests["tests/ + playwright/"]
+  skills --> memory[".codebase/"]
+  verify --> skills
+  verify --> contracts
+  verify --> fixtures
+  verify --> memory
+  evals --> install
+  evals --> cli
+  evals --> unit["tests/unit/*.test.js"]
+  evals --> integration["tests/integration/*.test.js"]
+  evals --> pack["npm pack smoke"]
+```
+
+## Skill Workflow Relationships
+
+```mermaid
+flowchart TD
+  harness["genesis-harness"] --> planning["genesis-planning"]
+  harness --> research["genesis-research-first"]
+  planning --> architecture["genesis-architecture"]
+  planning --> api["genesis-api-contract"]
+  planning --> design["genesis-design-spec"]
+  api --> apisync["genesis-api-sync"]
+  design --> ui["genesis-ui-ux-test"]
+  api --> specimpact["spec-impact-engine"]
+  specimpact --> specprop["genesis-spec-propagation"]
+  specprop --> docs["genesis-docs-automation"]
+  ui --> verifybefore["genesis-verification-before-completion"]
+  apisync --> verifybefore
+  docs --> verifybefore
+  verifybefore --> release["genesis-release"]
+  harness --> memorymap["genesis-codebase-map"]
+  harness --> observability["genesis-observability-automation"]
+```
+
+## Code Dependency Hints
+
+```mermaid
+flowchart TD
+  "tests/integration/cli-smoke.test.js" --> "assert"
+  "tests/integration/cli-smoke.test.js" --> "fs"
+  "tests/integration/cli-smoke.test.js" --> "os"
+  "tests/integration/cli-smoke.test.js" --> "path"
+  "tests/integration/cli-smoke.test.js" --> "child_process"
+  "tests/unit/contract_integrity_gate.test.js" --> "assert"
+  "tests/unit/contract_integrity_gate.test.js" --> "fs"
+  "tests/unit/contract_integrity_gate.test.js" --> "path"
+  "tests/unit/contract_integrity_gate.test.js" --> "child_process"
+  "tests/unit/healing_telemetry.test.js" --> "assert"
+  "tests/unit/healing_telemetry.test.js" --> "fs"
+  "tests/unit/healing_telemetry.test.js" --> "path"
+  "tests/unit/healing_telemetry.test.js" --> "child_process"
+  "tests/unit/prompt_sentinel.test.js" --> "assert"
+  "tests/unit/prompt_sentinel.test.js" --> "fs"
+  "tests/unit/prompt_sentinel.test.js" --> "path"
+  "tests/unit/prompt_sentinel.test.js" --> "child_process"
+  "tests/unit/spec_visual_sync.test.js" --> "assert"
+  "tests/unit/spec_visual_sync.test.js" --> "fs"
+  "tests/unit/spec_visual_sync.test.js" --> "path"
+  "tests/unit/spec_visual_sync.test.js" --> "child_process"
+  "tests/unit/test_generator.test.js" --> "assert"
+  "tests/unit/test_generator.test.js" --> "fs"
+  "tests/unit/test_generator.test.js" --> "path"
+  "tests/unit/test_generator.test.js" --> "child_process"
+  "bin/genesis-harness.js" --> "fs"
+  "bin/genesis-harness.js" --> "path"
+  "bin/genesis-harness.js" --> "child_process"
+  "bin/genesis-harness.js" --> "@babel/parser"
+  "bin/genesis-harness.js" --> "@babel/traverse"
+  "bin/genesis-harness.js" --> "child_process"
+```
+
+## .planning/ROADMAP.md Derived Feature Status
+
+```mermaid
+graph TD
+  classDef completed fill:#d4edda,stroke:#28a745,stroke-width:2px;
+  classDef inprogress fill:#fff3cd,stroke:#ffc107,stroke-width:2px;
+  classDef pending fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
+  subgraph Role_0 ["Role: User"]
+    Task0["Roadmap task 0"]
+    class Task0 completed;
+    Task1["Roadmap task 1"]
+    class Task1 inprogress;
+    Task2["Roadmap task 2"]
+    class Task2 pending;
+  end
+  subgraph Role_1 ["Role: Admin"]
+    Task3["Roadmap task 3"]
+    class Task3 completed;
+    Task4["Roadmap task 4"]
+    class Task4 pending;
+    Task5["Roadmap task 5"]
+    class Task5 inprogress;
+  end
+  subgraph Role_2 ["Role: Analytics"]
+    Task6["Roadmap task 6"]
+    class Task6 pending;
+    Task7["Roadmap task 7"]
+    class Task7 pending;
+    Task8["Roadmap task 8"]
+    class Task8 inprogress;
+  end
+  Task0 --> Task1
+  Task0 --> Task2
+  Task2 --> Task4
+  Task2 --> Task5
+  Task4 --> Task6
+```
+

package/.codebase/context-policy.json

@@ -0,0 +1,68 @@
+{
+  "name": "leanctx-default",
+  "token_budget": 12000,
+  "_comment_token_budget": "Default conservative budget. Override in project .codebase/context-policy.json. For 128k-context models, set to 40000.",
+  "auto_scale": {
+    "enabled": false,
+    "note": "Set enabled=true and provide model_context_window to auto-calculate budgets. Formula: token_budget = model_context_window * 0.09 (9% for harness context leaves 91% for generation).",
+    "model_context_window": null,
+    "scale_factor": 0.09
+  },
+  "warn_at": 0.6,
+  "compact_at": 0.7,
+  "hard_stop_at": 0.85,
+  "layers": [
+    {
+      "name": "core",
+      "max_tokens": 2500,
+      "include": [
+        "AGENTS.md",
+        ".codex/SOUL.md",
+        ".codebase/CURRENT_STATE.md",
+        ".codebase/MODULE_INDEX.md",
+        ".codebase/TEST_MATRIX.md"
+      ]
+    },
+    {
+      "name": "active_context",
+      "max_tokens": 6500,
+      "include": [
+        ".codebase/COMPRESSED_CONTEXT.md",
+        ".codebase/VISUAL_GRAPH.md",
+        ".planning/STATE.md",
+        ".planning/ROADMAP.md",
+        "contracts/",
+        "fixtures/"
+      ]
+    },
+    {
+      "name": "deferred_reference",
+      "max_tokens": 3000,
+      "include": [
+        ".codex/skills/*/references/",
+        ".codex/skills/*/playbooks/",
+        ".codex/skills/*/checklists/",
+        "README*.md"
+      ]
+    }
+  ],
+  "defer_patterns": [
+    ".codex/skills/*/templates/**",
+    ".codex/skills/*/examples/**",
+    "playwright/**",
+    "observability/**",
+    "node_modules/**",
+    "dist/**",
+    "coverage/**"
+  ],
+  "portable_commands": [
+    "genesis-harness leanctx",
+    "genesis-harness sync",
+    "genesis-harness docs-gate",
+    "genesis-harness verify-gate",
+    "npm run verify",
+    "npm run eval",
+    "node scripts/cold-start-check.js"
+  ],
+  "wrapper_policy": "rtk optional when installed locally; public docs and CI must use portable commands."
+}

package/.codebase/memories/lessons_learned.md

@@ -0,0 +1,63 @@
+# Lessons Learned & Historical Bugs
+
+This file chronicles the major failures, recursive bugs, and architectural dead-ends we have encountered. It acts as an immune system preventing the agent from repeating history.
+
+## 1. Duplicate Slash Commands in Registry
+- **Symptom**: Agent registered 4 copies of the same slash command for a single skill.
+- **Root Cause**: The CLI script recursively scanned the entire `.codex/` directory for active skills, accidentally parsing backup folders (`.codex/backup/`) generated during skill upgrades.
+- **Resolution**: Backup directories must ALWAYS be placed completely outside the active parsed directory (e.g., moved to `~/.codex/backups` globally).
+- **Rule**: When doing file tree walks for plugins/skills, always explicitly ignore `.git`, `node_modules`, `backup`, and `tmp` folders.
+
+## 2. Documentation Drift & Broken Contracts
+- **Symptom**: Code in `scripts/` changed logic without updating `contracts/`.
+- **Root Cause**: Agent skipped the documentation step after a "quick fix" code edit.
+- **Resolution**: Implemented Validation Gates (`npm run verify`).
+- **Rule**: Never finalize a code edit without explicitly checking `TEST_MATRIX.md` and related schemas in `contracts/`. The validation gate will fail the build if it detects drift.
+
+## 3. Excessive Token Usage from `cat` and `ls`
+- **Symptom**: Context window flooded with massive minified bundle files or deep directory trees.
+- **Root Cause**: Using `cat` on large files or `ls -R` without filters.
+- **Resolution**: 
+- **Rule**: Always use the native `view_file`, `list_dir`, and `grep_search` tools with precise line bounds or search terms. NEVER `cat` a file directly in bash if a native agent tool exists.
+
+## 4. Init Must Not Depend On Explicit Slash Commands
+- **Symptom**: The harness stayed idle on a blank repo until the user typed `/init`, even when the user had already provided a product idea.
+- **Root Cause**: The entry skill documented `/init`, but the actual CLI/bootstrap path only exposed an explicit interactive command and did not scaffold discovery artifacts automatically.
+- **Resolution**: Treat "empty repo + user idea" as implicit init in `genesis-harness` docs, and make CLI `init` call `init-planning.sh` to create Foundation, Discovery/QA, and dependency-map artifacts.
+- **Rule**: For cold starts, initialize first, then ask the discovery/QA/tech-stack questions. Do not force the user to know the harness command vocabulary.
+
+## 5. Auto-init Must Preserve The User Brief
+- **Symptom**: Even after auto-init started running, the planner still dumped mostly `TBD` placeholders and lost the original idea unless the user repeated it.
+- **Root Cause**: Initialization created structure but did not treat the first user brief as durable bootstrap input.
+- **Resolution**: `genesis-harness init --idea "<brief>"` now seeds planning docs and planner state from the brief before follow-up QA begins.
+- **Rule**: The first user idea is a source artifact. Persist it into planning docs and state immediately, then ask only the missing clarification questions.
+
+## 6. Prompt Contracts Must Match Runtime Contracts
+- **Symptom**: Skill docs and plugin prompts said the harness could auto-init from an idea, but the executable runtime still depended on manual follow-up and incomplete verification gates.
+- **Root Cause**: Routing docs, plugin metadata, and gate definitions evolved separately from the actual CLI control flow.
+- **Resolution**: Add a deterministic `genesis-harness run --idea ... --yes` pipeline, make `verify-gate` execute the full completion bar, and add regression tests for both.
+- **Rule**: Do not describe a harness behavior in prompts or memory until there is a CLI/runtime path and a regression test that enforces it.
+
+## 7. Resume Requires Durable Session Artifacts, Not Just State Labels
+- **Symptom**: The harness could move into planning, but a later session still had to infer what to do next from scattered markdown because there was no canonical run checkpoint.
+- **Root Cause**: `.codebase/state.json` carried phase labels, but there was no per-session artifact bundle tying brief, discovery answers, and next tasks together.
+- **Resolution**: `run` now writes `.runs/<session-id>/INPUT.md`, `DISCOVERY.json`, `STATE.json`, and `RESUME.md`, and `resume` reads or backfills them from state.
+- **Rule**: Any harness phase that claims resumability must emit a durable per-session artifact bundle and a deterministic resume entrypoint.
+
+## 8. Discovery-Only Pipelines Still Break End-To-End Execution
+- **Symptom**: `run --idea` looked complete in docs, but it only stopped at "Create the first feature plan", forcing a human or later session to bridge the actual execution gap manually.
+- **Root Cause**: Discovery persistence existed, but there was no runtime handoff that turned approved scope into a concrete active feature scaffold.
+- **Resolution**: `run` now creates the first feature scaffold automatically, seeds spec/plan/test-contract/verification files, records `active_feature`, and advances resumable state into `IMPLEMENTATION`.
+- **Rule**: A harness pipeline is not end-to-end unless it leaves the next session inside an execution-ready slice with explicit tests, contracts, and verification steps already scaffolded.
+
+## 9. Generic Execution Scaffolds Still Leave Contract Work To Humans
+- **Symptom**: Even after execution bootstrap existed, the first feature slice still began with only generic planning files, so the next agent had to invent API/UI contracts and fixtures manually.
+- **Root Cause**: The runtime scaffold did not classify the first slice by surface area and did not reuse the repository's contract and fixture structure.
+- **Resolution**: The bootstrap now infers `ui`, `api`, or `full-stack` from discovery answers and emits typed artifacts in `contracts/ui/<feature>/`, `contracts/api/<feature>/`, `playwright/fixtures/`, and `fixtures/api/`.
+- **Rule**: If a harness claims contract-first execution, the first slice must already contain the concrete contract and fixture paths needed by the likely implementation surface.
+
+## 10. Feature Completion Is Not Project Completion
+- **Symptom**: The runtime could verify one active feature, but there was no repeatable queue promotion, project-wide proof rerun, release-ready handoff, or drift audit before marking the project done.
+- **Root Cause**: Feature lifecycle state and project lifecycle state were treated as the same boundary.
+- **Resolution**: Added a multi-feature registry, append-only lifecycle events, project-wide verification, a distinct `RELEASE_READY` state, evidence-gated project completion, and `pipeline-audit`.
+- **Rule**: A project may reach `COMPLETED` only after every feature is verified, all proof commands pass again at project scope, the handoff exists, and release or acceptance evidence is recorded.

package/.codebase/memories/preferences.md

@@ -0,0 +1,17 @@
+# Developer Preferences
+
+This file records the specific technical choices, preferences, and stylistic guidelines of the human developer for this repository. Adhere to these implicitly during code generation and problem-solving.
+
+## Technology Stack
+- **Primary Language**: JavaScript (Node.js for backend scripts). Keep code modern but compatible with Node >= 18.
+- **Testing**: Use standard Unix bash testing scripts (`verify.sh`, `run-evals.sh`) and standard Node asserts for unit testing unless specified otherwise.
+- **Frontend/UI**: When dealing with UI generation, prefer Vanilla CSS for precise control and maximum performance. Emphasize "WOW" factor, modern gradients, glassmorphism, and responsive layouts.
+
+## Architectural Choices
+- **Harness Engineering**: The system relies on state machines (FSM) and validation gates. Never skip a validation gate (`contract_integrity_gate.js`, `healing_telemetry.js`).
+- **File Integrity**: Ensure all metadata inside `.codebase/` and `contracts/` stays perfectly synchronized with any changes to actual codebase logic (`scripts/spec_visual_sync.js`).
+
+## Communication Style
+- Be concise, professional, and skip unnecessary pleasantries when delivering technical solutions.
+- Use GitHub Flavored Markdown for formatting logs, alerts, and instructions.
+- Provide Vietnamese localization in READMEs and user-facing artifacts where possible, as the user frequently requests Vietnamese communication.