agent-project-sdlc 0.1.24 → 0.1.26

package/assets/tools/validate_harness.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python3
 from harness_utils import (
+    harness_path,
     load_lifecycle,
     load_phase_contract_data,
     load_phase_contracts,
@@ -13,25 +14,27 @@ from harness_utils import (
 
 
 def main() -> None:
+    root = harness_path()
     required_files = [
         "AGENTS.md",
         "Makefile",
         ".docs/INDEX.md",
-        ".codex/state/lifecycle.yaml",
-        ".codex/state/plan.yaml",
-        ".codex/state/plan.draft.yaml",
-        ".codex/state/memory.md",
-        ".codex/pjsdlc_managed/templates/PLAN_TEMPLATE.yaml",
-        ".codex/pjsdlc_managed/policies/phase_contracts.yaml",
-        ".codex/pjsdlc_managed/policies/gates.yaml",
-        ".codex/pjsdlc_managed/policies/allowed_paths.yaml",
-        ".codex/pjsdlc_managed/policies/risk_matrix.yaml",
+        harness_path("state", "lifecycle.yaml"),
+        harness_path("state", "plan.yaml"),
+        harness_path("state", "plan.draft.yaml"),
+        harness_path("state", "memory.md"),
+        harness_path("pjsdlc_managed", "templates", "PLAN_TEMPLATE.yaml"),
+        harness_path("pjsdlc_managed", "policies", "phase_contracts.yaml"),
+        harness_path("pjsdlc_managed", "policies", "gates.yaml"),
+        harness_path("pjsdlc_managed", "policies", "allowed_paths.yaml"),
+        harness_path("pjsdlc_managed", "policies", "risk_matrix.yaml"),
         "tools/build_doc_overviews.py",
         "tools/validate_plan.py",
     ]
     required_dirs = [
         ".docs/00_raw",
         ".docs/01_product",
+        ".docs/02_experience",
         ".docs/02_architecture",
         ".docs/03_tech_plan",
         ".docs/04_implementation",
@@ -41,7 +44,7 @@ def main() -> None:
         ".docs/08_release",
         ".docs/09_runbooks",
         ".docs/rfc",
-        ".codex/skills",
+        harness_path("skills"),
         "tools",
     ]
     require_paths(required_files + required_dirs)
@@ -49,9 +52,9 @@ def main() -> None:
     lifecycle = load_lifecycle()
     phase_contract_data = load_phase_contract_data()
     phases = load_phase_contracts()
-    load_yaml(".codex/pjsdlc_managed/policies/gates.yaml")
-    load_yaml(".codex/pjsdlc_managed/policies/allowed_paths.yaml")
-    load_yaml(".codex/pjsdlc_managed/policies/risk_matrix.yaml")
+    load_yaml(harness_path("pjsdlc_managed", "policies", "gates.yaml"))
+    load_yaml(harness_path("pjsdlc_managed", "policies", "allowed_paths.yaml"))
+    load_yaml(harness_path("pjsdlc_managed", "policies", "risk_matrix.yaml"))
 
     current_phase = lifecycle.get("current_phase")
     require(current_phase in phases, f"Lifecycle current_phase is not declared: {current_phase}")
@@ -61,7 +64,7 @@ def main() -> None:
     for phase_name, contract in phases.items():
         skill = contract.get("skill")
         require(skill, f"{phase_name} missing skill")
-        skill_file = repo_path(f".codex/skills/{skill}/SKILL.md")
+        skill_file = repo_path(f"{root}/skills/{skill}/SKILL.md")
         require(skill_file.exists(), f"Missing skill file for {phase_name}: {skill_file.relative_to(repo_path('.'))}")
         require("inputs" in contract, f"{phase_name} missing inputs")
         require("outputs" in contract, f"{phase_name} missing outputs")

package/assets/tools/validate_plan_draft.py

@@ -3,7 +3,7 @@ from harness_utils import load_plan, require, run_main, validate_task_shape
 
 
 def main() -> None:
-    data = load_plan(".codex/state/plan.draft.yaml")
+    data = load_plan("<harnessRoot>/state/plan.draft.yaml")
     require("current_phase" not in data, "plan.draft.yaml must not define current_phase; lifecycle.yaml is the single source for current_phase")
     require("current_task_id" not in data, "plan.draft.yaml must not define current_task_id because drafts are not active task state")
     tasks = data.get("tasks", [])

package/assets/tools/validate_prompt_language.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 
 from pathlib import Path
 
-from harness_utils import ROOT, HarnessError, load_yaml, require, run_main
+from harness_utils import ROOT, HarnessError, harness_path, load_yaml, require, run_main
 
 
 SKILL_REQUIRED_SECTIONS = ["## 目的", "## 角色提示词", "## 输入", "## 规则", "## 完成检查"]
@@ -45,14 +45,6 @@ MACHINE_IDENTIFIERS = [
     "pending_revision",
 ]
 
-REQUIRED_AGENTS_TERMS = [
-    "Skill Language Contract",
-    "中文解释 + 英文精确标识符",
-    ".codex/state/lifecycle.yaml",
-    ".codex/state/plan.yaml",
-    "make validate-current",
-]
-
 YAML_KEYWORDS = {
     "lifecycle": [
         "project_name",
@@ -78,15 +70,23 @@ def text(path: Path) -> str:
 
 def validate_agents() -> None:
     content = text(ROOT / "AGENTS.md")
-    for term in REQUIRED_AGENTS_TERMS:
+    required_agents_terms = [
+        "Skill Language Contract",
+        "中文解释 + 英文精确标识符",
+        harness_path("state", "lifecycle.yaml"),
+        harness_path("state", "plan.yaml"),
+        "make validate-current",
+    ]
+    for term in required_agents_terms:
         require(term in content, f"AGENTS.md missing skill language contract term: {term}")
     for identifier in MACHINE_IDENTIFIERS:
         require(identifier in content, f"AGENTS.md should preserve machine identifier: {identifier}")
 
 
 def validate_skills() -> None:
-    skill_files = sorted((ROOT / ".codex/skills").glob("*/SKILL.md"))
-    require(skill_files, "No workflow skill files found under .codex/skills/")
+    skill_root = ROOT / harness_path("skills")
+    skill_files = sorted(skill_root.glob("*/SKILL.md"))
+    require(skill_files, f"No workflow skill files found under {skill_root.relative_to(ROOT)}/")
 
     for path in skill_files:
         content = text(path)
@@ -101,8 +101,8 @@ def validate_skills() -> None:
 
 
 def validate_skill_template() -> None:
-    path = ROOT / ".codex/pjsdlc_managed/templates/SKILL_TEMPLATE.md"
-    require(path.exists(), "Missing .codex/pjsdlc_managed/templates/SKILL_TEMPLATE.md")
+    path = ROOT / harness_path("pjsdlc_managed", "templates", "SKILL_TEMPLATE.md")
+    require(path.exists(), f"Missing {path.relative_to(ROOT)}")
     content = text(path)
     for section in SKILL_REQUIRED_SECTIONS:
         require(section in content, f"SKILL_TEMPLATE.md missing Chinese section: {section}")
@@ -111,9 +111,9 @@ def validate_skill_template() -> None:
 
 
 def validate_yaml_keys() -> None:
-    lifecycle = load_yaml(".codex/state/lifecycle.yaml")
-    tasks = load_yaml(".codex/state/plan.yaml")
-    phase_contracts = load_yaml(".codex/pjsdlc_managed/policies/phase_contracts.yaml")
+    lifecycle = load_yaml(harness_path("state", "lifecycle.yaml"))
+    tasks = load_yaml(harness_path("state", "plan.yaml"))
+    phase_contracts = load_yaml(harness_path("pjsdlc_managed", "policies", "phase_contracts.yaml"))
 
     for key in YAML_KEYWORDS["lifecycle"]:
         require(key in lifecycle, f"lifecycle.yaml key was removed or translated: {key}")

package/assets/tools/validate_rfc.py

@@ -48,6 +48,23 @@ SELF_TEST_TRIGGER_TERMS = [
     "阻塞",
 ]
 SELF_TEST_IMPACT_TERMS = ["development self-test impact", "开发自测影响"]
+UI_UX_TRIGGER_TERMS = [
+    "ui/ux",
+    "ux",
+    "screen",
+    "interaction",
+    "design.md",
+    "frontend",
+    "browser",
+    "page",
+    "visual",
+    "体验",
+    "屏幕",
+    "交互",
+    "视觉",
+    "前端",
+]
+UI_UX_IMPACT_TERMS = ["ui/ux impact", "体验影响"]
 
 
 def superseded_test_docs(docs) -> list[str]:
@@ -85,6 +102,7 @@ def main() -> None:
     invalid = [status for status in statuses if status not in allowed]
     require(not invalid, "Invalid RFC status: " + ", ".join(invalid))
     validate_development_self_test_impact(docs)
+    validate_uiux_impact(docs)
     print(f"RFC artifacts OK: {len(docs)} file(s)")
 
 
@@ -101,6 +119,19 @@ def validate_development_self_test_impact(docs) -> None:
             )
 
 
+def validate_uiux_impact(docs) -> None:
+    for doc in docs:
+        number = rfc_number(doc.name)
+        if number is not None and number < 27:
+            continue
+        text = doc.read_text(encoding="utf-8")
+        if contains_any(text, UI_UX_TRIGGER_TERMS):
+            require(
+                contains_any(text, UI_UX_IMPACT_TERMS),
+                f"{doc.relative_to(repo_path('.')).as_posix()} must include UI/UX Impact when RFC changes experience docs, screen contracts, DESIGN.md, frontend, or browser behavior",
+            )
+
+
 def rfc_number(file_name: str) -> int | None:
     match = re.match(r"^RFC[_-](\d+)", file_name, re.IGNORECASE)
     return int(match.group(1)) if match else None

package/assets/tools/validate_test_plan.py

@@ -1,4 +1,7 @@
 #!/usr/bin/env python3
+import re
+from typing import Optional
+
 from harness_utils import (
     changed_files,
     contains_any,
@@ -13,7 +16,9 @@ from harness_utils import (
 )
 
 TEST_REPORT_PATH = ".docs/07_test/TEST_REPORT.md"
+TEST_CASES_PATH = ".docs/07_test/TEST_CASES.md"
 PLACEHOLDER_TERMS = ["pending", "tbd", "todo", "待填", "待补", "placeholder"]
+CASE_ID_RE = re.compile(r"\bTC-\d{3,}\b")
 MISSING_READINESS_TERMS = [
     "missing entry",
     "missing exit",
@@ -44,6 +49,10 @@ MISSING_READINESS_TERMS = [
 ]
 
 
+def as_list(value) -> list:
+    return value if isinstance(value, list) else []
+
+
 def read_test_report() -> tuple[str, str]:
     require(
         repo_path(TEST_REPORT_PATH).exists(),
@@ -52,8 +61,115 @@ def read_test_report() -> tuple[str, str]:
     return read_text(TEST_REPORT_PATH), TEST_REPORT_PATH
 
 
+def test_case_refs(text: str) -> list[str]:
+    return sorted(set(CASE_ID_RE.findall(text)))
+
+
+def plan_references_test_cases(plan: dict) -> bool:
+    for task in as_list(plan.get("tasks")):
+        if not isinstance(task, dict):
+            continue
+        if str(task.get("phase") or "") != "TESTING":
+            continue
+        refs = [str(item) for item in as_list(task.get("result_docs"))]
+        if TEST_CASES_PATH in refs:
+            return True
+    return False
+
+
+def split_markdown_row(line: str) -> list[str]:
+    return [cell.strip() for cell in line.strip().strip("|").split("|")]
+
+
+def is_separator_row(line: str) -> bool:
+    stripped = line.strip()
+    return stripped.startswith("|") and set(stripped.replace("|", "").strip()) <= {"-", ":", " "}
+
+
+def find_table_header(lines: list[str], row_index: int) -> Optional[list[str]]:
+    for index in range(row_index - 1, 0, -1):
+        if not is_separator_row(lines[index]):
+            continue
+        header = lines[index - 1]
+        if header.strip().startswith("|"):
+            return split_markdown_row(header)
+    return None
+
+
+def header_index(headers: list[str], *terms: str) -> Optional[int]:
+    lowered = [header.lower() for header in headers]
+    for index, header in enumerate(lowered):
+        if any(term in header for term in terms):
+            return index
+    return None
+
+
+def required_cell(cells: list[str], index: Optional[int]) -> str:
+    if index is None or index >= len(cells):
+        return ""
+    return cells[index].strip()
+
+
+def validate_test_cases(text: str, report_text: str) -> list[str]:
+    errors: list[str] = []
+    if contains_any(text, PLACEHOLDER_TERMS):
+        errors.append("TEST_CASES.md must not contain pending/TBD/TODO/placeholder content")
+
+    lines = text.splitlines()
+    rows: list[tuple[int, list[str], list[str]]] = []
+    for index, line in enumerate(lines):
+        if not line.strip().startswith("|") or not CASE_ID_RE.search(line):
+            continue
+        header = find_table_header(lines, index)
+        if header is None:
+            errors.append("TEST_CASES.md cases must be listed in a Markdown table with headers")
+            continue
+        rows.append((index + 1, header, split_markdown_row(line)))
+
+    ids = [CASE_ID_RE.search("|".join(cells)).group(0) for _, _, cells in rows if CASE_ID_RE.search("|".join(cells))]
+    if not ids:
+        errors.append("TEST_CASES.md must include at least one TC-* case")
+    duplicates = sorted({case_id for case_id in ids if ids.count(case_id) > 1})
+    if duplicates:
+        errors.append(f"TEST_CASES.md Case ID must be unique: {', '.join(duplicates)}")
+
+    for line_number, headers, cells in rows:
+        requirement = header_index(headers, "requirement", "risk", "需求", "风险")
+        runnable_entry = header_index(headers, "runnable entry", "runnable", "entry", "入口")
+        steps = header_index(headers, "steps", "步骤")
+        expected_exit = header_index(headers, "expected exit", "expected result", "expected", "预期", "出口")
+        missing = []
+        if not required_cell(cells, requirement):
+            missing.append("Requirement / Risk Ref")
+        if not required_cell(cells, runnable_entry):
+            missing.append("Runnable Entry")
+        if not required_cell(cells, steps):
+            missing.append("Steps")
+        if not required_cell(cells, expected_exit):
+            missing.append("Expected Exit")
+        if missing:
+            errors.append(f"TEST_CASES.md row {line_number} missing required case fields: {', '.join(missing)}")
+
+    refs = test_case_refs(report_text)
+    missing_refs = sorted(set(refs) - set(ids))
+    if missing_refs:
+        errors.append(f"TEST_REPORT.md references case IDs not found in TEST_CASES.md: {', '.join(missing_refs)}")
+    return errors
+
+
+def validate_test_cases_if_needed(plan: dict, report_text: str) -> None:
+    cases_path = repo_path(TEST_CASES_PATH)
+    should_validate = bool(test_case_refs(report_text)) or plan_references_test_cases(plan) or cases_path.exists()
+    if not should_validate:
+        return
+    require(cases_path.exists(), f"Missing test cases: expected {TEST_CASES_PATH} because TEST_REPORT.md or current TESTING task references test cases")
+    for error in validate_test_cases(read_text(TEST_CASES_PATH), report_text):
+        require(False, error)
+
+
 def main() -> None:
-    validate_plan_contract(load_plan(), allow_open=False)
+    plan = load_plan()
+    validate_plan_contract(plan, allow_open=False)
     text, source = read_test_report()
     require(
         not contains_any(text, PLACEHOLDER_TERMS),
@@ -72,6 +188,7 @@ def main() -> None:
             not contains_any(text, MISSING_READINESS_TERMS),
             "Test report cannot PASS while runnable entry/exit or Development Evidence is missing; use BLOCKED with recovery conditions",
         )
+    validate_test_cases_if_needed(plan, text)
     if load_lifecycle().get("current_phase") == "TESTING":
         for error in testing_boundary_errors_for_changed_files(changed_files()):
             require(False, error)

package/assets/tools/validate_uiux_design.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+import json
+import subprocess
+
+from harness_utils import (
+    contains_any,
+    load_lifecycle,
+    load_plan,
+    markdown_deliverables,
+    repo_path,
+    run_main,
+    require,
+    validate_plan_contract,
+)
+
+
+DESIGN_MD = "DESIGN.md"
+
+
+def main() -> None:
+    lifecycle = load_lifecycle()
+    plan = load_plan()
+    validate_plan_contract(plan, allow_open=lifecycle.get("current_phase") != "UI_UX_DESIGNING")
+
+    docs = markdown_deliverables(".docs/02_experience")
+    require(docs, "No UI/UX deliverables found in .docs/02_experience/")
+    visual_ui = False
+    for doc in docs:
+        text = doc.read_text(encoding="utf-8")
+        relative = doc.relative_to(repo_path(".")).as_posix()
+        not_applicable = contains_any(text, ["applicability: not_applicable", "applicability: `not_applicable`"])
+        visual_ui = visual_ui or contains_any(text, ["applicability: visual_ui", "applicability: `visual_ui`"])
+        if not_applicable:
+            continue
+        require(contains_any(text, ["prd", "requirement", "需求"]), f"{relative} must cite PRD and requirement IDs")
+        require(contains_any(text, ["user journey", "user journeys", "用户旅程"]), f"{relative} must include user journeys")
+        require(contains_any(text, ["handoff matrix", "交接矩阵"]), f"{relative} must include a handoff matrix")
+        require(
+            contains_any(text, ["loading", "empty", "error", "success", "permission", "加载", "空状态", "错误", "成功", "权限"]),
+            f"{relative} screen contracts must cover applicable loading/empty/error/success/permission states",
+        )
+        require(contains_any(text, ["responsive", "breakpoint", "响应式", "断点"]), f"{relative} must include responsive acceptance")
+        require(
+            contains_any(text, ["accessibility", "a11y", "focus", "keyboard", "touch", "无障碍", "焦点", "键盘", "触控"]),
+            f"{relative} must include accessibility/focus/keyboard/touch expectations",
+        )
+
+    if visual_ui:
+        design_path = repo_path(DESIGN_MD)
+        require(design_path.exists(), "visual UI experience requires root DESIGN.md")
+        validate_design_md()
+
+    print(f"UI/UX artifacts OK: {len(docs)} experience deliverable(s)")
+
+
+def validate_design_md() -> None:
+    command = designmd_command()
+    try:
+        proc = subprocess.run(
+            command + ["lint", DESIGN_MD],
+            cwd=repo_path("."),
+            text=True,
+            capture_output=True,
+            check=False,
+        )
+    except FileNotFoundError:
+        require(False, "DESIGN.md linter not found; install @google/design.md or run npm install")
+        return
+
+    output = (proc.stdout or "").strip()
+    diagnostics = None
+    if output:
+        try:
+            diagnostics = json.loads(output)
+        except json.JSONDecodeError:
+            diagnostics = None
+
+    errors = []
+    if isinstance(diagnostics, dict):
+        summary = diagnostics.get("summary") if isinstance(diagnostics.get("summary"), dict) else {}
+        if int(summary.get("errors") or 0) > 0:
+            errors.append("DESIGN.md linter reported errors")
+        for finding in diagnostics.get("findings") or []:
+            if isinstance(finding, dict) and str(finding.get("severity") or "").lower() == "error":
+                errors.append(str(finding.get("message") or "DESIGN.md linter error"))
+    elif proc.returncode != 0:
+        errors.append((proc.stderr or proc.stdout or "DESIGN.md linter failed").strip())
+
+    if errors:
+        require(False, "; ".join(errors))
+
+
+def designmd_command() -> list[str]:
+    local_bin = repo_path("node_modules/.bin/designmd")
+    if local_bin.exists():
+        return [str(local_bin)]
+    return ["npx", "--no-install", "designmd"]
+
+
+if __name__ == "__main__":
+    run_main(main)

package/dist/commands/index.js

@@ -1,4 +1,5 @@
 import { doctor } from "./doctor.js";
+import { inspectWorkflow } from "./inspect-workflow.js";
 import { init } from "./init.js";
 import { packageSource } from "./package-source.js";
 import { sync } from "./sync.js";
@@ -10,11 +11,13 @@ export const commands = {
     sync,
     upgrade,
     doctor,
+    "inspect-workflow": inspectWorkflow,
     validate,
     "validate-harness": (args) => validate(["validate-harness", ...args]),
     "validate-current": (args) => validate(["validate-current", ...args]),
     "validate-plan": (args) => validate(["validate-plan", ...args]),
     "validate-pm": (args) => validate(["validate-pm", ...args]),
+    "validate-uiux": (args) => validate(["validate-uiux", ...args]),
     "validate-design": (args) => validate(["validate-design", ...args]),
     "validate-dev": (args) => validate(["validate-dev", ...args]),
     "validate-review": (args) => validate(["validate-review", ...args]),
@@ -30,7 +33,8 @@ export function help() {
   sync                 Materialize canonical assets into the workspace
   upgrade              Run migrations and then sync
   doctor               Diagnose project configuration and drift
+  inspect-workflow     Lightly inspect workflow weight, fact-source drift, and handoff clarity
   validate <gate>      Run a Harness validation gate
-  validate-*           Run a named gate directly, including validate-plan/review/test/release/rfc
+  validate-*           Run a named gate directly, including validate-plan/uiux/design/dev/review/test/release/rfc
   package <subcommand> Maintain package canonical source`);
 }

package/dist/commands/inspect-workflow.d.ts

@@ -0,0 +1 @@
+export declare function inspectWorkflow(args: string[]): Promise<void>;

package/dist/commands/inspect-workflow.js

@@ -0,0 +1,71 @@
+import { renderWorkflowInspection, renderWorkflowInspectionPrompt, runWorkflowInspection } from "../lib/workflow-inspector.js";
+export async function inspectWorkflow(args) {
+    const options = {};
+    let json = false;
+    let prompt = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--json") {
+            json = true;
+        }
+        else if (arg === "--prompt") {
+            prompt = true;
+        }
+        else if (arg === "--recent-minutes") {
+            options.recentMinutes = parsePositiveNumber(requireValue(args, ++index, arg), arg);
+        }
+        else if (arg === "--recent-turns") {
+            options.recentTurns = parsePositiveNumber(requireValue(args, ++index, arg), arg);
+        }
+        else if (arg === "--estimated-tokens") {
+            options.estimatedTokens = parsePositiveNumber(requireValue(args, ++index, arg), arg);
+        }
+        else if (arg === "--help" || arg === "-h") {
+            printHelp();
+            return;
+        }
+        else {
+            throw new Error(`unknown inspect-workflow argument: ${arg}`);
+        }
+    }
+    const report = await runWorkflowInspection(process.cwd(), options);
+    if (json) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        process.stdout.write(renderWorkflowInspection(report));
+        if (prompt) {
+            console.log("");
+            console.log(renderWorkflowInspectionPrompt(report));
+        }
+    }
+    if (report.decision === "BLOCKED") {
+        process.exitCode = 1;
+    }
+}
+function printHelp() {
+    console.log(`sdlc-harness inspect-workflow
+
+Lightly inspect whether a user repository is running the Harness workflow as intended.
+
+Options:
+  --json                     Emit a machine-readable report
+  --prompt                   Print an Agent self-inspection prompt after the measured report
+  --recent-minutes <n>       Self-reported recent workflow orientation time
+  --recent-turns <n>         Self-reported recent workflow conversation turns
+  --estimated-tokens <n>     Self-reported recent workflow token estimate`);
+}
+function requireValue(args, index, flag) {
+    const value = args[index];
+    if (!value || value.startsWith("--")) {
+        throw new Error(`${flag} requires a value`);
+    }
+    return value;
+}
+function parsePositiveNumber(value, flag) {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        throw new Error(`${flag} must be a non-negative number`);
+    }
+    return parsed;
+}

package/dist/lib/harness-root.js

@@ -2,17 +2,17 @@ import path from "node:path";
 import { DEFAULT_HARNESS_ROOT, HARNESS_JSON_CONFIG_PATH } from "./paths.js";
 import { pathExists, readText } from "./fs.js";
 export async function readHarnessRootConfig(projectRoot) {
-    const explicitConfig = await readJsonConfig(path.join(projectRoot, HARNESS_JSON_CONFIG_PATH));
-    const explicitValue = folderNameFromObject(explicitConfig);
-    if (explicitValue) {
-        return { harnessFolderName: normalizeHarnessFolderName(explicitValue), source: HARNESS_JSON_CONFIG_PATH };
-    }
     const packageJson = await readJsonConfig(path.join(projectRoot, "package.json"));
     const packageConfig = packageJson && typeof packageJson === "object" ? packageJson.sdlcHarness : undefined;
     const packageValue = folderNameFromObject(packageConfig);
     if (packageValue) {
         return { harnessFolderName: normalizeHarnessFolderName(packageValue), source: "package.json#sdlcHarness" };
     }
+    const explicitConfig = await readJsonConfig(path.join(projectRoot, HARNESS_JSON_CONFIG_PATH));
+    const explicitValue = folderNameFromObject(explicitConfig);
+    if (explicitValue) {
+        return { harnessFolderName: normalizeHarnessFolderName(explicitValue), source: HARNESS_JSON_CONFIG_PATH };
+    }
     return { harnessFolderName: DEFAULT_HARNESS_ROOT, source: "default" };
 }
 export async function harnessRoot(projectRoot) {

package/dist/lib/init.js

@@ -7,6 +7,7 @@ import { syncDocsIndexMaintenanceSection, syncMemoryGuidanceSection } from "./us
 const DOC_DIRS = [
     ".docs/00_raw",
     ".docs/01_product",
+    ".docs/02_experience",
     ".docs/02_architecture",
     ".docs/03_tech_plan",
     ".docs/04_implementation",
@@ -31,7 +32,7 @@ export async function runInit(projectRoot, options) {
     else {
         report.push(`kept existing ${configPath}`);
     }
-    await createProjectState(projectRoot, root, report);
+    await createProjectState(projectRoot, root, options.adopt, report);
     await createDocs(projectRoot, report);
     const syncReport = await runSync(projectRoot);
     report.push(`sync changed=${syncReport.changed.length} skipped=${syncReport.skipped.length} blocked=${syncReport.blocked.length}`);
@@ -47,13 +48,16 @@ async function projectHasExistingFiles(projectRoot) {
     }
     return false;
 }
-async function createProjectState(projectRoot, root, report) {
+async function createProjectState(projectRoot, root, adopt, report) {
     const stateRoot = path.join(projectRoot, root, "state");
     await ensureDir(stateRoot);
+    const lifecycle = adopt
+        ? `project_name: "Project"\nversion: "v0.1"\ncurrent_phase: "SPRINTING"\nactive_role: "developer"\nactive_skill: "pjsdlc_dev_sprint"\ncurrent_milestone: "MVP"\nblocked_reason: ""\nsuspended_phase: ""\nallowed_next_phases:\n  - "REVIEWING"\n  - "RFC_RECALIBRATION"\n  - "BLOCKED"\n`
+        : `project_name: "Project"\nversion: "v0.1"\ncurrent_phase: "REQUIREMENT_GATHERING"\nactive_role: "product_manager"\nactive_skill: "pjsdlc_pm_prd"\ncurrent_milestone: "MVP"\nblocked_reason: ""\nsuspended_phase: ""\nallowed_next_phases:\n  - "UI_UX_DESIGNING"\n  - "BLOCKED"\n`;
     const files = [
         [
             harnessPath(root, "state", "lifecycle.yaml"),
-            `project_name: "Project"\nversion: "v0.1"\ncurrent_phase: "SPRINTING"\nactive_role: "developer"\nactive_skill: "pjsdlc_dev_sprint"\ncurrent_milestone: "MVP"\nblocked_reason: ""\nsuspended_phase: ""\nallowed_next_phases:\n  - "REVIEWING"\n  - "RFC_RECALIBRATION"\n  - "BLOCKED"\n`
+            lifecycle
         ],
         [harnessPath(root, "state", "plan.yaml"), `current_task_id: ""\nnext_task_sequence: 1\ntasks: []\n`],
         [harnessPath(root, "state", "plan.draft.yaml"), `next_task_sequence: 1\ntasks: []\n`],