@punks/cli 1.0.6 → 2.0.0-beta.0

package/dist/skills/agnostic/requirements/requirements-phase/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: requirements-phase
+description: Orchestrates the human-centric requirements phase from ambiguity through requirements-grill artifacts into backlog shape. Use when the user asks to run a requirements phase, move from discovery to backlog, close requirement branches, decide whether backlog writing is ready, or coordinate requirements-grill with write-backlog.
+---
+
+# Requirements Phase
+
+Human-centric discovery wrapper for `requirements-grill -> write-backlog`.
+
+Normally do not create or update a formal agent goal. This phase is an interview and decision-closure loop, not execution delivery.
+
+## Use when
+
+- The user asks for a requirements phase, requirements discovery, or backlog readiness.
+- Ambiguity needs to become grill branches, glossary, axioms, parked scope, and closure decisions.
+- Existing `*-grill-status.md` / `*-grill-log.md` artifacts need to drive backlog/module/epic/story shape.
+- The user wants to know whether to keep grilling, park scope, or write/sync backlog.
+
+## Do not use when
+
+- The user asks to write `SPEC.md`, `PLAN.md`, implementation notes, code, tests, PRs, or delivery execution.
+- The next step is already an approved spec/plan/implementation task. Use delivery-phase or the specific delivery skill instead.
+- The user wants only a tactical backlog formatting pass from already-closed requirements. Use `write-backlog` directly.
+
+## Workflow
+
+1. Establish phase state.
+   - Identify the topic, source artifacts, current backlog target/provider, and any explicit scope boundary.
+   - If grill artifacts exist, read status first, then log.
+   - State assumptions and known unresolved branches tersely.
+
+2. Route to `requirements-grill` while decisions are open.
+   - Let `requirements-grill` own HITL interviewing.
+   - Ask one question at a time with a recommended answer and why.
+   - Turn ambiguity into named branches, branch percentages, accepted decisions, rejected/superseded decisions, glossary entries, axioms, and parked scope.
+   - Do not write backlog while major branches remain open unless the user explicitly parks them.
+
+3. Decide backlog readiness.
+   - Backlog-ready means active branches are closed enough for module/epic/story shaping, and unresolved branches are either non-blocking, explicitly parked, or recorded as follow-up scope.
+   - If not ready, continue grilling or report the exact blocker branches.
+   - If ready, hand off to `write-backlog`.
+
+4. Run `write-backlog` only after readiness.
+   - Derive modules first, then epics/capabilities, then stories.
+   - Use accepted decisions and locked direction only.
+   - Preserve parked scope and unresolved items as deferred notes, not silent backlog content.
+   - Sync or draft provider payloads only when the user requested backlog write/sync.
+
+5. Stop at the requirements boundary.
+   - Do not create specs, plans, implementation tasks, or code changes from this phase.
+   - Recommend delivery-phase only after backlog state is clear.
+
+## Output contract
+
+End with one of these states:
+
+- `backlog-ready`: branches closed or parked enough; backlog can be written next.
+- `backlog-written`: backlog hierarchy/payloads were produced or synced.
+- `parked`: requirements are intentionally unresolved; parked scope and resume trigger are explicit.
+- `blocked`: named branches still need human decisions before backlog writing.
+
+Include:
+
+- active, closed, parked, and unresolved branches
+- glossary and axiom changes, if any
+- backlog module/epic/story implications, if known
+- next recommended action: continue grill, write/sync backlog, park, or move to delivery-phase

