codex-genesis-harness 0.1.8 → 0.1.9

package/contracts/features/project-registry-schema.json

@@ -0,0 +1,37 @@
+{
+  "version": "1.0.0",
+  "description": "Contract for .planning/FEATURE_REGISTRY.json generated by the lifecycle pipeline.",
+  "required_root_fields": [
+    "version",
+    "updated_at",
+    "project_status",
+    "project_verification",
+    "features"
+  ],
+  "required_feature_fields": [
+    "id",
+    "status",
+    "title",
+    "path",
+    "verify_cmd",
+    "evidence",
+    "started_at",
+    "verified_at",
+    "attempts",
+    "last_error"
+  ],
+  "valid_statuses": [
+    "planned",
+    "in-progress",
+    "done",
+    "verified",
+    "deprecated"
+  ],
+  "valid_project_statuses": [
+    "implementation",
+    "verification",
+    "release-ready",
+    "completed"
+  ],
+  "completion_rule": "A feature may become verified only after verify_cmd exits 0 and explicit evidence is persisted. A project may become completed only after all features are verified and project verification has passed."
+}

package/contracts/observability/agent-run-schema.json

@@ -14,7 +14,7 @@
     "session_id": "string — unique identifier for the agent session (e.g. UUID or date-prefixed slug)",
     "timestamp": "ISO 8601 string",
     "skill": "string — name of the genesis skill invoked",
-    "phase": "string — one of: init, plan, execute, verify, handoff",
+    "phase": "string — one of: init, plan, execute, verify, handoff, release",
     "outcome": "string — one of: success, failure, partial, skipped",
     "evidence": "string — CLI output snippet or file path proving the outcome"
   },
