@khoavu882/doflow 0.0.0-stage → 2.0.0-beta.3

package/core/shared/skills/do-code-review/assets/sample_java_clean.java

@@ -0,0 +1,55 @@
+// Sample Java file showing the fixed version of sample_java_smells.java.
+// Same shape, but every smell has been resolved per the patterns documented
+// in rules/universal.md and languages/java.md.
+//
+// Run:
+//   python scripts/code_quality_checker.py assets/sample_java_clean.java
+//
+// Expected: no HIGH Java-specific smells flagged.
+
+package sample;
+
+import java.io.FileInputStream;
+import java.io.InputStream;
+import java.sql.Connection;
+import java.sql.PreparedStatement;
+import java.sql.ResultSet;
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+public class UserService {
+
+    // FIX: heavy object shared as a singleton instead of constructed per call.
+    private static final ObjectMapper MAPPER = new ObjectMapper();
+
+    // FIX: connection string injected from configuration, never inlined.
+    private final String connectionString;
+
+    public UserService(String connectionString) {
+        this.connectionString = connectionString;
+    }
+
+    public String getName(Connection conn, int id) {
+        // FIX: try-with-resources guarantees the stream and statement close.
+        try (InputStream config = new FileInputStream("/etc/config");
+             // FIX: parameterized query, no string concatenation.
+             PreparedStatement stmt =
+                 conn.prepareStatement("SELECT name FROM users WHERE id = ?")) {
+            stmt.setInt(1, id);
+            try (ResultSet rs = stmt.executeQuery()) {
+                return rs.next() ? rs.getString("name") : null;
+            }
+        } catch (Exception e) {
+            // FIX: rethrow with context instead of swallowing.
+            throw new IllegalStateException("Failed to load user " + id, e);
+        }
+    }
+
+    public void process() {
+        try {
+            Thread.sleep(1000);
+        } catch (InterruptedException e) {
+            // FIX: restore the interrupt flag so cancellation still propagates.
+            Thread.currentThread().interrupt();
+        }
+    }
+}

package/core/shared/skills/do-code-review/assets/sample_java_smells.java

@@ -0,0 +1,56 @@
+// Sample Java file demonstrating the Java-specific patterns the code-reviewer
+// skill detects. Each smell is labelled inline. This file is NOT meant to
+// compile cleanly — it is a fixture for code_quality_checker.py and
+// pr_analyzer.py.
+//
+// Run:
+//   python scripts/code_quality_checker.py assets/sample_java_smells.java
+//
+// Expected output: see expected_outputs/sample_java_smells_quality.json
+
+package sample;
+
+import java.io.FileInputStream;
+import java.sql.Connection;
+import java.sql.Statement;
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+public class UserService {
+
+    // [hardcoded_secrets] hardcoded JDBC URL with password
+    public String connectionString = "jdbc:postgresql://prod/app?user=app&password=hunter2";
+
+    // [analyzer_disable] @SuppressWarnings without justification
+    @SuppressWarnings("unchecked")
+    public String getName(Connection conn, int id) throws Exception {
+        // [java_unclosed_resource] FileInputStream not in try-with-resources
+        FileInputStream fis = new FileInputStream("/etc/config");
+
+        // [java_per_use_heavy_object] new ObjectMapper() constructed per call
+        ObjectMapper mapper = new ObjectMapper();
+
+        try {
+            Statement stmt = conn.createStatement();
+            // [sql_concatenation] string concatenation builds SQL with user input
+            return stmt.executeQuery("SELECT name FROM users WHERE id = " + id).toString();
+        } catch (Exception e) {
+            // [java_empty_catch] empty catch swallows the exception
+        }
+        return null;
+    }
+
+    public void process() {
+        try {
+            Thread.sleep(1000);
+        } catch (InterruptedException e) {
+            // [java_swallowed_interrupt] interrupt flag not restored
+            // [console_log] printStackTrace used as error handling
+            e.printStackTrace();
+        }
+    }
+
+    public void log(String message) {
+        // [console_log] System.out.println left in production code
+        System.out.println(message);
+    }
+}