package/dist/skills/agnostic/research/review-phase/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: review-phase
+description: Run a findings-first readonly review phase with explicit entry gates, delegated lenses, artifacts, and validation. Use for review-only goals, manual reviews, PRs, merged branches, external edits, suspicious code, or as the mandatory review wrapper inside delivery-phase.
+---
+
+# Review Phase
+
+A phase is a wrapper skill: it defines when to enter, when to stop, which inner
+skills to delegate to, what artifacts to produce, and which gates must pass.
+`review-phase` is standalone and readonly by default. Inside `delivery-phase`, it
+is mandatory and may hand findings back to delivery for fixes, debugging, docs,
+or validation because delivery owns completion.
+
+## Use When
+
+- The user asks for a review, audit, second pass, PR review, suspicious-code check, or review-only goal.
+- Code changed outside this session and needs independent inspection.
+- A branch was merged, rebased, generated, or edited externally and needs confirmation.
+- `delivery-phase` reaches its mandatory review gate.
+- The desired output is findings, risks, missing tests, or recommended next actions.
+
+## Do Not Use When
+
+- The user asks directly for implementation with no review gate.
+- The task is pure planning, requirements grilling, or docs writing with no artifact to review.
+- You need to edit code immediately; ask for or enter an owning delivery/debug/fix phase instead.
+- The review target is undefined and cannot be inferred from branch, diff, issue, PR, or user prompt.
+
+## Entry Contract
+
+1. Identify the review target: diff, PR, branch range, files, spec, plan, docs, or runtime evidence.
+2. State scope and readonly posture. If scope is ambiguous, ask one clarifying question.
+3. Read local guidance in checked directories, especially relevant `AGENTS.md` files under apps, packages, docs, or nested ownership boundaries.
+4. Choose review lenses and say which are active.
+
+## Review Lenses
+
+- `parallel-research`: fan out independent readonly checks when scope can split by subsystem, risk, or hypothesis.
+- `simplify`: inspect clarity, overcomplexity, unnecessary abstraction, derivable state, naming, and scope creep.
+- `improve-codebase-architecture`: surface architectural friction, shallow modules, poor boundaries, and module-depth opportunities.
+- Scoped local guidance: apply applicable directory instructions, stack skills, runbooks, and ownership rules discovered in checked paths.
+
+Use only the lenses that fit the target. Do not perform ceremonial delegation when a local pass is faster and equally reliable.
+
+## Workflow
+
+1. Gather evidence:
+   - inspect status, diff/range/PR metadata, tests, docs, and relevant local instructions
+   - prefer primary artifacts over tracker summaries
+   - record exact files and commands consulted
+2. Split if useful:
+   - use `parallel-research` for independent readonly checks
+   - synthesize before reporting; disagreements need evidence, not vote counting
+3. Review findings-first:
+   - prioritize bugs, regressions, broken contracts, missing validation, unsafe assumptions, and user-facing risks
+   - include file and line references when available
+   - separate blocking findings from improvements and optional cleanup
+4. Apply clarity and architecture lenses:
+   - use `simplify` to flag unnecessary concepts or complexity
+   - use `improve-codebase-architecture` to flag deeper boundary opportunities, usually as follow-up RFC candidates
+5. Validate:
+   - run readonly checks that match the target when safe: tests, typecheck, lint, build, docs link checks, or focused smoke commands
+   - if a check cannot run, state why and the residual risk
+6. Stop:
+   - standalone mode stops after findings and recommended next actions
+   - delivery mode returns findings to `delivery-phase`; delivery decides and performs fixes/debug/docs/validation
+
+## Output Contract
+
+Lead with findings, ordered by severity. For each finding include:
+
+- severity
+- file/line or artifact reference
+- issue and impact
+- evidence
+- recommended action
+
+Then include:
+
+- open questions or assumptions
+- validation run and result
+- short summary only after findings
+- whether this was standalone readonly review or delivery-owned review
+
+If there are no findings, say so clearly and still report validation coverage and residual risk.
+
+## Expected Outputs
+
+- Review report in conversation, issue, PR comment, or handoff artifact as requested.
+- Optional follow-up issue/RFC candidates for architectural opportunities.
+- In delivery mode only: fix/debug/docs tasks handed back to the owning phase.
+
+## Gotchas
+
+- Findings-first means do not bury issues under summary prose.
+- Do not edit code in standalone mode unless the user explicitly asks after seeing the review scope.
+- Do not use `simplify` as permission to refactor; report simplification opportunities unless delivery owns fixes.
+- Do not flatten scoped `AGENTS.md` guidance into generic advice; quote the concrete constraint that matters.
+- Do not let `delivery-phase` skip this phase just because tests passed.

