cadence-skill-installer 0.2.29 → 0.2.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cadence-skill-installer",
-  "version": "0.2.29",
+  "version": "0.2.31",
   "description": "Install the Cadence skill into supported AI tool skill directories.",
   "repository": "https://github.com/snowdamiz/cadence",
   "private": false,

package/skill/SKILL.md

@@ -17,6 +17,12 @@ description: Structured project operating system for end-to-end greenfield or br
    - raw commands, terminal traces, or timing metadata
 3. When internal gates/checks succeed, continue directly with the user task and do not announce that checks were run.
 
+## State Mutation Safety
+1. Never manually edit `.cadence/cadence.json`.
+2. Mutate Cadence state only through the provided Cadence scripts (for example `run-*-gate.py`, `inject-ideation.py`, `run-brownfield-documentation.py`, `run-research-pass.py`, `set-workflow-item-status.py`, `read-workflow-state.py`).
+3. If a required state transition is not supported by existing scripts, stop and update scripts first instead of writing JSON by hand.
+4. For subskill preflight setup (project root + scripts-dir + repo-status, with optional route/workflow checks), use `scripts/run-skill-entry-gate.py` instead of repeating command chains.
+
 ## Repo Status Gate
 1. At Cadence entry (first assistant response in the conversation), resolve `PROJECT_ROOT` with `python3 scripts/resolve-project-root.py --project-root "$PWD"` (resolve script paths from this skill directory but keep command cwd at the active project).
 2. If `"$PROJECT_ROOT/.cadence"` exists, run `python3 scripts/check-project-repo-status.py --project-root "$PROJECT_ROOT"`.

package/skill/agents/openai.yaml

@@ -1,4 +1,17 @@
 interface:
   display_name: "Cadence"
   short_description: "Lifecycle + delivery system for structured project execution"
-  default_prompt: "Use Cadence to guide this project from lifecycle setup through phased execution, traceability, audit, and milestone completion. Always read and apply the active SOUL persona from .cadence/SOUL.json (fallback: SOUL.json). Keep user-facing responses concise and outcome-focused, and never expose internal skill-routing or command-execution traces unless the user explicitly asks. Do not announce successful internal checks; only surface them when a check fails and blocks progress. At Cadence entry (first assistant response in a conversation), resolve PROJECT_ROOT with scripts/resolve-project-root.py --project-root \"$PWD\". If \"$PROJECT_ROOT/.cadence\" exists, run scripts/check-project-repo-status.py --project-root \"$PROJECT_ROOT\" and treat repo_enabled as the authoritative push mode (if false, keep commits local-only). Never run scripts/check-project-repo-status.py without --project-root. If \"$PROJECT_ROOT/.cadence\" is missing, run scaffold first and let scaffold establish repo mode. If `.cadence` exists but `.cadence/cadence.json` is missing, run scaffold in recovery mode before routing. After scaffold handling, run scripts/read-workflow-state.py --project-root \"$PROJECT_ROOT\" and treat route.skill_name as authoritative for the next state-changing skill. During normal multi-turn subskill conversation flow, do not rerun repo/route gates between each user reply; rerun them only when checkpointing into a new subskill, handling explicit resume/status/reroute requests, or recovering from assertion/gate failures. Invoke skills/prerequisite-gate/SKILL.md only when route.skill_name is prerequisite-gate. Invoke skills/brownfield-intake/SKILL.md only when route.skill_name is brownfield-intake so project mode and baseline capture happen before downstream ideation routing. Invoke skills/brownfield-documenter/SKILL.md only when route.skill_name is brownfield-documenter so existing-project context is documented into canonical ideation structures. If scaffold, prerequisite, and brownfield-intake complete in-thread and route advances to ideator for a greenfield project, force subskill handoff with: Start a new chat and either say \"help me define my project\" or share your project brief. If scaffold, prerequisite, and brownfield-intake complete in-thread and route advances to brownfield-documenter for a brownfield project, force subskill handoff with: Start a new chat and say \"document my existing project\". In later chats, if route.skill_name is ideator, do not rerun prerequisite or brownfield-intake; invoke skills/ideator/SKILL.md in the same chat, and if the user has not provided ideation input yet, ask one kickoff ideation question in-thread instead of handing off again. In later chats, if route.skill_name is brownfield-documenter, invoke skills/brownfield-documenter/SKILL.md and do not route to ideator unless the user explicitly requests net-new ideation discovery. When route advances from ideator or brownfield-documenter to researcher, force a handoff with: Start a new chat with a new agent and say \"plan my project\". If route.skill_name is researcher, invoke skills/researcher/SKILL.md and enforce one pass per conversation; when more passes remain, end with: Start a new chat and say \"continue research\". If user intent indicates resuming/continuing work or asking progress, invoke skills/project-progress/SKILL.md first, report current phase, then route to the next step. If the user manually requests a Cadence subskill, resolve PROJECT_ROOT with scripts/resolve-project-root.py --project-root \"$PWD\" and then run scripts/assert-workflow-route.py --skill-name <subskill> --project-root \"$PROJECT_ROOT\" before any state-changing actions. Ensure direct subskill execution follows the same Git Checkpoints policy from this main skill: run scripts/finalize-skill-checkpoint.py with each subskill's configured --scope/--checkpoint and --paths ., allow status=no_changes without failure, and treat checkpoint or push failures as blocking errors surfaced verbatim."
+  default_prompt: >-
+    Use Cadence as the orchestrator and follow skill/SKILL.md as the authoritative workflow.
+    On entry, resolve PROJECT_ROOT with scripts/resolve-project-root.py --project-root "$PWD".
+    If "$PROJECT_ROOT/.cadence" exists, run scripts/check-project-repo-status.py --project-root "$PROJECT_ROOT";
+    otherwise scaffold first. If .cadence exists but cadence.json is missing, run scaffold recovery.
+    After scaffold handling, run scripts/read-workflow-state.py --project-root "$PROJECT_ROOT" and only invoke
+    the skill in route.skill_name. For manual subskill requests, assert route first with
+    scripts/assert-workflow-route.py --skill-name <subskill> --project-root "$PROJECT_ROOT".
+    Never edit .cadence/cadence.json manually. Keep replies concise, do not expose internal traces unless asked,
+    and do not announce successful internal checks.
+    For each successful subskill conversation, run scripts/finalize-skill-checkpoint.py from PROJECT_ROOT with
+    that subskill's --scope/--checkpoint and --paths ., allow status=no_changes, and treat checkpoint/push
+    failures as blocking.
+    Use the exact handoff lines in SKILL.md for ideator, brownfield-documenter, and researcher transitions.