package/core/shared/skills/do-code-review/assets/sample_json_clean.json

@@ -0,0 +1,7 @@
+{
+  "name": "sample",
+  "version": "1.0.0",
+  "scripts": {
+    "test": "node --test"
+  }
+}

package/core/shared/skills/do-code-review/assets/sample_markdown_clean.md

@@ -0,0 +1,30 @@
+---
+name: sample-markdown-clean
+description: >
+  Reviews markdown and prose content for structural health. Use when checking a SKILL.md or
+  agent-spec file for a missing Boundaries section, a weak triggering description, dangling
+  references/ or modes/ cross-references, or leftover staleness language such as "deprecated".
+---
+
+# Sample Markdown Skill (Clean Fixture)
+
+This is a synthetic fixture for `doc_quality_checker.py` — a well-formed document with a
+strong triggering description, an explicit Boundaries section, and no dangling references or
+stale language, so it should produce zero findings.
+
+Run:
+  python scripts/doc_quality_checker.py assets/sample_markdown_clean.md
+
+Expected output: see expected_outputs/sample_markdown_clean_quality.json
+
+## Boundaries
+
+**Will:** analyze markdown and prose files for structural health issues — missing Boundaries
+sections, weak triggering descriptions, dangling cross-references, and staleness markers.
+
+**Will Not:** compute a code-smell quality score for prose, or judge subjective writing quality
+beyond the deterministic patterns listed above.
+
+## Usage
+
+Run the tool against a target file or directory and read the findings it prints.

package/core/shared/skills/do-code-review/assets/sample_markdown_smells.md

@@ -0,0 +1,29 @@
+---
+name: sample-markdown-smells
+description: Helps with markdown stuff sometimes.
+---
+
+# Sample Markdown Skill (Smells Fixture)
+
+This is a synthetic fixture for `doc_quality_checker.py` — NOT a real skill, just a document
+shaped like a `SKILL.md` (frontmatter, a short description, a body) so the checker's
+content-agnostic checks (dangling references, staleness markers) have real prose to exercise.
+It intentionally omits a `## Boundaries` section and uses a weak, un-triggering description,
+mirroring the structural gaps `doc_quality_checker.py` is built to catch on a real SKILL.md.
+
+Run:
+  python scripts/doc_quality_checker.py assets/sample_markdown_smells.md
+
+Expected output: see expected_outputs/sample_markdown_smells_quality.json
+
+## Overview
+
+For the full background on this pattern, see `references/does-not-exist.md`, which was never
+written.
+
+This approach is deprecated and should not be used anymore — teams should migrate away from it
+entirely before relying on any of the examples below.
+
+## Usage
+
+Run the tool against a target file or directory and read the findings it prints.

package/core/shared/skills/do-code-review/assets/sample_shell_heredoc.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# Fixture for _blank_heredocs. Guards three behaviours at once; see code_quality_checker.py.
+set -euo pipefail
+
+# 1. Heredoc body is prose only. Real complexity is 1; every keyword below is text.
+usage() {
+  cat <<'EOF'
+Usage: tool [options]
+  Pick one or the other and then decide if you want more.
+  If the file exists and the flag is set or the mode is auto, it will run.
+  Use for each item, while any remain, and case by case.
+EOF
+}
+
+# 2. Real branches around a heredoc are still counted: if + while + case.
+emit() {
+  if [ -n "${1:-}" ]; then
+    cat <<-INDENTED
+	this or that and if for while case
+	INDENTED
+  fi
+  while read -r line; do
+    case "$line" in a) ;; *) ;; esac
+  done
+}
+
+# 3. An opener whose terminator never appears is not a heredoc, so the branches
+#    below it must stay visible rather than being blanked to end-of-file.
+unterminated() {
+  echo "<<NEVERCLOSED is only mentioned, never opened"
+  if [ -f /tmp/x ] && [ -d /tmp ]; then
+    for i in 1 2 3; do echo "$i"; done
+  fi
+}
+
+usage
+emit
+unterminated