package/package.json

@@ -1,8 +1,7 @@
 {
   "name": "@punks/cli",
-  "version": "1.0.6",
+  "version": "2.0.0-beta.0",
   "description": "Devpunks AI scaffolding CLI",
-  "type": "module",
   "bin": {
     "devpunks": "dist/index.js",
     "dp": "dist/index.js",
@@ -10,9 +9,10 @@
   },
   "files": [
     "dist",
-    "docs",
+    "README.md",
     "AGENTS.md"
   ],
+  "type": "module",
   "scripts": {
     "build": "node ./scripts/build-dist.mjs",
     "baseline:build": "bun ./scripts/build-baseline.mjs",
@@ -25,13 +25,22 @@
     "test": "vitest run --config vitest.config.ts"
   },
   "dependencies": {
+    "@effect/cli": "catalog:",
+    "@effect/platform": "catalog:",
+    "@effect/platform-bun": "catalog:",
+    "@effect/printer": "catalog:",
+    "@effect/printer-ansi": "catalog:",
+    "@punks/contract": "workspace:*",
+    "@punks/scaffold": "workspace:*",
+    "diff": "catalog:",
+    "effect": "catalog:",
     "react-devtools-core": "^6.1.5"
   },
   "devDependencies": {
-    "@effect/vitest": "0.27.0",
-    "@types/node": "^22.13.14",
-    "typescript": "^5.8.3",
-    "vitest": "^3.2.4"
+    "@effect/vitest": "catalog:",
+    "@types/node": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
   },
   "packageManager": "bun@1.3.5"
 }

package/dist/data/hooks/format-edited-file.py

@@ -1,157 +0,0 @@
-#!/usr/bin/env python3
-
-from __future__ import annotations
-
-import hashlib
-import json
-import os
-import subprocess
-import sys
-from pathlib import Path
-
-SUPPORTED_SUFFIXES = (".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".json")
-IGNORED_PARTS = {".git", "node_modules", ".next", "dist"}
-
-
-def read_input() -> dict[str, object]:
-    try:
-        return json.load(sys.stdin)
-    except json.JSONDecodeError:
-        return {}
-
-
-def run_git(args: list[str], cwd: str) -> str:
-    result = subprocess.run(
-        ["git", "-C", cwd, *args],
-        check=True,
-        capture_output=True,
-        text=True,
-    )
-    return result.stdout
-
-
-def repo_root(cwd: str) -> str:
-    try:
-        return run_git(["rev-parse", "--show-toplevel"], cwd).strip()
-    except subprocess.CalledProcessError:
-        return ""
-
-
-def dirty_files(root: str) -> list[str]:
-    try:
-        output = run_git(["ls-files", "-m", "-o", "--exclude-standard"], root)
-    except subprocess.CalledProcessError:
-        return []
-
-    files: list[str] = []
-    for raw_path in output.splitlines():
-        path = raw_path.strip()
-        if not path:
-            continue
-        if not path.endswith(SUPPORTED_SUFFIXES):
-            continue
-        if any(part in IGNORED_PARTS for part in Path(path).parts):
-            continue
-        files.append(path)
-
-    return sorted(set(files))
-
-
-def file_hash(path: Path) -> str:
-    digest = hashlib.sha256()
-    with path.open("rb") as handle:
-        for chunk in iter(lambda: handle.read(65536), b""):
-            digest.update(chunk)
-    return digest.hexdigest()
-
-
-def snapshot_path(root: str, session_id: str, tool_use_id: str) -> Path:
-    repo_name = Path(root).name or "repo"
-    safe_session_id = session_id.replace("/", "_")
-    safe_tool_use_id = tool_use_id.replace("/", "_")
-    state_dir = Path(os.environ.get("TMPDIR", "/tmp")) / "codex-hooks" / repo_name / safe_session_id
-    state_dir.mkdir(parents=True, exist_ok=True)
-    return state_dir / f"{safe_tool_use_id}.json"
-
-
-def load_snapshot(path: Path) -> dict[str, str]:
-    if not path.exists():
-        return {}
-    try:
-        return json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError):
-        return {}
-
-
-def fingerprints(root: str) -> dict[str, str]:
-    snapshot: dict[str, str] = {}
-    for relative_path in dirty_files(root):
-        absolute_path = Path(root) / relative_path
-        if absolute_path.exists():
-            snapshot[relative_path] = file_hash(absolute_path)
-    return snapshot
-
-
-def format_files(root: str, files: list[str]) -> list[str]:
-    failed: list[str] = []
-    for relative_path in files:
-        absolute_path = Path(root) / relative_path
-        result = subprocess.run(
-            ["npx", "oxfmt", "--write", str(absolute_path)],
-            cwd=root,
-            stdout=subprocess.DEVNULL,
-            stderr=subprocess.DEVNULL,
-            check=False,
-        )
-        if result.returncode != 0:
-            failed.append(relative_path)
-    return failed
-
-
-def emit_failure(files: list[str]) -> None:
-    message = "Auto-format failed for " + ", ".join(files) + ". Review the file and format it manually if needed."
-    print(json.dumps({"systemMessage": message}))
-
-
-def main() -> int:
-    mode = sys.argv[1] if len(sys.argv) > 1 else ""
-    payload = read_input()
-
-    cwd = str(payload.get("cwd") or os.getcwd())
-    session_id = str(payload.get("session_id") or "")
-    tool_use_id = str(payload.get("tool_use_id") or "")
-    root = repo_root(cwd)
-
-    if not root or not session_id or not tool_use_id:
-        return 0
-
-    state_file = snapshot_path(root, session_id, tool_use_id)
-
-    if mode == "pre":
-        state_file.write_text(json.dumps(fingerprints(root), sort_keys=True), encoding="utf-8")
-        return 0
-
-    if mode != "post":
-        return 0
-
-    previous = load_snapshot(state_file)
-    current = fingerprints(root)
-
-    try:
-        state_file.unlink()
-    except OSError:
-        pass
-
-    touched = [path for path, digest in current.items() if previous.get(path) != digest]
-    if not touched:
-        return 0
-
-    failed = format_files(root, touched)
-    if failed:
-        emit_failure(failed)
-
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