package/skill/assets/AGENTS.md

@@ -40,6 +40,7 @@
 ### 7. User-Facing Hygiene
 - Keep user-facing messages outcome-focused
 - Do not expose internal routing, command traces, terminal transcripts, or timing metadata unless the user explicitly asks
+- Never manually edit `.cadence/cadence.json`; use Cadence scripts for all state updates
 
 ## Task Management
 
@@ -55,3 +56,4 @@
 - **Simplicity First**: Make every change as simple as possible. Impact minimal code.
 - **No Laziness**: Find root causes. No temporary fixes. Senior developer standards.
 - **Minimal Impact**: Changes should only touch what's necessary. Avoid introducing bugs.
+- **Script-Only State Writes**: `.cadence/cadence.json` must only be changed via existing Cadence scripts.

package/skill/scripts/run-brownfield-documentation.py

@@ -405,6 +405,233 @@ def parse_payload(args: argparse.Namespace, project_root: Path) -> dict[str, Any
     return payload
 
 
+def _slug_token(value: Any, fallback: str) -> str:
+    token = re.sub(r"[^a-z0-9]+", "-", str(value).strip().lower()).strip("-")
+    if token:
+        return token
+    fallback_token = re.sub(r"[^a-z0-9]+", "-", str(fallback).strip().lower()).strip("-")
+    return fallback_token or "item"
+
+
+def _coerce_text_list(value: Any) -> list[str]:
+    if value is None:
+        return []
+    if isinstance(value, (list, tuple, set)):
+        raw = list(value)
+    else:
+        raw = [value]
+
+    values: list[str] = []
+    for item in raw:
+        text = str(item).strip()
+        if text and text not in values:
+            values.append(text)
+    return values
+
+
+def _unique_token(seed: str, used: set[str]) -> str:
+    candidate = seed
+    index = 2
+    while candidate in used:
+        candidate = f"{seed}-{index}"
+        index += 1
+    used.add(candidate)
+    return candidate
+
+
+def _normalized_aliases(label: str, aliases: Any) -> list[str]:
+    values = _coerce_text_list(aliases)
+    if label and label not in values:
+        values.insert(0, label)
+    return values
+
+
+def repair_research_entity_links(payload: dict[str, Any]) -> dict[str, Any]:
+    """Auto-repair cross-block entity references to reduce avoidable validation failures."""
+
+    repairs: dict[str, Any] = {
+        "applied": False,
+        "generated_block_ids": 0,
+        "created_entities": 0,
+        "owner_assignments": 0,
+        "cross_block_relinks": 0,
+        "unknown_owner_resets": 0,
+    }
+
+    agenda = payload.get("research_agenda")
+    if not isinstance(agenda, dict):
+        return repairs
+
+    blocks = agenda.get("blocks")
+    if not isinstance(blocks, list):
+        return repairs
+
+    block_ids: list[str] = []
+    for index, block in enumerate(blocks, start=1):
+        if not isinstance(block, dict):
+            continue
+        block_id = str(block.get("block_id", "")).strip()
+        if not block_id:
+            block_id = f"block-{index}"
+            block["block_id"] = block_id
+            repairs["generated_block_ids"] += 1
+        block_ids.append(block_id)
+
+    if not block_ids:
+        return repairs
+
+    block_id_set = set(block_ids)
+    entity_registry_raw = agenda.get("entity_registry")
+    entity_registry_raw = entity_registry_raw if isinstance(entity_registry_raw, list) else []
+
+    used_entity_ids: set[str] = set()
+    entity_index: dict[str, dict[str, Any]] = {}
+    entity_order: list[str] = []
+
+    for index, raw_entry in enumerate(entity_registry_raw, start=1):
+        entry = dict(raw_entry) if isinstance(raw_entry, dict) else {"label": raw_entry}
+        label = str(entry.get("label") or entry.get("name") or entry.get("entity_id") or entry.get("id") or "").strip()
+        seed = _slug_token(entry.get("entity_id") or entry.get("id") or label, f"entity-{index}")
+        owner_block_id = str(entry.get("owner_block_id") or entry.get("owner") or "").strip()
+        kind = str(entry.get("kind") or entry.get("type") or "entity").strip() or "entity"
+        aliases = _normalized_aliases(label, entry.get("aliases"))
+
+        if seed in entity_index:
+            existing = entity_index[seed]
+            existing_owner = str(existing.get("owner_block_id", "")).strip()
+            if owner_block_id and existing_owner and owner_block_id != existing_owner:
+                seed = _unique_token(
+                    f"{seed}--{_slug_token(owner_block_id, 'block')}",
+                    used_entity_ids,
+                )
+            else:
+                if not existing_owner and owner_block_id:
+                    existing["owner_block_id"] = owner_block_id
+                for alias in aliases:
+                    if alias not in existing["aliases"]:
+                        existing["aliases"].append(alias)
+                continue
+        else:
+            seed = _unique_token(seed, used_entity_ids)
+
+        entity = {
+            "entity_id": seed,
+            "label": label or seed.replace("-", " ").title(),
+            "kind": kind,
+            "aliases": aliases,
+            "owner_block_id": owner_block_id,
+        }
+        entity_index[seed] = entity
+        entity_order.append(seed)
+
+    clone_cache: dict[tuple[str, str], str] = {}
+    synthetic_index = 0
+
+    for block_index, block in enumerate(blocks, start=1):
+        if not isinstance(block, dict):
+            continue
+        block_id = str(block.get("block_id") or f"block-{block_index}").strip()
+        topics = block.get("topics")
+        topics = topics if isinstance(topics, list) else []
+
+        for topic in topics:
+            if not isinstance(topic, dict):
+                continue
+
+            related_raw = topic.get("related_entities")
+            related_entities = _coerce_text_list(related_raw)
+            if not related_entities:
+                topic["related_entities"] = []
+                continue
+
+            repaired_related: list[str] = []
+            for raw_entity in related_entities:
+                entity_seed = _slug_token(raw_entity, "entity")
+                entity_id = entity_seed
+
+                if entity_id not in entity_index:
+                    synthetic_index += 1
+                    if entity_id in used_entity_ids:
+                        entity_id = _unique_token(f"{entity_seed}-{synthetic_index}", used_entity_ids)
+                    else:
+                        used_entity_ids.add(entity_id)
+                    label = str(raw_entity).strip() or entity_id.replace("-", " ").title()
+                    entity_index[entity_id] = {
+                        "entity_id": entity_id,
+                        "label": label,
+                        "kind": "entity",
+                        "aliases": [label] if label else [],
+                        "owner_block_id": block_id,
+                    }
+                    entity_order.append(entity_id)
+                    repairs["created_entities"] += 1
+                    repairs["owner_assignments"] += 1
+
+                entity = entity_index[entity_id]
+                owner_block_id = str(entity.get("owner_block_id", "")).strip()
+
+                if owner_block_id and owner_block_id != block_id:
+                    cache_key = (entity_id, block_id)
+                    clone_id = clone_cache.get(cache_key, "")
+                    if not clone_id:
+                        clone_id = _unique_token(
+                            f"{entity_id}--{_slug_token(block_id, 'block')}",
+                            used_entity_ids,
+                        )
+                        clone = dict(entity)
+                        clone["entity_id"] = clone_id
+                        clone["owner_block_id"] = block_id
+                        clone["aliases"] = _normalized_aliases(
+                            str(clone.get("label", "")).strip(),
+                            clone.get("aliases"),
+                        )
+                        entity_index[clone_id] = clone
+                        entity_order.append(clone_id)
+                        clone_cache[cache_key] = clone_id
+                        repairs["created_entities"] += 1
+                    repaired_related.append(clone_id)
+                    repairs["cross_block_relinks"] += 1
+                    continue
+
+                if not owner_block_id:
+                    entity["owner_block_id"] = block_id
+                    repairs["owner_assignments"] += 1
+
+                repaired_related.append(entity_id)
+
+            deduped_related: list[str] = []
+            for entity_id in repaired_related:
+                if entity_id not in deduped_related:
+                    deduped_related.append(entity_id)
+            topic["related_entities"] = deduped_related
+
+    for entity_id in entity_order:
+        entity = entity_index.get(entity_id)
+        if not isinstance(entity, dict):
+            continue
+        owner_block_id = str(entity.get("owner_block_id", "")).strip()
+        if owner_block_id and owner_block_id not in block_id_set:
+            entity["owner_block_id"] = ""
+            repairs["unknown_owner_resets"] += 1
+        entity["aliases"] = _normalized_aliases(str(entity.get("label", "")).strip(), entity.get("aliases"))
+        entity["kind"] = str(entity.get("kind", "")).strip() or "entity"
+
+    agenda["entity_registry"] = [entity_index[entity_id] for entity_id in entity_order]
+    payload["research_agenda"] = agenda
+
+    repairs["applied"] = any(
+        int(repairs[key]) > 0
+        for key in (
+            "generated_block_ids",
+            "created_entities",
+            "owner_assignments",
+            "cross_block_relinks",
+            "unknown_owner_resets",
+        )
+    )
+    return repairs
+
+
 def ensure_brownfield_mode(data: dict[str, Any]) -> None:
     state = data.get("state")
     state = state if isinstance(state, dict) else {}
@@ -416,6 +643,7 @@ def ensure_brownfield_mode(data: dict[str, Any]) -> None:
 def complete_flow(args: argparse.Namespace, project_root: Path, data: dict[str, Any]) -> dict[str, Any]:
     ensure_brownfield_mode(data)
     payload = parse_payload(args, project_root)
+    repair_summary = repair_research_entity_links(payload)
     normalized = normalize_ideation_research(payload, require_topics=True)
     normalized = reset_research_execution(normalized)
     data["ideation"] = normalized
@@ -474,6 +702,7 @@ def complete_flow(args: argparse.Namespace, project_root: Path, data: dict[str,
             "topic_count": int(summary.get("topic_count", 0)),
             "entity_count": int(summary.get("entity_count", 0)),
         },
+        "payload_repairs": repair_summary,
         "next_route": data.get("workflow", {}).get("next_route", {}),
     }
 

package/skill/scripts/run-skill-entry-gate.py

@@ -0,0 +1,215 @@
+#!/usr/bin/env python3
+"""Run shared Cadence subskill entry gates and emit a single JSON payload.
+
+This helper centralizes repeated subskill preflight steps:
+- resolve project root
+- resolve cadence scripts dir
+- run repo status gate
+- optionally assert workflow route
+- optionally read workflow state
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+from project_root import resolve_project_root, write_project_root_hint
+
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+RESOLVE_SCRIPTS_DIR_SCRIPT = SCRIPT_DIR / "resolve-project-scripts-dir.py"
+
+
+def run_command(command: list[str], *, cwd: Path | None = None) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        command,
+        cwd=str(cwd) if cwd else None,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Run shared Cadence subskill entry gates.",
+    )
+    parser.add_argument(
+        "--project-root",
+        default="",
+        help="Explicit project root path override.",
+    )
+    parser.add_argument(
+        "--require-cadence",
+        action="store_true",
+        help="Require .cadence to exist while resolving project root.",
+    )
+    parser.add_argument(
+        "--assert-skill-name",
+        default="",
+        help="Optional skill name to assert against workflow route.",
+    )
+    parser.add_argument(
+        "--allow-complete",
+        action="store_true",
+        help="Allow route assertion success when workflow is already complete.",
+    )
+    parser.add_argument(
+        "--include-workflow-state",
+        action="store_true",
+        help="Include read-workflow-state output in the response payload.",
+    )
+    parser.add_argument(
+        "--remote-policy",
+        choices=("any", "github"),
+        default="any",
+        help="Remote policy for repo-enabled detection.",
+    )
+    parser.add_argument(
+        "--set-local-only",
+        action="store_true",
+        help="Pass --set-local-only to check-project-repo-status.",
+    )
+    return parser.parse_args()
+
+
+def fail(message: str, *, code: int = 1) -> None:
+    print(message, file=sys.stderr)
+    raise SystemExit(code)
+
+
+def load_json_output(
+    command: list[str],
+    *,
+    error_label: str,
+    cwd: Path | None = None,
+) -> dict[str, Any]:
+    result = run_command(command, cwd=cwd)
+    if result.returncode != 0:
+        detail = result.stderr.strip() or result.stdout.strip() or error_label
+        fail(detail, code=result.returncode)
+
+    raw = result.stdout.strip()
+    if not raw:
+        fail(f"{error_label}: EMPTY_STDOUT")
+
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        fail(f"{error_label}: INVALID_JSON: {exc}")
+
+    if not isinstance(payload, dict):
+        fail(f"{error_label}: PAYLOAD_MUST_BE_OBJECT")
+    return payload
+
+
+def resolve_scripts_dir(project_root: Path) -> str:
+    result = run_command(
+        [
+            sys.executable,
+            str(RESOLVE_SCRIPTS_DIR_SCRIPT),
+            "--project-root",
+            str(project_root),
+        ]
+    )
+    if result.returncode != 0:
+        detail = result.stderr.strip() or result.stdout.strip() or "MISSING_CADENCE_SCRIPTS_DIR"
+        fail(detail, code=result.returncode)
+
+    scripts_dir = result.stdout.strip()
+    if not scripts_dir:
+        fail("MISSING_CADENCE_SCRIPTS_DIR")
+
+    scripts_path = Path(scripts_dir)
+    if not scripts_path.is_dir():
+        fail("INVALID_CADENCE_SCRIPTS_DIR")
+    return str(scripts_path)
+
+
+def main() -> int:
+    args = parse_args()
+    explicit_project_root = args.project_root.strip() or None
+
+    try:
+        project_root, project_root_source = resolve_project_root(
+            script_dir=SCRIPT_DIR,
+            explicit_project_root=explicit_project_root,
+            require_cadence=bool(args.require_cadence),
+            allow_hint=True,
+        )
+    except ValueError as exc:
+        fail(str(exc))
+
+    write_project_root_hint(SCRIPT_DIR, project_root)
+    scripts_dir = resolve_scripts_dir(project_root)
+
+    repo_status_command = [
+        sys.executable,
+        str(Path(scripts_dir) / "check-project-repo-status.py"),
+        "--project-root",
+        str(project_root),
+        "--remote-policy",
+        str(args.remote_policy),
+    ]
+    if args.set_local_only:
+        repo_status_command.append("--set-local-only")
+
+    repo_status = load_json_output(
+        repo_status_command,
+        error_label="CHECK_PROJECT_REPO_STATUS_FAILED",
+    )
+
+    route_assertion: dict[str, Any] | None = None
+    assert_skill_name = str(args.assert_skill_name).strip()
+    if assert_skill_name:
+        route_command = [
+            sys.executable,
+            str(Path(scripts_dir) / "assert-workflow-route.py"),
+            "--skill-name",
+            assert_skill_name,
+            "--project-root",
+            str(project_root),
+        ]
+        if args.allow_complete:
+            route_command.append("--allow-complete")
+        route_assertion = load_json_output(
+            route_command,
+            error_label="WORKFLOW_ROUTE_CHECK_FAILED",
+        )
+
+    workflow_state: dict[str, Any] | None = None
+    if args.include_workflow_state:
+        workflow_state = load_json_output(
+            [
+                sys.executable,
+                str(Path(scripts_dir) / "read-workflow-state.py"),
+                "--project-root",
+                str(project_root),
+            ],
+            error_label="WORKFLOW_STATE_READ_FAILED",
+        )
+
+    payload: dict[str, Any] = {
+        "status": "ok",
+        "project_root": str(project_root),
+        "project_root_source": project_root_source,
+        "cadence_scripts_dir": scripts_dir,
+        "repo_enabled": bool(repo_status.get("repo_enabled", False)),
+        "repo_status": repo_status,
+    }
+    if route_assertion is not None:
+        payload["route_assertion"] = route_assertion
+    if workflow_state is not None:
+        payload["workflow_state"] = workflow_state
+
+    print(json.dumps(payload))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skill/skills/brownfield-documenter/SKILL.md

@@ -5,41 +5,58 @@ description: Perform deep evidence-based analysis of an existing codebase and pe
 
 # Brownfield Documenter
 
-1. Resolve project root by running `python3 ../../scripts/resolve-project-root.py --require-cadence` and store stdout in `PROJECT_ROOT`.
-2. Resolve helper scripts dir by running `python3 ../../scripts/resolve-project-scripts-dir.py --project-root "$PROJECT_ROOT"` and store stdout in `CADENCE_SCRIPTS_DIR`.
-3. Run `python3 "$CADENCE_SCRIPTS_DIR/check-project-repo-status.py" --project-root "$PROJECT_ROOT"` and parse the JSON output. Treat `repo_enabled` as the authoritative push mode (`false` means local-only commits).
-4. Run brownfield discovery context extraction:
+1. Run shared skill entry gates once at conversation start:
+   - `python3 ../../scripts/run-skill-entry-gate.py --require-cadence`
+   - Parse JSON and store `PROJECT_ROOT` from `project_root`, `CADENCE_SCRIPTS_DIR` from `cadence_scripts_dir`, and push mode from `repo_enabled` (`false` means local-only commits).
+   - Never manually edit `.cadence/cadence.json`; all Cadence state writes must go through Cadence scripts.
+2. Run brownfield discovery context extraction:
    - `python3 "$CADENCE_SCRIPTS_DIR/run-brownfield-documentation.py" --project-root "$PROJECT_ROOT" discover`
-5. `run-brownfield-documentation.py` performs workflow route assertion internally; if assertion fails, stop and surface the exact error.
-6. Treat discover output as helper context only:
+3. `run-brownfield-documentation.py` performs workflow route assertion internally; if assertion fails, stop and surface the exact error.
+4. Treat discover output as helper context only:
    - It must not be treated as final documentation.
    - Use it to choose where to inspect deeply in the repository.
-7. Perform AI-led deep investigation of the existing project using repository evidence:
+5. During normal brownfield documentation, do not read Cadence script source files (for example `run-brownfield-documentation.py`, `ideation_research.py`, `get-ideation.py`) to infer schema or workflow details. Only inspect Cadence internals if the user explicitly asks to debug Cadence itself.
+6. Perform AI-led deep investigation of the existing project using repository evidence:
    - inspect key docs and manifests
    - inspect runtime entrypoints and major code paths
    - inspect test surfaces, tooling, CI, and deployment configuration when present
    - infer objective, core outcome, scope boundaries, constraints, and risks from evidence
-8. Build a finalized ideation payload using the same structure as greenfield ideation
-   - payload root is full `ideation` object
-   - `research_agenda` is required; non-research planning fields are optional in brownfield documentation
-   - include only fields that are explicitly evidenced in the repository or confirmed by the user
-   - do not invent `in_scope`, `out_of_scope`, `implementation_approach`, `milestones`, or `constraints` when evidence is missing
-   - when important details are unknown, ask a focused clarification question or omit those fields and capture uncertainty in optional `assumptions` / `open_questions`
-   - preferred evidence-backed core fields when available: `objective`, `core_outcome`, `target_audience`, `core_experience`, `risks`, `success_signals`
-   - include required `research_agenda` with `blocks`, `entity_registry`, and `topic_index` (`topic_index` can be `{}` in payload; normalization rebuilds it)
-   - each topic must include `topic_id`, `title`, `category`, `priority`, `why_it_matters`, `research_questions`, `keywords`, `tags`, `related_entities`
-   - each entity must include `entity_id`, `label`, `kind`, `aliases`, `owner_block_id`
-   - entity/topic relationships must remain block-consistent
-9. Persist finalized ideation without creating extra project files:
+7. Use this canonical ideation payload contract and do not inspect Cadence Python scripts to infer schema during normal operation:
+   - Payload root must be a JSON object representing the full `ideation` object.
+   - `research_agenda` is required for brownfield completion.
+   - Non-research planning fields are optional in brownfield documentation and must be evidence-backed or user-confirmed.
+   - Do not invent unknown planning details. If information is missing, ask one focused clarification question or omit the field and record uncertainty in optional `assumptions` / `open_questions`.
+8. Build the brownfield payload with these rules:
+   - Preferred optional top-level fields when available: `objective`, `core_outcome`, `target_audience`, `core_experience`, `risks`, `success_signals`, `assumptions`, `open_questions`.
+   - Optional planning fields: `in_scope`, `out_of_scope`, `implementation_approach`, `milestones`, `constraints`.
+   - Required `research_agenda` keys:
+     - `blocks` (array; must contain at least one topic total for completion)
+     - `entity_registry` (array; can be empty)
+     - `topic_index` (object; set `{}` in payload, rebuilt during normalization)
+   - Each `research_agenda.blocks[]` item should include:
+     - `block_id`, `title`, `rationale`, `tags`, `topics`
+   - Each `topics[]` item should include:
+     - `topic_id`, `title`, `category`, `priority` (`low|medium|high`), `why_it_matters`, `research_questions`, `keywords`, `tags`, `related_entities`
+   - Each `entity_registry[]` item should include:
+     - `entity_id`, `label`, `kind`, `aliases`, `owner_block_id`
+   - Relationship rule:
+     - every id listed in topic `related_entities` must exist in `entity_registry`, and that entity's `owner_block_id` must match the topic block.
+9. Sparse payloads are allowed as long as `research_agenda` has at least one topic:
+   - missing topic `category` defaults to `general`
+   - missing topic `priority` defaults to `medium`
+   - missing list fields default to `[]`
+   - empty `entity_registry` is valid
+10. Persist finalized ideation without creating extra project files:
    - pipe payload JSON directly to stdin and run:
    - `python3 "$CADENCE_SCRIPTS_DIR/run-brownfield-documentation.py" --project-root "$PROJECT_ROOT" complete --stdin`
-10. Verify persistence by running:
+   - `complete` automatically repairs common entity-linkage mistakes (for example cross-block entity references) and returns a `payload_repairs` summary.
+11. Verify persistence by running:
    - `python3 "$CADENCE_SCRIPTS_DIR/get-ideation.py" --project-root "$PROJECT_ROOT"`
-11. Mention that granular research queries are available via:
+12. Mention that granular research queries are available via:
    - `python3 "$CADENCE_SCRIPTS_DIR/query-ideation-research.py" --project-root "$PROJECT_ROOT"`
-12. End successful completion replies with this exact line:
+13. End successful completion replies with this exact line:
    - `Start a new chat with a new agent and say "plan my project".`
-13. At end of this successful skill conversation, run `cd "$PROJECT_ROOT" && python3 "$CADENCE_SCRIPTS_DIR/finalize-skill-checkpoint.py" --scope brownfield-documenter --checkpoint documentation-captured --paths .`.
-14. If `finalize-skill-checkpoint.py` returns `status=no_changes`, continue without failure.
-15. If `finalize-skill-checkpoint.py` reports an error, stop and surface it verbatim.
-16. In normal user-facing updates, report brownfield findings and persisted ideation outcomes without raw command traces or internal routing details unless explicitly requested.
+14. At end of this successful skill conversation, run `cd "$PROJECT_ROOT" && python3 "$CADENCE_SCRIPTS_DIR/finalize-skill-checkpoint.py" --scope brownfield-documenter --checkpoint documentation-captured --paths .`.
+15. If `finalize-skill-checkpoint.py` returns `status=no_changes`, continue without failure.
+16. If `finalize-skill-checkpoint.py` reports an error, stop and surface it verbatim.
+17. In normal user-facing updates, report brownfield findings and persisted ideation outcomes without raw command traces or internal routing details unless explicitly requested.

package/skill/skills/brownfield-documenter/agents/openai.yaml

@@ -1,4 +1,16 @@
 interface:
   display_name: "Brownfield Documenter"
   short_description: "Document existing project context into ideation structures"
-  default_prompt: "Resolve PROJECT_ROOT with scripts/resolve-project-root.py --require-cadence, then resolve CADENCE_SCRIPTS_DIR with scripts/resolve-project-scripts-dir.py --project-root \"$PROJECT_ROOT\". Run scripts/check-project-repo-status.py --project-root \"$PROJECT_ROOT\" and treat repo_enabled as authoritative for push/local-only behavior. Run scripts/run-brownfield-documentation.py --project-root \"$PROJECT_ROOT\" discover first (this command performs route assertion internally) and use the output only as helper context to guide deeper AI-led repository investigation. Perform in-depth evidence-based analysis across docs, manifests, entrypoints, major code paths, and test/tooling/deploy surfaces. Build a full ideation payload using the same contract as greenfield ideation, but require only research_agenda for brownfield documentation; non-research planning fields (for example in_scope/out_of_scope/implementation_approach/milestones/constraints) are optional and must be included only when evidenced or user-confirmed. Do not fabricate unknown details; ask focused clarifying questions for high-impact gaps or omit unknown fields and capture uncertainty in assumptions/open_questions. Persist by piping JSON to scripts/run-brownfield-documentation.py --project-root \"$PROJECT_ROOT\" complete --stdin. Do not create extra project tracking files for this flow; persist state in .cadence/cadence.json. Verify with scripts/get-ideation.py and mention scripts/query-ideation-research.py for detailed queries. End successful completion replies with: Start a new chat with a new agent and say \"plan my project\". At end of successful execution, run scripts/finalize-skill-checkpoint.py from PROJECT_ROOT with --scope brownfield-documenter --checkpoint documentation-captured --paths .; allow status=no_changes and surface failures verbatim. Keep user-facing replies concise and do not expose internal command traces unless explicitly requested."
+  default_prompt: >-
+    Follow skills/brownfield-documenter/SKILL.md for exact behavior and payload contract.
+    Run scripts/run-skill-entry-gate.py --require-cadence, then use its JSON output for PROJECT_ROOT
+    (project_root), CADENCE_SCRIPTS_DIR (cadence_scripts_dir), and push/local-only mode (repo_enabled).
+    Never edit .cadence/cadence.json manually.
+    Run scripts/run-brownfield-documentation.py --project-root "$PROJECT_ROOT" discover, perform evidence-based
+    analysis, then persist with scripts/run-brownfield-documentation.py --project-root "$PROJECT_ROOT" complete --stdin.
+    Require a research_agenda with at least one topic, verify with scripts/get-ideation.py, and mention
+    scripts/query-ideation-research.py for granular queries.
+    End success with: Start a new chat with a new agent and say "plan my project".
+    Finalize from PROJECT_ROOT with scripts/finalize-skill-checkpoint.py --scope brownfield-documenter
+    --checkpoint documentation-captured --paths . (allow status=no_changes; surface failures verbatim).
+    Keep replies concise and hide internal traces unless asked.