package/core/shared/skills/do-code-review/assets/sample_shell_smells.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# A script with the failure modes shell review exists to catch.
+
+deploy_release() {
+  cd $RELEASE_DIR
+  rm $STALE_ARTIFACT
+  cp $SOURCE $DEST
+}
+
+function rollback {
+  cd /var/tmp
+  cat $LOGFILE
+}
+
+deploy_release

package/core/shared/skills/do-code-review/assets/sample_typescript_strings.ts

@@ -0,0 +1,36 @@
+// Regression asset for string-literal handling in cyclomatic complexity.
+//
+// Before strip_string_literals, every "or"/"and"/"if"/"for" inside these strings counted as a
+// branch. This function has exactly two real branches; the prose in its messages has many more
+// words that the keyword scan used to charge it for.
+
+export function describeOutcome(state: string, retries: number): string {
+  const messages = {
+    blocked: "evidence disagrees and a human must reconcile it, or the gate stays shut",
+    ready: "every prerequisite is verified and no claim is conflicted",
+    waiting: "waiting for a build or a test or a review, and then for approval",
+    failed: "the run failed and the cause was not classified for a retry",
+    unknown: "no outcome was recorded, if indeed the task ever started",
+  };
+
+  if (state in messages) {
+    return messages[state as keyof typeof messages];
+  }
+  return retries > 0 ? "retrying after a transient error" : "no state and no retries";
+}
+
+export const BANNER = `report generated for review — pass or fail, and every skipped file named`;
+
+// Multi-line template literal. Before the spanning pass, every keyword in this prose counted as a
+// branch on whichever function the slice attributed it to.
+export const REPORT_TEMPLATE = `
+  Coverage was partial and the verdict describes the analysed files only.
+  If a file could not be read it is named here, and if a check could not run
+  it is reported as not run — for every file in the set, or the report is
+  incomplete and the score means less than it appears to.
+`;
+
+export function pick(kind: string): number {
+  if (kind === "wide") { return 2; }
+  return 1;
+}

package/core/shared/skills/do-code-review/assets/sample_yaml_smells.yaml

@@ -0,0 +1,6 @@
+service:
+  name: payments
+  name: payments-v2
+  database:
+    password: sup3rs3cr3tvalue
+    host: db.internal

package/core/shared/skills/do-code-review/content-types/config.md