package/dist/skills/agnostic/docs/docs-maintenance/SKILL.md

@@ -1,193 +0,0 @@
----
-name: docs-maintenance
-description: "Ingest a spec folder into the wiki domain layer by extracting and writing flow pages first, then concept pages, then syncing ingest metadata. Secondary: update docs/ when code changes alter architecture, setup, contracts, or operator workflow. Use when a spec is ready to be captured as domain knowledge after review or implementation, or when a code task changes non-obvious behavior that docs/ should reflect."
----
-
-# Docs Maintenance
-
-## Contract
-
-- **Role:** higher-order ingest and repo-docs orchestrator
-- **Entrypoint type:** public entrypoint
-- **Upstream:** reviewed or implemented spec folder, or code changes that may require `docs/` updates
-- **Delegates to:** internal flow-writing phase, then internal concept-writing phase
-- **Downstream:** synced wiki indexes, ingest metadata, wiki log, and any required `docs/` updates
-- **Entry conditions:** resolved spec folder for ingest work, or a concrete docs-affecting code change
-- **Stop conditions:** ingest bookkeeping complete, required docs updates complete, failures reported honestly
-
-## Overview
-
-**Primary purpose:** synthesize `<wiki-root>/specs/<domain>/<spec>/SPEC.md` (and optionally `IMPLEMENTATION-NOTES.md`) into the wiki domain knowledge layer. Write flow pages first, then concept pages, then sync ingest bookkeeping.
-
-**Secondary purpose:** keep `docs/` accurate when code changes alter architecture, setup, contracts, decisions, or operator-facing behavior.
-
-Read `<wiki-root>/AGENTS.md` before touching any wiki content.
-
-`<wiki-root>` is repo-shape dependent:
-- monorepo: `apps/wiki`
-- single-repo: `wiki`
-
----
-
-## Primary: Wiki Ingest Orchestration
-
-### Pipeline
-
-```
-docs-maintenance (orchestrator)
-  └─ 1. flow-writing phase    — writes flows/, updates domain index
-  └─ 2. concept-writing phase — reads flows/ for cross-linking, writes concepts/, updates domain index
-```
-
-**Why this order is required:** concept writing reads existing flow pages to cross-link concepts. Flow pages must exist before concept pages are written.
-
-### Inputs
-
-Accept any of:
-- A spec folder path: `<wiki-root>/specs/<domain>/<spec>/`
-- A domain name + spec name
-- An explicit `SPEC.md` path
-
-Resolve all inputs to a full spec folder path before continuing. If the target is still ambiguous, ask only for the missing folder.
-
-### Step 1: Guard
-
-Check `SPEC.md` frontmatter for `ingested: true`. If set, exit with a clear no-op message.
-
-Verify the spec has `domain:` in frontmatter. Error if absent.
-
-### Step 2: Read the source
-
-Read in order:
-1. `SPEC.md` — mandatory. If missing, stop and report.
-2. `IMPLEMENTATION-NOTES.md` — optional. If present, flows and concepts become `status: implemented`. If absent, status is `proposed`.
-   - Check its frontmatter. If it lacks frontmatter (no YAML block), add it now before continuing:
-     ```yaml
-     ---
-     domain: <domain from SPEC.md>
-     type: implementation-notes
-     spec: <spec id from SPEC.md>
-     links:
-       - "[[specs/<domain>/<spec>/SPEC]]"
-     ingested: false
-     last_ingested: null
-     created: <today>
-     updated: <today>
-     ---
-     ```
-
-Verify `<wiki-root>/domains/<domain>/` exists with a `<domain>.md` index file. If the domain is missing, stop and scaffold the wiki/domain structure first.
-
-### Step 3: Extract flows
-
-A flow exists when the spec describes a **sequence of user or system actions with a defined start, steps, and end outcome**.
-
-Look for flows in:
-- Multi-step acceptance criteria (e.g. "On save, the system runs duplicate detection → blocks if exact match → redirects operator on success")
-- Explicit user journeys or process descriptions in the Context section
-- "When X, then Y" conditional chains across multiple acceptance criteria
-- Any section titled Flow, Process, Journey, or similar
-
-For each flow found:
-- Assign a descriptive `flow_name` (e.g., "Create Patient", "Document Upload", "Duplicate Check")
-- Extract `flow_content`: triggering event, actors involved, ordered steps with decision points, terminal outcome
-- When `IMPLEMENTATION-NOTES.md` is present: note deviations, surprises, or blocked steps inline
-
-If no multi-step sequence is discernible (e.g., a purely data-model spec), record the absence and skip flow delegation.
-
-### Step 4: Write flow pages
-
-Read [references/flow-pages.md](references/flow-pages.md) and apply that contract to every extracted flow.
-
-Wait for all flow pages to complete before proceeding.
-
-If any flow write fails, stop immediately. Do not proceed to concept writing. Report the failure so the run can be resumed cleanly.
-
-### Step 5: Extract concepts
-
-A concept exists when the spec **names a domain entity or term with defined attributes, invariants, or bounded scope**.
-
-Look for concepts in:
-- Fields listed in acceptance criteria (e.g., `first_name`, `email`, `acquisition_channel`, `nin`)
-- Explicit data model or entity sections
-- Nouns that recur across multiple acceptance criteria with their own distinct attributes or rules
-- Enum sets representing a bounded domain state (e.g., `acquisition_channel` values)
-- Entities referenced via `[[wikilinks]]` to other specs or domain pages
-
-**Grouping rule:** collect related fields under one owning entity rather than creating a concept per field. All patient registry fields → one "Patient" concept. All acquisition channel variants → one "Acquisition Channel" concept.
-
-If no distinct domain entity is identifiable, record the absence and skip concept delegation.
-
-### Step 6: Write concept pages
-
-Read [references/concept-pages.md](references/concept-pages.md) and apply that contract to every extracted concept.
-
-Wait for all concept pages to complete.
-
-### Step 7: Mark sources as ingested
-
-Update `SPEC.md` frontmatter:
-```yaml
-ingested: true
-last_ingested: YYYY-MM-DD
-```
-
-If `IMPLEMENTATION-NOTES.md` is present, update its frontmatter:
-```yaml
-ingested: true
-last_ingested: YYYY-MM-DD
-```
-
-Also populate its `links` array with every flow and concept page written in Steps 4 and 6 (in addition to the SPEC link that was set in Step 2). This is the only moment where IMPLEMENTATION-NOTES links are updated — do not leave them pointing only at the SPEC.
-
-### Step 8: Log entry
-
-Append to `<wiki-root>/log.md` (cap at 50 entries; drop oldest when over):
-```md
-## [YYYY-MM-DD] ingest | <spec title>
-- Source: [[specs/<domain>/<spec>/SPEC]]
-- Flows written: <count>
-- Concepts written: <count>
-```
-
-### Step 9: Update wiki index
-
-If new pages were created, update the Concepts and Flows counts in the relevant Domains table row in `<wiki-root>/index.md`.
-
-### Resumability
-
-Output pages are the checkpoints. On re-invocation of the same source:
-
-- Flow pages with `ingested: true` → skip Step 4 for those flows
-- Any expected flow page missing → re-run Step 4 for it before Step 6
-- Concept pages with `ingested: true` → skip Step 6 for those concepts
-
----
-
-## Secondary: docs/ Maintenance
-
-Update `docs/` when a code task changes **architecture, setup, contracts, decisions, or non-obvious operator-facing behavior**. Do not let docs/ work displace or delay wiki ingest.
-
-1. Read `docs/README.md` and the nearest affected section README before editing.
-2. Prefer editing an existing leaf doc over creating a new one.
-3. When a doc is added, removed, or renamed: update `docs/README.md` and the nearest section README in the same task.
-4. Record repo-wide behavior changes in `docs/architecture/decisions/`.
-
-**Route by owned behavior:**
-- Backend/runtime surface → `docs/reference/domains/backend-effect-sql.md` or `docs/runbooks/`
-- Auth/user-management → `docs/reference/domains/user-management.md`
-- Frontend/app structure → `docs/reference/domains/frontend-application-structure.md`
-- AI workflow/agent infrastructure → `docs/runbooks/subagent-templates.md` or `docs/runbooks/claude-code-hooks.md`
-
----
-
-## Never Do
-
-- Ingest a spec with `ingested: true` — exit early instead
-- Ingest an `IMPLEMENTATION-NOTES.md` with `ingested: true` — treat it as already reflected in domain pages
-- Proceed to concept writing when a flow write has failed
-- Create `docs/prd`, `docs/dev`, roadmap, sprint, or backlog-mirror folders
-- Document speculative or future-state features as current truth
-- Put agent task instructions inside human-facing docs pages
-- Leave docs orphaned from `docs/README.md` after adding or renaming them
-- Duplicate content between `<wiki-root>/domains/` (the "what") and `docs/reference/domains/` (the "how")