@@ -25,6 +25,11 @@
     "recovery_needed": "boolean — whether a recovery point was consulted"
   },
   "changelog": [
+    {
+      "version": "1.1.0",
+      "date": "2026-06-12",
+      "change": "Added release phase for project completion records"
+    },
     {
       "version": "1.0.0",
       "date": "2026-06-03",

package/features/REGISTRY.md

@@ -35,10 +35,12 @@
 | F013 | verified | Feature Registry as harness primitive (L08) | `node tests/unit/feature_registry.test.js` | genesis-harness-engineering |
 | F014 | verified | npm pack / tarball smoke test | `bash scripts/run-evals.sh` | genesis-release |
 | F015 | verified | spec-impact-engine propagation chain | `bash scripts/verify.sh .codex/skills/spec-impact-engine` | spec-impact-engine |
-| F016 | in-progress | Cold-start test automation (L03) | `node scripts/cold-start-check.js` | genesis-harness |
+| F016 | verified | Cold-start test automation (L03) | `node scripts/cold-start-check.js` | genesis-harness |
 | F017 | planned | Per-session Time-to-First-Verification KPI (L06) | `node bin/genesis-harness.js status --ttfv` | genesis-harness |
-| F018 | planned | Scope ledger per task (L07) | `bash scripts/check-scope.sh` | genesis-harness |
-| F019 | verified | Demo Feature (Mockup + Contract + E2E) | `npm test` (or npx playwright test) | genesis-harness-engineering |
+| F018 | verified | Scope ledger per task (L07) | `bash scripts/check-scope.sh` | genesis-harness |
+| F019 | planned | Demo feature templates (mockup + contract + E2E) | `npx playwright test playwright/e2e/auth/login-screen.spec.js` | genesis-harness-engineering |
+| F020 | verified | Stateful feature lifecycle (`next` → evidence-gated `complete-feature`) | `node tests/integration/cli-smoke.test.js` | genesis-pipeline-orchestration |
+| F021 | verified | End-to-end multi-feature lifecycle with project verification, release-ready handoff, completion, event history, and audit | `node tests/integration/cli-smoke.test.js` | genesis-pipeline-orchestration |
 
 ---
 
@@ -47,10 +49,10 @@
 > Update this section after each CI run.
 
 ```
-Date: 2026-06-03T02:38:00Z
-scripts/verify.sh       → verify passed
-scripts/run-evals.sh    → evals passed
-feature_registry.test.js → feature_registry tests passed
+Date: 2026-06-12T09:50:17Z
+scripts/verify.sh         → verify passed
+scripts/run-evals.sh      → evals passed
+genesis-harness verify-gate → passed
 ```
 
 ---

package/fixtures/pipeline/end-to-end-project-lifecycle-fixture.md

@@ -0,0 +1,39 @@
+# End-to-End Project Lifecycle Fixture
+
+## Initial State
+
+- One feature is `in-progress`.
+- A second feature is added as `planned`.
+- Project state is `IMPLEMENTATION`.
+
+## Lifecycle
+
+```text
+complete active feature
+  -> mark active feature verified
+  -> promote next planned feature
+  -> keep project in IMPLEMENTATION
+
+complete final feature
+  -> mark feature verified
+  -> clear active feature
+  -> move project to VERIFICATION
+
+verify project
+  -> run every feature proof command
+  -> run project proof command
+  -> create project verification and handoff artifacts
+  -> move project to RELEASE_READY
+
+complete project
+  -> require RELEASE_READY
+  -> append final lifecycle event
+  -> move project to COMPLETED
+```
+
+## Invariants
+
+- Repeating a successful completion command is idempotent.
+- A failed proof command blocks the transition and increments failure metrics.
+- `pipeline-audit` fails on registry/state/artifact drift.
+- Every accepted transition is appended to `.runs/<session-id>/EVENTS.jsonl`.

package/fixtures/pipeline/feature-completion-fixture.md

@@ -0,0 +1,26 @@
+# Feature Completion Fixture
+
+## Given
+
+- `.codebase/state.json` records one `active_feature`.
+- `.planning/FEATURE_REGISTRY.json` records that feature as `in-progress`.
+- The caller supplies a verification command and an evidence summary.
+
+## When
+
+```sh
+genesis-harness complete-feature \
+  --verify-cmd "npm test" \
+  --evidence "All feature tests passed"
+```
+
+## Expected
+
+- The verification command exits `0`.
+- The registry feature status becomes `verified`.
+- `.planning/FEATURE_INDEX.md` marks the feature `[x]`.
+- State becomes `COMPLETED` and records feature lead-time metrics.
+- An observability run record is written.
+- The active `.runs/<session-id>` checkpoint is refreshed.
+
+If verification exits non-zero, completion is blocked and `failed_gate_count` increments.

package/fixtures/pipeline/run-to-feature-execution-fixture.md

@@ -0,0 +1,20 @@
+# Run To Feature Execution Fixture
+
+## Input
+
+- Command: `genesis-harness run --idea "<brief>" --yes ...`
+- Discovery answers: product approach, primary user, v1 outcome, QA owner, stack, deployment, and test strategy
+
+## Expected Output
+
+- `.planning/features/<NNN>-<slug>/` exists
+- `SPEC.md`, `PLAN.md`, `TEST_CONTRACT.md`, `TASKS.md`, `VERIFICATION.md`, and `DIAGRAM.mmd` are seeded for the first active slice
+- `contracts/ui/<feature>/screen-contract.json` exists when the first slice is UI-capable
+- `playwright/fixtures/<feature>-ui-fixture.md` exists when the first slice is UI-capable
+- `contracts/api/<feature>/request.json` and `response.json` exist when the first slice is API-capable
+- `fixtures/api/<feature>-api-fixture.md` exists when the first slice is API-capable
+- `.planning/FEATURE_INDEX.md` registers the active slice
+- `.planning/STATE.md` advances to `02 First Feature Execution`
+- `.codebase/state.json` advances to `IMPLEMENTATION`
+- `.runs/<session-id>/STATE.json` mirrors the same `IMPLEMENTATION` state and `active_feature`
+- `genesis-harness resume` reports the active feature and the next implementation task

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-genesis-harness",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Hệ thống quản trị (Harness) dành cho AI Agent (Codex) với cơ chế FSM State Persistence, Validation Gates và Test-First Workflow. Đảm bảo agent không bị trôi context.",
   "license": "MIT",
   "bin": {
@@ -29,8 +29,13 @@
     "playwright",
     "observability",
     "bin",
-    "scripts",
+    "scripts/*.js",
+    "scripts/*.sh",
+    "scripts/README.md",
+    "scripts/schema",
     "README.md",
+    "README.EN.md",
+    "README.VI.md",
     "LICENSE",
     "VERSION",
     "CHANGELOG.md"

package/scripts/check-repository-hygiene.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+"use strict";
+
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const repoRoot = path.resolve(__dirname, "..");
+const workTreeCheck = spawnSync("git", ["rev-parse", "--is-inside-work-tree"], {
+  cwd: repoRoot,
+  encoding: "utf8"
+});
+
+if (workTreeCheck.status !== 0) {
+  console.log("repository hygiene skipped: package is not inside a Git worktree");
+  process.exit(0);
+}
+
+const result = spawnSync("git", ["ls-files", "-z"], {
+  cwd: repoRoot,
+  encoding: "utf8"
+});
+
+if (result.status !== 0) {
+  console.error(result.stderr || "repository hygiene failed: git ls-files failed");
+  process.exit(result.status || 1);
+}
+
+const tracked = result.stdout.split("\0").filter(Boolean);
+const forbidden = tracked.filter(file =>
+  file === "node_modules"
+  || file.startsWith("node_modules/")
+  || file === "dist"
+  || file.startsWith("dist/")
+  || file.endsWith(".tgz")
+);
+
+if (forbidden.length > 0) {
+  console.error("repository hygiene failed: generated or dependency artifacts are tracked:");
+  for (const file of forbidden.slice(0, 20)) {
+    console.error(`- ${file}`);
+  }
+  if (forbidden.length > 20) {
+    console.error(`- ... and ${forbidden.length - 20} more`);
+  }
+  process.exit(1);
+}
+
+console.log("repository hygiene passed");

package/scripts/run-evals.sh

@@ -58,6 +58,7 @@ assert_contains "$repo_root/.codex-plugin/plugin.json" '"skills"'
 assert_contains "$repo_root/.codex-plugin/plugin.json" '"genesis-skill-set"'
 assert_contains "$repo_root/.codex-plugin/plugin.json" '$genesis-pipeline-orchestration'
 assert_contains "$repo_root/.codex-plugin/plugin.json" '$genesis-api-contract'
+assert_contains "$repo_root/.codex-plugin/plugin.json" 'implicit init'
 assert_not_contains "$repo_root/.codex-plugin/plugin.json" '$pipeline-orchestration-skill'
 assert_not_contains "$repo_root/.codex-plugin/plugin.json" '$api-contract-skill'
 assert_contains "$harness_dir/SKILL.md" '/genesis-init'
@@ -65,6 +66,13 @@ assert_contains "$repo_root/.codex/SKILLS_INDEX.md" '/genesis-init'
 assert_contains "$repo_root/bin/genesis-harness.js" 'genesis-harness docs-gate'
 assert_contains "$repo_root/bin/genesis-harness.js" 'check-docs-sync.sh'
 assert_contains "$repo_root/bin/genesis-harness.js" 'npx genesis-harness docs-gate'
+assert_contains "$repo_root/bin/genesis-harness.js" 'genesis-harness resume'
+assert_contains "$repo_root/bin/genesis-harness.js" 'genesis-harness next'
+assert_contains "$repo_root/bin/genesis-harness.js" 'genesis-harness add-feature'
+assert_contains "$repo_root/bin/genesis-harness.js" 'genesis-harness complete-feature'
+assert_contains "$repo_root/bin/genesis-harness.js" 'genesis-harness verify-project'
+assert_contains "$repo_root/bin/genesis-harness.js" 'genesis-harness complete-project'
+assert_contains "$repo_root/bin/genesis-harness.js" 'genesis-harness pipeline-audit'
 assert_contains "$harness_dir/scripts/check-docs-sync.sh" '.codebase/'
 assert_contains "$harness_dir/scripts/check-docs-sync.sh" 'README(\.[A-Z]{2})?\.md'
 assert_contains "$repo_root/.codebase/VISUAL_GRAPH.md" 'genesis-harness'
@@ -73,12 +81,23 @@ assert_contains "$repo_root/.codebase/PIPELINE_FLOW.md" 'contracts --> impl'
 assert_not_contains "$repo_root/.codebase/VISUAL_GRAPH.md" 'Đăng nhập'
 assert_not_contains "$repo_root/.codebase/VISUAL_GRAPH.md" 'src/auth.js'
 assert_contains "$repo_root/.codebase/IMPLEMENTATION_HANDOFF.md" 'Harness Drift Gate Hardening'
-assert_contains "$repo_root/.codebase/IMPLEMENTATION_HANDOFF.md" '2026-06-03'
 assert_not_contains "$repo_root/.codebase/IMPLEMENTATION_HANDOFF.md" '_[Name and reference]_'
 assert_not_contains "$repo_root/.codebase/IMPLEMENTATION_HANDOFF.md" 'Feature A'
 assert_not_contains "$repo_root/.codebase/IMPLEMENTATION_HANDOFF.md" 'YYYY-MM-DD'
-assert_contains "$repo_root/.codebase/state.json" '"completed_at": "2026-06-03'
-assert_contains "$repo_root/.codebase/CURRENT_STATE.md" '2026-06-03'
+node - "$repo_root/.codebase/state.json" <<'NODE'
+const fs = require("fs");
+const state = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
+if (state.current_state === "COMPLETED" && !state.completed_at) {
+  throw new Error("completed state must include completed_at");
+}
+if (state.current_state !== "COMPLETED" && Object.prototype.hasOwnProperty.call(state, "completed_at")) {
+  throw new Error("active state must not retain completed_at");
+}
+NODE
+assert_contains "$repo_root/.codebase/CURRENT_STATE.md" '**Time**: '
+assert_contains "$repo_root/.codebase/MODULE_INDEX.md" '.runs/'
+assert_not_contains "$repo_root/.codebase/CURRENT_STATE.md" '110/110 perfect score'
+assert_not_contains "$repo_root/.codebase/state.json" '"to": "EXECUTE"'
 assert_contains "$repo_root/.codebase/IMPLEMENTATION_HANDOFF.md" 'npm run eval'
 assert_not_contains "$repo_root/.codebase/IMPLEMENTATION_HANDOFF.md" 'rtk '
 assert_not_contains "$repo_root/.codebase/state.json" 'rtk '
@@ -106,6 +125,16 @@ assert_contains "$repo_root/package.json" '"playwright"'
 assert_contains "$repo_root/package.json" '"observability"'
 assert_contains "$repo_root/README.md" '.codex/skills/'
 
+plugin_version=$(node -p "require('$repo_root/.codex-plugin/plugin.json').version")
+package_version=$(node -p "require('$repo_root/package.json').version")
+[ "$plugin_version" = "$package_version" ] || fail "plugin version ($plugin_version) must match package version ($package_version)"
+
+[ "$(grep -c '^- `bin/genesis-harness.js`:' "$repo_root/.codebase/MODULE_INDEX.md")" -eq 1 ] \
+  || fail ".codebase/MODULE_INDEX.md must contain a single canonical bin/genesis-harness.js entry"
+
+[ "$(grep -c '^- `tests/integration/cli-smoke.test.js`:' "$repo_root/.codebase/TEST_MATRIX.md")" -eq 1 ] \
+  || fail ".codebase/TEST_MATRIX.md must describe cli-smoke in one canonical entry"
+
 for skill_name in "${skill_names[@]}"; do
   assert_contains "$repo_root/bin/genesis-harness.js" "$skill_name"
   assert_contains "$repo_root/scripts/install.sh" "$skill_name"
@@ -193,6 +222,8 @@ pack_tmp="$(mktemp -d)"
 npm pack --pack-destination "$pack_tmp" >/dev/null
 tarball_path=$(ls "$pack_tmp"/*.tgz | head -n 1)
 [ -f "$tarball_path" ] || fail "npm pack failed to produce tarball"
+tar tzf "$tarball_path" | grep -q '^package/scripts/bin/' \
+  && fail "packaged tarball must not include generated scripts/bin binaries"
 (
   cd "$pack_tmp"
   tar xzf "$tarball_path"
@@ -208,7 +239,9 @@ assert_contains "$repo_root/features/REGISTRY.md" "| id |"
 assert_contains "$repo_root/features/REGISTRY.md" "| status |"
 assert_contains "$repo_root/features/REGISTRY.md" "| verify_cmd |"
 assert_file "$repo_root/contracts/features/registry-schema.json"
+assert_file "$repo_root/contracts/features/project-registry-schema.json"
 assert_contains "$repo_root/contracts/features/registry-schema.json" '"required_columns"'
+assert_contains "$repo_root/contracts/features/project-registry-schema.json" '"completion_rule"'
 assert_contains "$repo_root/.codebase/MODULE_INDEX.md" "features/REGISTRY.md"
 
 # L11 — Observability Live Data

package/scripts/schema/001-init.sql

@@ -0,0 +1,129 @@
+-- Harness v0 schema — migration 001
+-- Durable layer for operational harness data.
+-- Policy docs (HARNESS.md, FEATURE_INTAKE.md, ARCHITECTURE.md) stay as
+-- human-readable references. This database stores the operational records
+-- that agents produce and query during work.
+
+PRAGMA journal_mode = WAL;
+PRAGMA foreign_keys = ON;
+
+----------------------------------------------------------------------
+-- Schema version
+----------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS schema_version (
+    version     INTEGER PRIMARY KEY,
+    applied_at  TEXT    NOT NULL DEFAULT (datetime('now'))
+);
+
+INSERT INTO schema_version (version) VALUES (1);
+
+----------------------------------------------------------------------
+-- Intake: classifying incoming work
+----------------------------------------------------------------------
+CREATE TABLE intake (
+    id            INTEGER PRIMARY KEY AUTOINCREMENT,
+    created_at    TEXT    NOT NULL DEFAULT (datetime('now')),
+    input_type    TEXT    NOT NULL
+                         CHECK(input_type IN (
+                           'new_spec','spec_slice','change_request',
+                           'new_initiative','maintenance','harness_improvement'
+                         )),
+    summary       TEXT    NOT NULL,
+    risk_lane     TEXT    NOT NULL
+                         CHECK(risk_lane IN ('tiny','normal','high_risk')),
+    risk_flags    TEXT,          -- JSON array, e.g. ["auth","data_model"]
+    affected_docs TEXT,          -- JSON array of doc paths
+    story_id      TEXT,          -- links to story.id when one is created
+    notes         TEXT
+);
+
+----------------------------------------------------------------------
+-- Story: work packets and their validation status
+-- Replaces hand-edited TEST_MATRIX.md rows.
+----------------------------------------------------------------------
+CREATE TABLE story (
+    id               TEXT PRIMARY KEY,   -- e.g. US-001
+    title            TEXT NOT NULL,
+    created_at       TEXT NOT NULL DEFAULT (datetime('now')),
+    risk_lane        TEXT NOT NULL
+                     CHECK(risk_lane IN ('tiny','normal','high_risk')),
+    contract_doc     TEXT,               -- path to product doc
+    status           TEXT NOT NULL DEFAULT 'planned'
+                     CHECK(status IN (
+                       'planned','in_progress','implemented','changed','retired'
+                     )),
+    unit_proof       INTEGER NOT NULL DEFAULT 0,
+    integration_proof INTEGER NOT NULL DEFAULT 0,
+    e2e_proof        INTEGER NOT NULL DEFAULT 0,
+    platform_proof   INTEGER NOT NULL DEFAULT 0,
+    evidence         TEXT,
+    notes            TEXT
+);
+
+----------------------------------------------------------------------
+-- Decision: durable records with optional verification
+----------------------------------------------------------------------
+CREATE TABLE decision (
+    id                    TEXT PRIMARY KEY,  -- e.g. 0001
+    title                 TEXT NOT NULL,
+    created_at            TEXT NOT NULL DEFAULT (datetime('now')),
+    status                TEXT NOT NULL DEFAULT 'proposed'
+                          CHECK(status IN (
+                            'proposed','accepted','superseded','rejected'
+                          )),
+    doc_path              TEXT,              -- path to the markdown ADR
+    verify_command        TEXT,              -- optional check command
+    last_verified_at      TEXT,
+    last_verified_result  TEXT
+                          CHECK(last_verified_result IN ('pass','fail') OR
+                                last_verified_result IS NULL),
+    predicted_impact      TEXT,
+    actual_outcome        TEXT,
+    notes                 TEXT
+);
+
+----------------------------------------------------------------------
+-- Backlog: harness improvement proposals with evidence loop
+----------------------------------------------------------------------
+CREATE TABLE backlog (
+    id                    INTEGER PRIMARY KEY AUTOINCREMENT,
+    created_at            TEXT    NOT NULL DEFAULT (datetime('now')),
+    title                 TEXT    NOT NULL,
+    discovered_while      TEXT,
+    current_pain          TEXT,
+    suggested_improvement TEXT,
+    risk                  TEXT    CHECK(risk IN ('tiny','normal','high_risk')),
+    status                TEXT    NOT NULL DEFAULT 'proposed'
+                          CHECK(status IN (
+                            'proposed','accepted','implemented','rejected'
+                          )),
+    predicted_impact      TEXT,
+    actual_outcome        TEXT,
+    implemented_at        TEXT,
+    notes                 TEXT
+);
+
+----------------------------------------------------------------------
+-- Trace: agent task execution records (observability foundation)
+----------------------------------------------------------------------
+CREATE TABLE trace (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    created_at      TEXT    NOT NULL DEFAULT (datetime('now')),
+    task_summary    TEXT    NOT NULL,
+    intake_id       INTEGER REFERENCES intake(id),
+    story_id        TEXT    REFERENCES story(id),
+    agent           TEXT,
+    actions_taken   TEXT,       -- JSON array
+    files_read      TEXT,       -- JSON array
+    files_changed   TEXT,       -- JSON array
+    decisions_made  TEXT,       -- JSON array
+    errors          TEXT,       -- JSON array
+    outcome         TEXT
+                    CHECK(outcome IN (
+                      'completed','blocked','partial','failed'
+                    )),
+    duration_seconds INTEGER,
+    token_estimate   INTEGER,
+    harness_friction TEXT,
+    notes            TEXT
+);

package/scripts/schema/002-story-verify.sql

@@ -0,0 +1,9 @@
+-- Harness v0 schema - migration 002
+-- Story-level mechanical verification.
+
+ALTER TABLE story ADD COLUMN verify_command TEXT;
+ALTER TABLE story ADD COLUMN last_verified_at TEXT;
+ALTER TABLE story ADD COLUMN last_verified_result TEXT
+    CHECK(last_verified_result IN ('pass','fail') OR last_verified_result IS NULL);
+
+INSERT INTO schema_version (version) VALUES (2);

package/scripts/schema/003-tool-registry.sql

@@ -0,0 +1,15 @@
+-- Harness v0 schema - migration 003
+-- Machine-readable registry for user-provided project tools.
+
+CREATE TABLE tool (
+    name           TEXT PRIMARY KEY,
+    created_at     TEXT NOT NULL DEFAULT (datetime('now')),
+    provider       TEXT NOT NULL DEFAULT 'custom',
+    command        TEXT NOT NULL,
+    description    TEXT NOT NULL,
+    args           TEXT,
+    responsibility TEXT NOT NULL,
+    since          TEXT NOT NULL DEFAULT 'registered'
+);
+
+INSERT INTO schema_version (version) VALUES (3);

package/scripts/schema/004-intervention.sql

@@ -0,0 +1,15 @@
+-- Harness v0 schema - migration 004
+-- Review, human, CI, or agent interventions separated from normal traces.
+
+CREATE TABLE intervention (
+    id          INTEGER PRIMARY KEY AUTOINCREMENT,
+    created_at  TEXT NOT NULL DEFAULT (datetime('now')),
+    trace_id    INTEGER REFERENCES trace(id),
+    story_id    TEXT,
+    type        TEXT NOT NULL CHECK(type IN ('correction','override','escalation','approval')),
+    description TEXT NOT NULL,
+    source      TEXT NOT NULL CHECK(source IN ('human','reviewer','ci','agent')),
+    impact      TEXT
+);
+
+INSERT INTO schema_version (version) VALUES (4);

package/scripts/transition_state.sh

@@ -1,5 +1,7 @@
 #!/bin/bash
 
+set -euo pipefail
+
 if [ -z "$1" ]; then
   echo "Usage: bash scripts/transition_state.sh <NEW_STATE> [Reason]"
   exit 1
@@ -30,14 +32,16 @@ const fs = require('fs');
 const file = '$STATE_FILE';
 const newState = '$NEW_STATE';
 const reason = '$REASON';
+const now = new Date().toISOString();
 
 const allowed = {
   'INIT': ['REQUIREMENTS_GATHERING', 'PLANNING'],
   'REQUIREMENTS_GATHERING': ['PLANNING'],
   'PLANNING': ['IMPLEMENTATION'],
   'IMPLEMENTATION': ['VERIFICATION', 'PLANNING'],
-  'VERIFICATION': ['COMPLETED', 'IMPLEMENTATION'],
-  'COMPLETED': ['INIT', 'REQUIREMENTS_GATHERING']
+  'VERIFICATION': ['RELEASE_READY', 'IMPLEMENTATION'],
+  'RELEASE_READY': ['COMPLETED', 'IMPLEMENTATION'],
+  'COMPLETED': ['INIT', 'REQUIREMENTS_GATHERING', 'IMPLEMENTATION']
 };
 
 let data = JSON.parse(fs.readFileSync(file, 'utf8'));
@@ -45,8 +49,18 @@ const current = data.current_state || 'INIT';
 
 if (allowed[current] && allowed[current].includes(newState)) {
   data.history = data.history || [];
-  data.history.push({ from: current, to: newState, reason: reason, timestamp: new Date().toISOString() });
+  data.history.push({ from: current, to: newState, reason: reason, timestamp: now, session_id: data.session_id || 'manual-transition' });
   data.current_state = newState;
+  data.session_started_at = data.session_started_at || now;
+  data.last_updated_at = now;
+  if (newState === 'COMPLETED') {
+    data.completed_at = now;
+    data.active_work = '';
+    data.pending_tasks = [];
+    data.latest_recovery_point = reason;
+  } else {
+    delete data.completed_at;
+  }
   fs.writeFileSync(file, JSON.stringify(data, null, 2));
   console.log('Transition successful: ' + current + ' -> ' + newState);
 } else {
@@ -56,11 +70,21 @@ if (allowed[current] && allowed[current].includes(newState)) {
 "
 
 if [ $? -eq 0 ]; then
-  echo "# Current State: $NEW_STATE" > "$CURRENT_STATE_MD"
-  echo "Last updated: $(date)" >> "$CURRENT_STATE_MD"
-  echo "" >> "$CURRENT_STATE_MD"
-  echo "## Reason" >> "$CURRENT_STATE_MD"
-  echo "$REASON" >> "$CURRENT_STATE_MD"
+  SESSION_ID=$(node -p "JSON.parse(require('fs').readFileSync('$STATE_FILE', 'utf8')).session_id || 'manual-transition'")
+  TTFV_SECONDS=$(node -p "JSON.parse(require('fs').readFileSync('$STATE_FILE', 'utf8')).ttfv_seconds || 0")
+  cat > "$CURRENT_STATE_MD" <<EOF
+# Current System State
+
+**Time**: $(date +%F)
+**Status**: \`$NEW_STATE\`
+**Latest Session**: \`$SESSION_ID\`
+**Time to First Verification (TTFV)**: ${TTFV_SECONDS}s
+
+## Latest Transition
+
+- State changed to \`$NEW_STATE\`
+- Reason: $REASON
+EOF
   exit 0
 else
   exit 1