@@ -0,0 +1,83 @@
+---
+content-type: config
+extensions: [".yaml", ".yml", ".json"]
+---
+
+# Declarative Config — Content-Specific Review Notes
+
+YAML and JSON are not `languages/*.md` entries. The language template's required sections
+(Async/Concurrency, Resource Management, Exception Handling, Performance) describe code-execution
+concerns that do not exist for declarative data. Forcing config through that template would produce
+empty or fabricated sections — the same reasoning that puts markdown in `content-types/`.
+
+More concretely: a cyclomatic complexity, a function count, or a SOLID verdict for a YAML file is a
+number with nothing behind it. Reporting one is precisely the false-confidence defect that adding
+these analysers was meant to remove, so the analyser reports none of them and this file names no
+rule that would need one.
+
+Load this file **instead of** `rules/universal.md` plus a language file. It has no universal
+counterpart, same as `content-types/markdown.md`.
+
+---
+
+## What the analyser checks deterministically
+
+`scripts/code_quality_checker.py` routes these extensions to its declarative path and reports:
+
+| Check | Why it matters |
+|---|---|
+| Parse validity | A JSON file that does not parse is a deploy-time failure, not a review comment |
+| Duplicate keys at one level | The later value silently wins; the earlier one looks live but is dead |
+| Nesting depth | Past a point, an indentation mistake is undetectable by reading |
+| Credential-shaped literals | A `password:`/`token:`/`api_key:` with a literal value in a committed file |
+
+Everything below is for the reviewer, not the analyser.
+
+## Correctness
+
+- **Duplicate keys** — YAML permits them and resolves to the last; most parsers do not warn. Check
+  merged or templated files especially, where a key can be introduced twice from different sources.
+- **Type coercion** — unquoted `yes`, `no`, `on`, `off`, `true`, `false` become booleans in YAML 1.1;
+  `NO` as a country code and `on` as a key have both caused real outages. Quote strings that could
+  be read as another type.
+- **Sexagesimal and octal** — an unquoted `1:30` can parse as 90, and a leading zero can mean octal.
+  Version strings and identifiers are quoted.
+- **Anchors and aliases** — `&anchor` / `*alias` save repetition but move the definition away from
+  the use. Deep anchor chains are a readability finding; an alias that overrides only some keys via
+  merge (`<<:`) is a correctness one, since merge order is not obvious.
+- **Empty vs absent** — `key:` with no value is null, which is not the same as the key being absent.
+  Confirm the consumer treats them the same way if the file relies on it.
+
+## Security
+
+- No credential literals: passwords, tokens, API keys, private keys, connection strings with
+  embedded auth. A value that looks like a placeholder still ships if nothing replaces it.
+- A permissive default is a finding: `allowAll`, `verify: false`, `insecureSkipTLSVerify`,
+  `0.0.0.0/0`, a wildcard CORS origin. Each needs a comment saying why.
+- Check that a config claiming to reference a secret store actually does, rather than naming one in
+  a comment beside a literal.
+
+## Structure and Maintainability
+
+- **Depth** — deeply nested config is hard to review and easy to mis-indent. Prefer a flatter shape
+  or a split file over another level.
+- **Duplication across environments** — three near-identical env files drift. Look for the one key
+  that differs by accident rather than by intent.
+- **Ordering and grouping** — related keys adjacent, and a consistent order across sibling files, so
+  a diff between two environments is readable.
+- **Comments** — a non-obvious value (a timeout, a magic port, a feature flag) carries a comment
+  saying what it is for. A config file has no other place to put the reasoning.
+
+## API Specifications (OpenAPI, JSON Schema)
+
+Treated as config here rather than as a separate content type — the checks above all apply, plus:
+
+- Every operation has an `operationId`, and it is unique across the document.
+- Every response the implementation can return is documented, including the error shapes.
+- `required` is stated explicitly on request bodies; an omitted `required` reads as optional.
+- `additionalProperties` is decided rather than defaulted, since the default is permissive.
+- `$ref` targets resolve within the document or to a file that ships with it.
+- Examples parse against their own schema — an example that contradicts its schema is worse than
+  none, because tooling generates from it.
+- No DoFlow-internal identifiers in `description` or `summary` fields — run
+  `doflow leak-scan --path <spec>`; see the skill's Review Contract.

package/core/shared/skills/do-code-review/content-types/markdown.md