package/dist/skills/agnostic/docs/docs-maintenance/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Docs Maintenance"
-  short_description: "Wiki ingest plus repo docs maintenance"
-  default_prompt: "Use $docs-maintenance to own the wiki ingest pipeline, then keep docs/ human-facing and implementation-grounded when code changes affect durable knowledge."

package/dist/skills/agnostic/planning/implement-spec/references/parallel-reasoning.md

@@ -1,19 +0,0 @@
-# Codex Parallel Reasoning
-
-Use this reference only when `implement-spec` runs in Codex parallel mode and calls Codex `spawn_agent`.
-
-Set worker `reasoning_effort` lower than the parent orchestrator:
-
-| Orchestrator reasoning | Worker reasoning |
-|------------------------|------------------|
-| `xhigh`                | `high`           |
-| `high`                 | `medium`         |
-| `medium`               | `low`            |
-| `low`                  | `low`            |
-
-Rules:
-
-- This policy is Codex-only. Do not apply it to other models or hosts.
-- Pass the mapped value as `reasoning_effort` in each Codex `spawn_agent` call.
-- Keep orchestration, retries, dependency decisions, and acceptance audit in the parent.
-- If a worker task needs equal or higher reasoning, keep that task in the parent instead of spawning it.

package/docs/README.md

