devflow-kit 1.8.3 → 2.0.0

package/dist/commands/self-review.md

@@ -0,0 +1,251 @@
+---
+description: Self-review workflow - Simplify agent (code clarity) then Scrutinize agent (9-pillar quality gate)
+---
+# Self-Review Command
+
+Run Simplify agent and Scrutinize agent sequentially on changed files for post-implementation quality refinement.
+
+## Usage
+
+/self-review              (auto-detect changed files from git)
+/self-review <file>...    (review specific files)
+
+## Phases
+
+### Phase 0: Context Gathering
+
+**Produces:** FILES_CHANGED, TASK_DESCRIPTION, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE
+
+Detect changed files and build context:
+
+1. If arguments provided, use those as FILES_CHANGED
+2. Else run `git diff --name-only HEAD` + `git diff --name-only --cached` to get staged + unstaged
+3. If no changes found, report "No changes to review" and exit
+4. Build TASK_DESCRIPTION from recent commit messages or branch name
+### Load DECISIONS_CONTEXT
+
+Resolve the worktree root using the `devflow:worktree-support` algorithm (use WORKTREE_PATH if provided, otherwise cwd). All paths below are relative to `{worktree}`.
+
+**Step 1 — Read the pre-rendered index:**
+
+Attempt to read `{worktree}/.devflow/learning/index.md`.
+
+- If the file exists and contains non-empty content: use that content as `DECISIONS_CONTEXT`.
+- If the file is absent or empty: set `DECISIONS_CONTEXT` to `(none)`.
+
+**No subprocess, no `.cjs` script.** This is a single direct file read — the index is written at render time by `render-decisions.cjs` alongside `decisions.md`/`pitfalls.md`.
+
+**Step 2 — Apply decisions using `devflow:apply-decisions`:**
+
+When `DECISIONS_CONTEXT` is not `(none)`, follow `devflow:apply-decisions` to scan the index, identify plausibly-relevant entries, Read full entry bodies on demand, and cite verbatim IDs in downstream agent prompts and reasoning.
+
+Pass `DECISIONS_CONTEXT` to Scrutinize agent — the compact index lists active ADR/PF entries; Scrutinize agent uses `devflow:apply-decisions` to Read full entry bodies on demand. Known pitfalls help identify reintroduced issues, prior decisions help validate architectural consistency. (Simplify agent does not consume decisions — it operates at code-shape level and Scrutinize agent runs after to catch any architectural drift.)
+
+### Load Feature Knowledge
+
+Resolve the worktree root using the `devflow:worktree-support` algorithm (use WORKTREE_PATH if provided, otherwise cwd). All paths below are relative to `{worktree}`.
+
+**Step 1 — Read the index cache:**
+
+Attempt to read `{worktree}/.devflow/features/index.md`. Each line follows the format:
+
+```
+- **{slug}** — {areas} — {Use-when description}
+```
+
+If `index.md` exists and contains at least one entry line, use it for relevance matching.
+
+**Step 2 — Fallback: glob frontmatter (if `index.md` is absent or empty):**
+
+Glob `{worktree}/.devflow/features/*/KNOWLEDGE.md`. For each file found, read only its YAML frontmatter block (between the opening and closing `---` delimiters). The frontmatter fields `name`, `description`, and `directories` are the authoritative relevance surface — `index.md` is only a cache.
+
+**Step 3 — Pick relevant KBs:**
+
+Match the current task area and description against each index line (or frontmatter `description` + `directories` on fallback). Select entries whose documented area overlaps the current task. This is a relevance judgment — prefer specificity over breadth.
+
+**Step 4 — Read selected KBs:**
+
+For each selected entry, read `{worktree}/.devflow/features/{slug}/KNOWLEDGE.md` in full. When the KB content contradicts the current code you observe, **trust the code** — the code is the freshness mechanism; the KB may lag behind.
+
+**Step 5 — Set FEATURE_KNOWLEDGE:**
+
+Concatenate the selected KNOWLEDGE.md files under slug headers:
+
+```
+--- Feature knowledge: {slug} ---
+{full KNOWLEDGE.md content}
+```
+
+If no KBs exist, no KBs are relevant, or `.devflow/features/` is absent, set `FEATURE_KNOWLEDGE` to `(none)`.
+
+**No subprocess, no git calls, no `.cjs` script.** This entire step is direct file reads — 1 index read (or N frontmatter reads on fallback), bounded by KB count.
+
+Pass `FEATURE_KNOWLEDGE` to Scrutinize agent.
+
+**Extract:** FILES_CHANGED (list), TASK_DESCRIPTION (string), DECISIONS_CONTEXT (string, optional), FEATURE_KNOWLEDGE (string, optional)
+
+### Phase 1: Simplify agent (Code Refinement)
+
+**Produces:** SIMPLIFY_COMMITS
+**Requires:** FILES_CHANGED, TASK_DESCRIPTION
+
+Spawn Simplify agent to refine code for clarity and consistency:
+
+Agent(subagent_type="Simplify", run_in_background=false):
+"TASK_DESCRIPTION: {task_description}
+FILES_CHANGED: {files_changed}
+Simplify and refine the code for clarity and consistency while preserving functionality."
+
+**Wait for completion.** Simplify agent commits changes directly.
+
+### Phase 2: Scrutinize agent (9-Pillar Quality Gate)
+
+**Produces:** SCRUTINIZE_STATUS, SCRUTINIZE_CHANGES
+**Requires:** FILES_CHANGED, TASK_DESCRIPTION, DECISIONS_CONTEXT
+
+Spawn Scrutinize agent for quality evaluation and fixing:
+
+Agent(subagent_type="Scrutinize", run_in_background=false):
+"TASK_DESCRIPTION: {task_description}
+FILES_CHANGED: {files_changed}
+DECISIONS_CONTEXT: {decisions_context}
+FEATURE_KNOWLEDGE: {feature_knowledge}
+Evaluate against 9-pillar framework. Fix P0/P1 issues. Return structured report.
+Follow devflow:apply-decisions to scan DECISIONS_CONTEXT and Read full ADR/PF bodies on demand. Skip if (none).
+Follow devflow:apply-feature-knowledge for FEATURE_KNOWLEDGE. Skip if (none)."
+
+**Wait for completion.** Extract: STATUS (PASS|FIXED|BLOCKED), changes_made (bool)
+
+### Phase 3: Conditional Validation
+
+**Produces:** VALIDATION_RESULT
+**Requires:** SCRUTINIZE_CHANGES
+
+If Scrutinize agent made changes (STATUS == FIXED):
+
+Agent(subagent_type="Validate", run_in_background=false):
+"FILES_CHANGED: {scrutinize_modified_files}
+VALIDATION_SCOPE: changed-only
+Run build, typecheck, lint, test on modified files"
+
+**If FAIL:** Report validation failures to user and halt
+**If PASS:** Continue to report
+
+### Phase 4: Report
+
+**Requires:** SCRUTINIZE_STATUS, VALIDATION_RESULT
+
+Display summary:
+
+## Self-Review Complete
+
+**Files Reviewed**: {n}
+**Status**: {PASS|FIXED|BLOCKED}
+
+### Simplify agent
+- {n} files refined for clarity
+
+### Scrutinize agent (9-Pillar Evaluation)
+| Pillar | Status |
+|--------|--------|
+| Design | {status} |
+| Functionality | {status} |
+| Security | {status} |
+| Complexity | {status} |
+| Error Handling | {status} |
+| Tests | {status} |
+| Naming | {status} |
+| Consistency | {status} |
+| Documentation | {status} |
+
+### Commits Created
+- {sha} {message}
+
+{If BLOCKED: ### Blocking Issue\n{description}}
+
+### Feature Knowledge Write-Back (Conditional)
+
+Resolve the worktree root using the `devflow:worktree-support` algorithm (use WORKTREE_PATH if provided, otherwise cwd). All paths below are relative to `{worktree}`.
+
+**Step 1 — Check the opt-out gate:**
+
+Read `{worktree}/.devflow/config.json`. If the `knowledge` field is `false`, skip write-back entirely — the user has disabled it.
+
+If `.devflow/config.json` does not exist, proceed (default is enabled).
+
+**Step 2 — Evaluate whether write-back is warranted:**
+
+Only proceed if **at least one** of these is true:
+- This workflow changed files in a directory that is documented by an existing feature knowledge base (a documented area changed).
+- This workflow surfaced durable, cross-cutting knowledge about a codebase area that would help future agents working in the same area — patterns, anti-patterns, integration points, gotchas not visible from a single file read.
+
+**Never spawn unconditionally.** If neither condition is met, skip write-back silently.
+
+**Step 3 — Spawn the Knowledge agent:**
+
+Spawn `Agent(subagent_type="Knowledge")` with the following context:
+
+```
+"WORKTREE_PATH: {worktree root}
+FEATURE_SLUG: {slug derived from primary changed directory, kebab-case}
+FEATURE_NAME: {human-readable name}
+DIRECTORIES: {list of primary directories touched by this workflow}
+FILES_CHANGED: {list of files changed}
+DECISIONS_CONTEXT: {DECISIONS_CONTEXT if available, else (none)}
+
+Load the devflow:feature-knowledge skill and follow its authoring process.
+
+Write the knowledge base to:
+  {worktree}/.devflow/features/{slug}/KNOWLEDGE.md
+
+Then update the index cache by performing a read-modify-write on:
+  {worktree}/.devflow/features/index.md
+
+Index line format: `- **{slug}** — {areas} — {Use-when description}`
+
+If the line for this slug already exists in index.md, replace it. If it does not exist, append it. If index.md does not exist, create it with just this line.
+
+The frontmatter in KNOWLEDGE.md is the source of truth — index.md is only a cache. Write the two files directly — no intermediate result JSON files, no external scripts.
+
+After writing, commit the two files to the current worktree branch yourself by running git via your Bash tool (do not use a script). Stage ONLY .devflow/features/index.md and .devflow/features/{slug}/KNOWLEDGE.md, then commit just those paths with a docs(knowledge): message. Do NOT push, do NOT force, do NOT stage anything else. Follow your Commit Protocol — it is non-blocking, so if any git step fails, report KB_COMMIT and finish normally."
+```
+
+**Failure handling**: Non-blocking. If the Knowledge agent fails, log the failure and continue — the workflow outcome is not affected by write-back success.
+
+## Architecture
+
+/self-review (orchestrator)
+│
+├─ Phase 0: Context gathering
+│  ├─ Git diff for changed files
+│  └─ Read index.md → DECISIONS_CONTEXT
+│
+├─ Phase 1: Simplify agent
+│  └─ Code refinement (commits directly)
+│
+├─ Phase 2: Scrutinize agent
+│  └─ 9-pillar quality gate (may fix and commit)
+│
+├─ Phase 3: Validate agent (conditional)
+│  └─ If Scrutinize agent made changes, verify tests pass
+│
+└─ Phase 4: Report
+   └─ Display summary with pillar status
+
+## Edge Cases
+
+| Case | Handling |
+|------|----------|
+| No changes | Report "No changes to review" and exit |
+| Simplify agent finds nothing | Normal, continue to Scrutinize agent |
+| Scrutinize agent BLOCKED | Report blocking issue, halt workflow |
+| Validation fails | Report failures, halt (don't create broken state) |
+| Not in git repo | Report error, suggest running in git repo |
+
+## Principles
+
+1. **Orchestration only** - Command spawns agents, doesn't do the work
+2. **Sequential execution** - Simplify agent must complete before Scrutinize agent
+3. **Validation gate** - If Scrutinize agent changes code, must pass validation
+4. **Honest reporting** - Display actual agent outputs
+5. **Fail fast** - Stop on BLOCKED or validation failure

package/dist/core/agent-frontmatter.js

@@ -0,0 +1,209 @@
+/**
+ * Agent frontmatter rewriting utilities.
+ *
+ * Pure module — zero I/O. All functions take content strings and return
+ * new content strings; callers own file reads and writes.
+ *
+ * applies ADR-013: pure core-layer module, no Claude Code adapter concerns.
+ * avoids PF-014: no process.exit(); all fallible paths return Result.
+ *
+ * Regex scoping guarantee: ALL operations are confined to the FIRST `---…---`
+ * block. Model/effort lines in the document body are never touched.
+ *
+ * EOL safety: CRLF files are detected by checking the first frontmatter
+ * delimiter line. The EOL token is threaded through all replacements so the
+ * output preserves the file's original line-ending style byte-for-byte.
+ */
+// ---------------------------------------------------------------------------
+// Model name validation — shared charset used at every write boundary
+// ---------------------------------------------------------------------------
+/**
+ * Regex that model names must satisfy before being written to any agent
+ * frontmatter. The same charset is used at the CLI entry point so injection
+ * payloads are rejected before they can propagate.
+ *
+ * Rules:
+ *  - Start with an alphanumeric character.
+ *  - Remaining characters: alphanumeric, dot, underscore, hyphen.
+ *  - Total length: 1–64 characters.
+ *
+ * Accepts all real Anthropic model IDs (e.g. "claude-3-5-sonnet-20241022"),
+ * devflow aliases ("sonnet", "opus", "haiku", "fable", "inherit"), and
+ * well-formed third-party IDs (e.g. "gpt-5.6-sol").
+ */
+export const MODEL_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/**
+ * Returns true when `model` passes the MODEL_NAME_RE charset test.
+ * Use at every trust boundary before passing `model` to rewriteAgentFrontmatter.
+ */
+export function isValidModelName(model) {
+    return MODEL_NAME_RE.test(model);
+}
+function Ok(value) {
+    return { ok: true, value };
+}
+function Err(error) {
+    return { ok: false, error };
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Detect EOL style from the opening `---` line.
+ * Returns '\r\n' for CRLF files, '\n' for LF files.
+ */
+function detectEol(content) {
+    return content.startsWith('---\r\n') ? '\r\n' : '\n';
+}
+function parseFrontmatter(content) {
+    const eol = detectEol(content);
+    // Must begin with `---<EOL>`
+    if (!content.startsWith(`---${eol}`)) {
+        return Err('no-frontmatter');
+    }
+    // Regex for the FIRST `---…---` block only.
+    // Capture groups: 1=body, 2=line-ending of closing delimiter (may be empty at EOF).
+    const FM_RE = /^---\r?\n([\s\S]*?)\r?\n---(\r?\n|$)/;
+    const m = FM_RE.exec(content);
+    if (!m) {
+        return Err('unterminated-frontmatter');
+    }
+    const fullMatch = m[0];
+    const fmBody = m[1];
+    const closeEol = m[2];
+    const openDelim = `---${eol}`;
+    const closeDelim = `---${closeEol}`;
+    const afterClose = content.slice(fullMatch.length);
+    return Ok({ fmBody, openDelim, closeDelim, afterClose, eol });
+}
+// ---------------------------------------------------------------------------
+// readFrontmatterModel
+// ---------------------------------------------------------------------------
+/**
+ * Read the `model:` value from the first frontmatter block.
+ *
+ * Returns Result<string, FrontmatterError> where the string is the trimmed
+ * model identifier. Returns an error for missing or unterminated frontmatter.
+ * Does NOT error if no `model:` line exists (returns Ok('')).
+ *
+ * Scoped to the frontmatter block only — a `model:` line in the body is ignored.
+ */
+export function readFrontmatterModel(content) {
+    const parts = parseFrontmatter(content);
+    if (!parts.ok)
+        return Err(parts.error);
+    const MODEL_RE = /^model:[ \t]*(.*?)[ \t]*$/m;
+    const m = MODEL_RE.exec(parts.value.fmBody);
+    return Ok(m ? m[1] : '');
+}
+/**
+ * Rewrite the `model:` and optionally `effort:` lines in the first
+ * frontmatter block of `content`.
+ *
+ * Rules:
+ *  - Only the FIRST `---…---` block is modified; body bytes are untouched.
+ *  - EOL style (LF or CRLF) is detected and preserved throughout.
+ *  - `effort: null` removes the effort line and exactly one adjacent EOL
+ *    (preceding when effort is last, trailing otherwise) — no global collapse.
+ *  - When effort is a string: insert after model line (if absent) or replace
+ *    existing effort line.
+ *  - `changed` is a byte-level comparison — cheap idempotency check.
+ *
+ * Returns Result error for:
+ *  - `no-frontmatter`: content does not begin with `---<EOL>`.
+ *  - `unterminated-frontmatter`: opening `---` has no closing `---`.
+ */
+export function rewriteAgentFrontmatter(content, opts) {
+    // Frontmatter injection guard: reject model names that do not satisfy
+    // MODEL_NAME_RE before touching the file. Without this check, a name such as
+    //   "gpt-4\ntools:\n  - bash"
+    // would be interpolated raw into `newBody.replace(MODEL_RE, ...)`, injecting
+    // arbitrary YAML into the frontmatter block.
+    if (!isValidModelName(opts.model)) {
+        return Err('invalid-model');
+    }
+    const partsResult = parseFrontmatter(content);
+    if (!partsResult.ok)
+        return Err(partsResult.error);
+    const { fmBody, openDelim, closeDelim, afterClose, eol } = partsResult.value;
+    // -------------------------------------------------------------------------
+    // 1. Update model line
+    // -------------------------------------------------------------------------
+    const MODEL_RE = /^model:[ \t]*(.*?)[ \t]*$/m;
+    const modelMatch = MODEL_RE.exec(fmBody);
+    const currentModel = modelMatch ? modelMatch[1] : '';
+    let newBody = fmBody;
+    if (currentModel !== opts.model) {
+        if (modelMatch) {
+            // Replace the first model line (only)
+            newBody = newBody.replace(MODEL_RE, `model: ${opts.model}`);
+        }
+        else {
+            // No model line — insert before the first key-value line as a fallback.
+            // (All real agent files have a model line, so this path exists for robustness.)
+            newBody = `model: ${opts.model}${eol}${newBody}`;
+        }
+    }
+    // -------------------------------------------------------------------------
+    // 2. Update effort line
+    // -------------------------------------------------------------------------
+    const EFFORT_RE = /^effort:[ \t]*(.*?)[ \t]*$/m;
+    const effortMatch = EFFORT_RE.exec(newBody);
+    const currentEffort = effortMatch ? effortMatch[1] : null;
+    if (opts.effort !== null) {
+        // Add or replace
+        if (effortMatch) {
+            if (currentEffort !== opts.effort) {
+                // Use a replacement function — NOT a string — so that $&, $`, $',
+                // and $1 in opts.effort are written verbatim rather than expanded as
+                // replacement patterns (avoids PF-018).
+                newBody = newBody.replace(EFFORT_RE, () => `effort: ${opts.effort}`);
+            }
+        }
+        else {
+            // Insert immediately after the model line
+            const MODEL_RE2 = /^model:[ \t]*.*$/m;
+            newBody = newBody.replace(MODEL_RE2, (match) => `${match}${eol}effort: ${opts.effort}`);
+        }
+    }
+    else {
+        // effort: null — remove effort line if present.
+        //
+        // D-EFR-1: Remove ONLY the matched effort line plus exactly one adjacent
+        // EOL. Never run a global \n{2,} collapse — that would silently corrupt
+        // any multi-line YAML value that legitimately contains a blank line.
+        //
+        // EOL consumed:
+        //   • effort is last line  → consume the PRECEDING \r?\n (no trailing EOL
+        //     exists in fmBody), so reassembly doesn't produce a stray blank line.
+        //   • effort is mid-body   → consume the TRAILING \r?\n after the line.
+        //   • effort is first+only → clear the body entirely.
+        if (effortMatch) {
+            const effortStart = effortMatch.index;
+            const effortEnd = effortStart + effortMatch[0].length;
+            if (effortEnd < newBody.length) {
+                // Not the last line: swallow the trailing EOL (\r?\n) after the line.
+                const trailingEolLen = newBody[effortEnd] === '\r' ? 2 : 1;
+                newBody = newBody.slice(0, effortStart) + newBody.slice(effortEnd + trailingEolLen);
+            }
+            else if (effortStart > 0) {
+                // Last line: swallow the preceding EOL (\r?\n) before the line.
+                const eolStart = (effortStart >= 2 && newBody[effortStart - 2] === '\r')
+                    ? effortStart - 2
+                    : effortStart - 1;
+                newBody = newBody.slice(0, eolStart) + newBody.slice(effortEnd);
+            }
+            else {
+                // effort is the first and only line — clear the body.
+                newBody = '';
+            }
+        }
+    }
+    // -------------------------------------------------------------------------
+    // 3. Reassemble and check for changes
+    // -------------------------------------------------------------------------
+    const newContent = openDelim + newBody + eol + closeDelim + afterClose;
+    const changed = newContent !== content;
+    return Ok({ content: newContent, changed });
+}
+//# sourceMappingURL=agent-frontmatter.js.map