@@ -0,0 +1,132 @@
+---
+content-type: markdown
+extensions: [".md"]
+---
+
+# Markdown / Prose — Content-Specific Review Notes
+
+Markdown is not treated as a `languages/*.md` entry. The language files' required sections
+(Security, Async, Resource Management, Exception Handling, Performance) describe code-execution
+concerns that do not translate to prose — forcing markdown through that template would produce
+empty or fabricated sections, which is exactly the "invented metrics" problem that
+the guidance tree's `rules/RULE_03_QUALITY.md` warns against under "Professional Honesty". This file documents a
+content-type-specific set of checks instead, run by `scripts/doc_quality_checker.py`.
+
+Load this file when the reviewed path is a `.md` file. There is no `rules/universal.md`
+equivalent for prose — every check below is either skill-specific or guidance-tree-wide, as
+noted per check.
+
+---
+
+## Tool
+
+```bash
+# Analyze a single file or a directory of .md files
+python scripts/doc_quality_checker.py <path>
+
+# JSON output — same finding-list shape as code_quality_checker.py --json
+python scripts/doc_quality_checker.py <path> --json
+```
+
+Every check below is deterministic and cite-the-match: a finding names the exact line, phrase,
+or reference that triggered it. There is no aggregate "quality score" — per "Professional Honesty"
+in the guidance tree's `rules/RULE_03_QUALITY.md`, an invented single-number score would claim more
+precision than a pattern match can support. Treat every finding as "here is the specific thing to
+look at," not as a verdict; confirm it against the actual file before editing (the same
+manual-verification discipline this feature's own audit applies to its own tooling).
+
+---
+
+## Checks
+
+### 1. Length (SKILL.md files only)
+
+**Applies to:** `SKILL.md` files specifically — not every `.md` file in the tree.
+
+Flags a `SKILL.md` whose line count exceeds skill-creator's progressive-disclosure guideline of
+roughly 500 lines. The guideline exists so a skill's main file stays a dispatch/overview surface,
+pushing detail into `references/`, `languages/`, `modes/`, or similar sibling files rather than
+growing one monolithic document. A finding here cites the actual line count against the ~500-line
+threshold — it does not judge whether the content itself is good or bad, only that it has likely
+outgrown the single-file shape.
+
+**Interpretation:** if flagged, look for content that belongs in a sibling reference file instead
+of `SKILL.md` itself; splitting content out (not just trimming prose) is usually the fix.
+
+### 2. Boundaries section (SKILL.md and agent-spec files)
+
+**Applies to:** `SKILL.md` files, and specialist agent-definition files — identified by
+frontmatter shape (`model:` plus either `tools:` or `effort:`, with no `argument-hint:`), not by a
+fixed path. This recognizes existing agent files that have `tools:` but no `effort:`, along with
+the current shared shape, where `tools:` is optional and the host provides the available tool pool.
+This repo keeps its own agent definitions under `core/shared/agent-specs/`, but every harness
+installs them under a differently-named directory (typically `agents/`), so the check deliberately
+does not hardcode a source-tree path — it works the same way against an installed copy in any
+project as it does against this repo's own source.
+
+Flags a file that lacks a `## Boundaries` section, or has one that does not frame scope with
+explicit Will / Will Not language. This check is guidance-tree-wide in the sense that it runs
+against both file kinds — a skill and an agent spec are held to the same expectation that scope is
+stated, not implied.
+
+**Interpretation:** a finding here means the file's scope is not explicit, not that it is wrong.
+Add a `## Boundaries` section (or a Will / Will Not pair inside an existing one) describing what
+the skill or archetype does and, as importantly, what it deliberately does not do.
+
+### 3. Triggering description (SKILL.md frontmatter `description:` field)
+
+**Applies to:** the `description:` field in `SKILL.md`'s YAML frontmatter only.
+
+Flags a description that is under roughly 40 words, or that does not contain a concrete trigger
+phrase or example (e.g., "Use when reviewing pull requests..."). This follows skill-creator's
+"make it a little pushy" guidance: the description is what a dispatching agent reads to decide
+whether to load the skill at all, so a vague or generic description under-triggers it.
+
+**Interpretation:** a finding here cites the current description's word count and/or the absence
+of a "Use when..." style clause. The fix is a more specific description naming concrete scenarios,
+not a longer description for its own sake — length and specificity are separate signals and both
+should hold.
+
+### 4. Dangling cross-reference
+
+**Applies to:** any `.md` file under the reviewed path (skills, agent specs, or guidance).
+
+Flags any mention of a `references/<name>.md` or `modes/<name>.md` style path that does not resolve
+to a real file on disk relative to the reviewing file's own location. This is guidance-tree-wide —
+the same broken-link risk exists whether the dangling mention is in a skill, an agent spec, or a
+guidance rule file.
+
+**Interpretation:** a finding here cites the exact dangling path string and the file it appeared
+in. Either the referenced file needs to be created, or the mention needs to be corrected/removed
+— check which is intended before editing, since a dangling reference can indicate an unfinished
+file just as easily as a stale one.
+
+### 5. Staleness markers
+
+**Applies to:** any `.md` file under the reviewed path.
+
+Conservatively flags prose containing deprecated / legacy / no longer / outdated / obsolete
+language. This check is deliberately conservative: it does not flag a rule or guard whose own
+*description* quotes one of these words as the thing being detected (for example, a staleness
+guard's own doc-comment listing "deprecated" as a pattern it searches for is not itself stale
+prose). Only prose asserting that the surrounding content itself is deprecated/legacy/outdated is
+flagged.
+
+**Interpretation:** this check exists to catch false positives, not manufacture them — the
+design-phase investigation for this feature already found that a naive keyword grep for
+words like "deprecated" produces false positives against files that quote the word as a detection
+target rather than describing themselves as stale. Confirm the matched sentence actually describes
+the file's own content as outdated before treating it as a real finding; if it is a rule
+description quoting the word, it is not a defect.
+
+---
+
+## Adding a New Content Type
+
+Follow the same two-step pattern `languages/*.md` uses for code, but do not reuse that template's
+required sections — they are code-execution concerns and do not apply to prose:
+
+1. Create `content-types/<name>.md` describing the checks specific to that content type, not the
+   `languages/*.md` section shape (PR Analyzer Signals, Security, Async, Resource Management,
+   Exception Handling, Performance, Idioms do not translate to non-code content).
+2. Add the content-type row to the dispatch table in `SKILL.md`.

