its-magic 0.1.2-9 → 0.1.2

package/template/scripts/validate_project_readme_coverage.py

@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+"""
+Validate project root README catalog coverage vs backlog (US-0097 / DEC-0083).
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+_SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+_REPO_ROOT = os.path.normpath(os.path.join(_SCRIPT_DIR, ".."))
+
+if _REPO_ROOT not in sys.path:
+    sys.path.insert(0, _REPO_ROOT)
+if _SCRIPT_DIR not in sys.path:
+    sys.path.insert(0, _SCRIPT_DIR)
+
+import installer  # noqa: E402
+import project_readme_coverage_lib as prc  # noqa: E402
+
+
+def _enforce_flag(merged: dict) -> bool:
+    raw = (merged.get("PROJECT_README_ENFORCE") or "1").strip()
+    return raw == "1"
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Validate project README catalog coverage vs backlog (DEC-0083)."
+    )
+    parser.add_argument(
+        "--repo",
+        default=_REPO_ROOT,
+        help="Target repository root (default: parent of scripts/).",
+    )
+    parser.add_argument(
+        "--backlog",
+        default=None,
+        help="Backlog file (default: docs/product/backlog.md under --repo).",
+    )
+    parser.add_argument(
+        "--self-test",
+        action="store_true",
+        help="Run sentinel matrix + schema stability checks.",
+    )
+    parser.add_argument(
+        "--report",
+        action="store_true",
+        help="Emit stable JSON report to stdout.",
+    )
+    parser.add_argument(
+        "--audit-out",
+        metavar="PATH",
+        default=None,
+        help="Write gap audit artifact (JSON) to PATH.",
+    )
+    parser.add_argument(
+        "--enforce",
+        action="store_true",
+        help="Blocking mode (required for /release when PROJECT_README_ENFORCE=1).",
+    )
+    parser.add_argument(
+        "--no-kit-skip",
+        action="store_true",
+        help="Validate root even when FRAMEWORK_KIT_REPO=1.",
+    )
+    args = parser.parse_args()
+
+    if args.self_test:
+        try:
+            prc.self_test_sentinel_matrix()
+            prc.self_test_report_schema()
+        except AssertionError as exc:
+            print(f"self-test failed: {exc}", file=sys.stderr)
+            return 2
+        print("[PROJECT_README_COVERAGE_SELF_TEST_OK]")
+        return 0
+
+    target = os.path.abspath(args.repo)
+    backlog = args.backlog or os.path.join(target, "docs", "product", "backlog.md")
+    if not os.path.isfile(backlog):
+        print(
+            f"{prc.REASON_INPUT_INVALID}: backlog not found: {backlog}",
+            file=sys.stderr,
+        )
+        return 2
+
+    merged, _paths = installer.merge_scratchpad_layers(target)
+    enforce = args.enforce or _enforce_flag(merged)
+
+    if prc.is_framework_kit_repo(merged) and not args.no_kit_skip and not args.enforce:
+        report = {
+            "catalog_marker_present": False,
+            "coverage_missing": [],
+            "coverage_present": [],
+            "coverage_total": 0,
+            "framework_paths_excluded": list(prc.FRAMEWORK_PATHS_EXCLUDED),
+            "gaps": [],
+            "kit_repo_skipped": True,
+            "report_schema_version": prc.REPORT_SCHEMA_VERSION,
+            "repo_root": ".",
+            "status": "PASS",
+        }
+        stderr_lines: list[str] = []
+    else:
+        report, stderr_lines = prc.build_report(
+            target,
+            backlog,
+            enforce=enforce,
+            merged=merged,
+            no_kit_skip=args.no_kit_skip,
+        )
+
+    if args.audit_out:
+        audit_path = args.audit_out
+        if not os.path.isabs(audit_path):
+            audit_path = os.path.join(target, audit_path)
+        os.makedirs(os.path.dirname(audit_path) or ".", exist_ok=True)
+        audit_obj = {
+            "audit_schema_version": 1,
+            "coverage_total": report["coverage_total"],
+            "gaps": report["gaps"],
+            "items": report["coverage_present"] + report["coverage_missing"],
+            "status": report["status"],
+        }
+        with open(audit_path, "w", encoding="utf-8", newline="\n") as f:
+            f.write(prc.canonical_json(audit_obj))
+
+    blocking = bool(stderr_lines) or report["status"] != "PASS"
+
+    if args.report or not args.audit_out:
+        sys.stdout.write(prc.canonical_json(report))
+
+    if blocking and (args.enforce or args.report):
+        print(prc.REASON_BLOCKED, file=sys.stderr)
+        for line in stderr_lines:
+            print(line, file=sys.stderr)
+        return 1
+
+    if blocking:
+        for line in stderr_lines:
+            print(line, file=sys.stderr)
+        return 1 if args.enforce else 0
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/template/scripts/validate_readme_feature_coverage.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""
+Validate README feature coverage vs backlog (US-0091 / DEC-0074).
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+_SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+_REPO_ROOT = os.path.normpath(os.path.join(_SCRIPT_DIR, ".."))
+
+if _REPO_ROOT not in sys.path:
+    sys.path.insert(0, _REPO_ROOT)
+if _SCRIPT_DIR not in sys.path:
+    sys.path.insert(0, _SCRIPT_DIR)
+
+import installer  # noqa: E402
+import readme_feature_coverage_lib as rfc  # noqa: E402
+
+
+def _enforce_flag(merged: dict) -> bool:
+    raw = (merged.get("README_FEATURE_COVERAGE_ENFORCE") or "0").strip()
+    return raw == "1"
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Validate README feature coverage vs backlog (DEC-0074)."
+    )
+    parser.add_argument(
+        "--repo",
+        default=_REPO_ROOT,
+        help="Target repository root (default: parent of scripts/).",
+    )
+    parser.add_argument(
+        "--backlog",
+        default=None,
+        help="Backlog file (default: docs/product/backlog.md under --repo).",
+    )
+    parser.add_argument(
+        "--self-test",
+        action="store_true",
+        help="Run predicate matrix + schema stability checks.",
+    )
+    parser.add_argument(
+        "--report",
+        action="store_true",
+        help="Emit stable JSON report to stdout.",
+    )
+    parser.add_argument(
+        "--audit-out",
+        metavar="PATH",
+        default=None,
+        help="Write gap audit artifact (JSON) to PATH.",
+    )
+    parser.add_argument(
+        "--enforce",
+        action="store_true",
+        help="Blocking mode (required for /release when enforce=1).",
+    )
+    parser.add_argument(
+        "--no-template-parity",
+        action="store_true",
+        help="Skip active vs template/ README and script parity sub-check.",
+    )
+    args = parser.parse_args()
+
+    if args.self_test:
+        try:
+            rfc.self_test_predicate_matrix()
+            rfc.self_test_report_schema()
+        except AssertionError as exc:
+            print(f"self-test failed: {exc}", file=sys.stderr)
+            return 2
+        print("[README_FEATURE_COVERAGE_SELF_TEST_OK]")
+        return 0
+
+    target = os.path.abspath(args.repo)
+    backlog = args.backlog or os.path.join(target, "docs", "product", "backlog.md")
+    if not os.path.isfile(backlog):
+        print(f"{rfc.REASON_INPUT_INVALID}: backlog not found: {backlog}", file=sys.stderr)
+        return 2
+
+    merged, _paths = installer.merge_scratchpad_layers(target)
+    enforce = args.enforce or _enforce_flag(merged)
+
+    merged_profile = None if args.no_template_parity else merged
+    report, stderr_lines = rfc.build_report(
+        target,
+        backlog,
+        enforce=enforce,
+        merged=merged_profile,
+        skip_parity=args.no_template_parity,
+    )
+
+    if args.audit_out:
+        audit_path = args.audit_out
+        if not os.path.isabs(audit_path):
+            audit_path = os.path.join(target, audit_path)
+        os.makedirs(os.path.dirname(audit_path), exist_ok=True)
+        audit_obj = {
+            "audit_schema_version": 1,
+            "coverage_total": report["coverage_total"],
+            "gaps": report["gaps"],
+            "items": report["coverage_present"] + report["coverage_missing"],
+            "status": report["status"],
+        }
+        with open(audit_path, "w", encoding="utf-8", newline="\n") as f:
+            f.write(rfc.canonical_json(audit_obj))
+
+    blocking = bool(stderr_lines) or report["status"] != "PASS"
+
+    if args.report or not args.audit_out:
+        sys.stdout.write(rfc.canonical_json(report))
+
+    if blocking and (args.enforce or args.report):
+        print(rfc.REASON_BLOCKED, file=sys.stderr)
+        for line in sorted(set(stderr_lines)):
+            print(line, file=sys.stderr)
+        return 1
+
+    if blocking and args.audit_out and not args.report:
+        return 0
+
+    if blocking:
+        print(rfc.REASON_BLOCKED, file=sys.stderr)
+        for line in sorted(set(stderr_lines)):
+            print(line, file=sys.stderr)
+        return 1
+
+    if args.enforce:
+        print("[README_FEATURE_COVERAGE_VALIDATE_OK]")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/template/sprints/S0001/progress.md

@@ -0,0 +1 @@
+# Progress — Sprint S0001

package/template/sprints/S0001/qa-findings.md

@@ -0,0 +1,9 @@
+# QA Findings — Sprint S0001
+
+## Scope
+
+## Test plan
+
+## Findings
+
+## Summary

package/template/sprints/S0001/release-findings.md

@@ -0,0 +1,24 @@
+# Release Findings — Sprint S0001
+
+## Release gate status
+
+- Result: PASS|BLOCKED
+- Story: `US-xxxx`
+- Gate order evaluated: `check-in test -> QA -> UAT -> finalize`
+
+## Blocking findings
+
+- Reason code:
+- Summary:
+- Evidence refs:
+
+## Non-blocking findings
+
+- 
+
+## Remediation and rerun criteria
+
+1. 
+2. 
+
+- Re-run `/release` after remediation and update this file with final outcome.

package/template/sprints/S0001/sprint.md

@@ -0,0 +1,9 @@
+# Sprint S0001
+
+## Goal
+
+## Scope
+
+## Risks
+
+## Definition of Done

package/template/sprints/S0001/summary.md

@@ -0,0 +1,7 @@
+# Summary — Sprint S0001
+
+## Goal
+
+## Completed
+
+## Open items

package/template/sprints/S0001/tasks.md

@@ -0,0 +1 @@
+# Tasks — Sprint S0001

package/template/sprints/S0001/uat.json

@@ -0,0 +1,6 @@
+{
+  "sprint": "S0001",
+  "steps": [],
+  "passed": 0,
+  "failed": 0
+}

package/template/sprints/S0001/uat.md

@@ -0,0 +1,5 @@
+# UAT — Sprint S0001
+
+## Steps
+
+## Results

package/template/sprints/quick/Q0001/summary.md

@@ -0,0 +1 @@
+# Summary — Quick Task Q0001

package/{sprints → template/sprints}/quick/Q0001/task.json

@@ -1,5 +1,4 @@
 {
-  "id": "Q0001",
   "task": "",
   "acceptance": [],
   "status": "open"

package/.cursor/agents/curator.mdc

@@ -1,21 +0,0 @@
----
-description: "Curator agent"
----
-
-You are the Curator. Keep context compact and artifacts current.
-
-Inputs:
-- `docs/engineering/state.md`
-- `docs/engineering/decisions.md`
-- Sprint summaries and handoffs
-
-Outputs:
-- Refreshed `docs/engineering/state.md`
-- Refreshed `docs/engineering/decisions.md`
-- Updated sprint summary
-- `handoffs/resume_brief.md`
-
-Rules:
-- Avoid context bloat. Summarize and prune.
-- Ensure pause/resume is reliable.
-

package/.cursor/agents/dev.mdc

@@ -1,20 +0,0 @@
----
-description: "Developer agent"
----
-
-You are the Dev. Implement tasks and maintain artifacts.
-
-Inputs:
-- `sprints/S0001/tasks.md`
-- `handoffs/tl_to_dev.md`
-
-Outputs:
-- Code changes
-- `sprints/S0001/summary.md`
-- `docs/engineering/state.md`
-- `handoffs/dev_to_qa.md` (when ready)
-
-Rules:
-- Implement one task at a time.
-- Update summaries and state after each task.
-

package/.cursor/agents/po.mdc

@@ -1,19 +0,0 @@
----
-description: "Product Owner agent"
----
-
-You are the PO. Your job is to clarify requirements and persist them.
-
-Inputs:
-- User idea, constraints, target audience
-
-Outputs:
-- `docs/product/vision.md`
-- `docs/product/backlog.md`
-- `docs/product/acceptance.md`
-- `handoffs/po_to_tl.md`
-
-Rules:
-- Ask targeted questions until acceptance is concrete.
-- Never leave critical info only in chat.
-

package/.cursor/agents/qa.mdc

@@ -1,19 +0,0 @@
----
-description: "QA agent"
----
-
-You are QA. Validate acceptance and report findings.
-
-Inputs:
-- `handoffs/dev_to_qa.md`
-- `sprints/S0001/summary.md`
-
-Outputs:
-- `sprints/S0001/qa-findings.md`
-- `handoffs/qa_to_dev.md` (if issues)
-- `docs/engineering/state.md`
-
-Rules:
-- Provide a clear test plan and findings.
-- Escalate critical issues via decision gate.
-

package/.cursor/agents/release.mdc

@@ -1,19 +0,0 @@
----
-description: "Release agent"
----
-
-You are Release. Prepare release notes and runbook commands.
-
-Inputs:
-- `sprints/S0001/summary.md`
-- `docs/engineering/runbook.md`
-
-Outputs:
-- `handoffs/release_notes.md`
-- `docs/engineering/runbook.md`
-- `docs/engineering/state.md`
-
-Rules:
-- Ensure deploy commands are explicit before release.
-- Keep release notes concise and actionable.
-

package/.cursor/agents/tech-lead.mdc

@@ -1,21 +0,0 @@
----
-description: "Tech Lead agent"
----
-
-You are the Tech Lead. Define architecture, risks, and sprint plan.
-
-Inputs:
-- `docs/product/*`
-- `handoffs/po_to_tl.md`
-
-Outputs:
-- `docs/engineering/architecture.md`
-- `docs/engineering/decisions.md`
-- `docs/engineering/state.md`
-- `sprints/S0001/*`
-- `handoffs/tl_to_dev.md`
-
-Rules:
-- Document tradeoffs and decision gates.
-- Keep architecture minimal and practical.
-

package/.cursor/commands/gsd-architecture.md

@@ -1,29 +0,0 @@
----
-description: "GSD architecture: define approach, risks, and decisions."
----
-
-# /gsd-architecture
-
-## Subagents
-- tech-lead
-
-## Inputs
-- Product vision and acceptance
-- Constraints and risks
-- `docs/engineering/research.md`
-
-## Outputs (artifacts)
-- `docs/engineering/architecture.md`
-- `docs/engineering/decisions.md`
-- `docs/engineering/state.md`
-- `handoffs/po_to_tl.md` (read)
-
-## Stop conditions
-- Major tradeoff requires a decision
-- Unknown feasibility or data migration risk
-
-## Steps
-1. Define the minimal architecture and key components.
-2. Record tradeoffs in decisions log.
-3. Update engineering state and readiness.
-

package/.cursor/commands/gsd-auto.md

@@ -1,27 +0,0 @@
----
-description: "GSD auto: run phases sequentially until decision gate."
----
-
-# /gsd-auto
-
-## Subagents
-- curator
-- tech-lead
-
-## Inputs
-- `AUTO_FLOW_MODE` and `PHASE_MODE` from `.cursor/scratchpad.md`
-- Current product and engineering docs
-
-## Outputs (artifacts)
-- Updated phase artifacts for each step
-- `docs/engineering/state.md`
-- `handoffs/resume_brief.md` if stopped
-
-## Stop conditions
-- Decision gate triggered
-- Missing critical input
-
-## Steps
-1. Read automation flags from scratchpad.
-2. Run phases sequentially (intake -> discovery -> research -> architecture -> sprint plan -> plan verify -> execute -> QA -> verify work -> release -> refresh).
-3. Stop at decision gate or missing info and write resume brief.

package/.cursor/commands/gsd-discovery.md

@@ -1,27 +0,0 @@
----
-description: "GSD discovery: collect design/UX inspiration and scope updates."
----
-
-# /gsd-discovery
-
-## Subagents
-- po
-
-## Inputs
-- Design/UX references
-- Competitive/market notes
-
-## Outputs (artifacts)
-- `docs/product/vision.md`
-- `docs/product/backlog.md`
-- `handoffs/po_to_tl.md`
-
-## Stop conditions
-- Missing references
-- Decision gate triggered
-
-## Steps
-1. Capture references and UX notes in vision.
-2. Add new stories or updates to backlog.
-3. Refresh the PO -> TL handoff.
-

package/.cursor/commands/gsd-execute.md

@@ -1,32 +0,0 @@
----
-description: "GSD execute: implement tasks with artifacts and state updates."
----
-
-# /gsd-execute
-
-## Subagents
-- dev
-
-## Inputs
-- `sprints/S0001/tasks.md`
-- `handoffs/tl_to_dev.md`
-
-## Outputs (artifacts)
-- Code changes
-- `sprints/S0001/summary.md`
-- `docs/engineering/state.md`
-- `handoffs/dev_to_qa.md` (if ready)
-
-## Stop conditions
-- Decision gate triggered
-- Missing task definition or unclear scope
-
-## Steps
-1. Implement one task at a time.
-2. Update summary and engineering state.
-3. Handoff to QA when ready.
-4. If `AUTO_INSTALL_DEPS=1` in `.cursor/scratchpad.md`, install dependencies
-   via the appropriate package manager without prompting.
-5. If `REMOTE_EXECUTION=1` and `.cursor/remote.json` is configured, use
-   remote/docker servers for heavy builds or tests when needed.
-

package/.cursor/commands/gsd-intake.md

@@ -1,28 +0,0 @@
----
-description: "GSD intake: clarify idea and capture story + acceptance."
----
-
-# /gsd-intake
-
-## Subagents
-- po
-
-## Inputs
-- User idea (text or voice transcription)
-- Constraints, audience, success criteria
-
-## Outputs (artifacts)
-- `docs/product/vision.md`
-- `docs/product/backlog.md`
-- `docs/product/acceptance.md`
-- `handoffs/po_to_tl.md`
-
-## Stop conditions
-- Missing acceptance criteria or unclear scope
-- Decision gate triggered (see escalation rule)
-
-## Steps
-1. Ask targeted questions until the story and acceptance are concrete.
-2. Persist the story and acceptance in product docs.
-3. Write a PO -> TL handoff with scope and risks.
-

package/.cursor/commands/gsd-map-codebase.md

@@ -1,25 +0,0 @@
----
-description: "GSD map codebase: analyze existing project before changes."
----
-
-# /gsd-map-codebase
-
-## Subagents
-- tech-lead
-- curator
-
-## Inputs
-- Existing repository code and docs
-
-## Outputs (artifacts)
-- `docs/engineering/codebase-map.md`
-- `docs/engineering/dependencies.json`
-- `docs/engineering/state.md`
-
-## Stop conditions
-- Decision gate triggered
-
-## Steps
-1. Identify stack, structure, and key entry points.
-2. Summarize architecture and conventions.
-3. Capture dependencies and tooling.