@@ -1,29 +0,0 @@
-# CLI Docs
-
-- [Requirements](./reference/dp-requirements.md)
-- [Scaffolding runbook](./runbooks/dp-cli-scaffolding.md)
-
-Implementation notes:
-
-- canonical bundled scaffold metadata and shared assets live in `src/data/`
-- runtime scaffold content resolves from a `Baseline`: latest remote stable by default, bundled fallback when offline or forced with `--baseline bundled`
-- pack-owned lint asset metadata lives in `src/data/catalog/lint.ts`
-- distributed skill assets live in `skills/`
-- runtime projection/writing logic lives in `src/scaffold/`
-- `punks update` refreshes scaffold-managed assets from `.devpunks/scaffold-manifest.json`
-- CLI startup checks run in a detached advisory worker at most once per 12 hours by default. They check npm's `latest` dist-tag and whether the named `dp-cli` skill is present, but startup never installs or updates packages/skills while another CLI command is starting. Set `DP_NO_UPDATE_CHECK=1` or `DP_NO_SKILL_UPDATE_CHECK=1` to skip those checks, `DP_UPDATE_TAG=next` to compare against another dist-tag, and `DP_STARTUP_CHECK_INTERVAL_MS=0` to force the worker during local testing.
-- baseline releases use `baseline/stable/*` GitHub release tags, separate from npm executable tags such as `v1.0.1`
-- shared neutral hook and sync assets live in `src/data/hooks/` and `src/data/scripts/`; hook commands infer the target repo package manager from `packageManager` and lockfiles
-- scaffolded required tools always include `portless` and `skills` so generated guidance can standardize local dev origins and keep skill entrypoints up to date
-- `punks scaffold setup` checks the base required tools (`portless`, `skills`) before repo detection and checks selected-pack tools after pack confirmation.
-- Oxlint specs/starter config are scaffolded only when scanned manifests already declare `oxlint`; the auto format/lint hook is scaffolded only when manifests declare `oxfmt`. Other lint/format stacks are intentionally left untouched for now.
-- the default debug pack scaffolds the local `debug-agent` skill and installs/verifies the `debug-agent` CLI without running its agent-install wizard
-- scaffolded repos keep project-local skills in `.agents/skills/`; only `.claude/skills` is a compatibility symlink mirror
-- React scaffold surfaces include `async-react-patterns` alongside the existing React composition, structure, and Vercel guidance so agents avoid outdated manual async state patterns.
-- Next.js detection implies the React pack even when `react` / `react-dom` are not directly listed in scanned manifests.
-- Frontend surface detection scaffolds `frontend-domain-structure` with the frontend pack when React or Next.js is detected.
-- Backend surface detection scaffolds `backend-domain-structure`, `backend-recoverable-actions`, and `logging-best-practices` when backend framework/data/auth packages are detected, or when workspace names/paths clearly identify API, backend, server, or service packages. Workspace prompt specs apply backend packs only to backend-looking workspaces, not frontend workspaces that happen to share repo-level backend/data detections.
-- Drizzle detection selects the `drizzle` pack for data-layer prompt/lint metadata, but does not imply Effect skills or Effect opensrc references unless `effect` / `@effect/*` is also detected.
-- Scaffold no longer preselects concrete opensrc repositories. Post-scaffold agents must choose and clone the core detected libraries whose source behavior matters before authoring final prompts or plans.
-- The default subagent manifest includes a read-only `code-review` template that uses `simplify` and `improve-codebase-architecture`; root prompt guidance routes review requests to findings-first review before broad refactor planning.
-- Non-surface agnostic skill groups are mandatory scaffold packs (`debug`, `docs`, `planning`, `quality`, `research`, `requirements`, `subagents`); `frontend` and `backend` remain detection-driven.