package/core/shared/skills/do-code-review/expected_outputs/sample_c_clean_quality.json

@@ -0,0 +1,79 @@
+{
+  "file": "assets/sample_c_clean.c",
+  "language": "c",
+  "metrics": {
+    "lines": {
+      "total": 72,
+      "code": 43,
+      "blank": 17,
+      "comment": 12
+    },
+    "functions": 4,
+    "classes": 0,
+    "avg_complexity": 1.8
+  },
+  "quality_score": 100,
+  "grade": "A",
+  "smells": [
+    {
+      "type": "long_function",
+      "severity": "medium",
+      "message": "Function 'safe_input' has 60 lines (max: 50)",
+      "location": "safe_input"
+    },
+    {
+      "type": "magic_number",
+      "severity": "low",
+      "message": "Magic number 100 should be a named constant",
+      "location": "line 29"
+    },
+    {
+      "type": "magic_number",
+      "severity": "low",
+      "message": "Magic number 100 should be a named constant",
+      "location": "line 68"
+    }
+  ],
+  "solid_violations": [],
+  "function_details": [
+    {
+      "name": "safe_input",
+      "parameters": 1,
+      "lines": 60,
+      "complexity": 3
+    },
+    {
+      "name": "checked_alloc",
+      "parameters": 1,
+      "lines": 30,
+      "complexity": 2
+    },
+    {
+      "name": "run_safe_cmd",
+      "parameters": 1,
+      "lines": 14,
+      "complexity": 1
+    },
+    {
+      "name": "main",
+      "parameters": 2,
+      "lines": 8,
+      "complexity": 1
+    }
+  ],
+  "class_details": [],
+  "policy": {
+    "tiers": [
+      "built-in",
+      "review-policy.json"
+    ],
+    "thresholds": {
+      "long_function_lines": 50,
+      "too_many_parameters": 5,
+      "high_complexity": 10,
+      "god_class_methods": 20,
+      "max_imports": 15,
+      "max_declarative_depth": 8
+    }
+  }
+}