bmad-module-skill-forge 1.3.0 → 1.4.0

package/.claude-plugin/marketplace.json

@@ -30,7 +30,7 @@
       "name": "skill-forge",
       "source": "./",
       "description": "Evidence-based agent skills compiler with progressive capability tiers (Quick/Forge/Forge+/Deep).",
-      "version": "1.3.0",
+      "version": "1.4.0",
       "author": {
         "name": "Armel"
       },

package/docs/_data/pinned.yaml

@@ -26,7 +26,7 @@
 # Enforced two ways: (1) release.yaml bumps this line in the same commit
 # as package.json + marketplace.json on every release; (2) validate-docs-drift.js
 # cross-checks this value against package.json.version and fails on mismatch.
-skf_version: "1.3.0"
+skf_version: "1.4.0"
 
 # Path to the oh-my-skills repo, resolved relative to this repo's root.
 # Override at runtime with the OMS environment variable if oh-my-skills

package/docs/workflows.md

@@ -286,15 +286,15 @@ flowchart TD
 
 ## Workflow Categories
 
-| Category | Workflows | Description |
-|----------|-----------|-------------|
-| Core | SF, BS, CS, US | Setup, brief, create, and update skills |
-| Feature | QS, SS, AN | Quick skill, stack skill, and analyze source |
-| Quality | AS, TS | Detect skill drift (AS) and verify skill completeness (TS) |
-| Architecture Verification | VS, RA | Pre-code architecture feasibility and refinement |
-| Management | RS, DS | Rename and drop skill versions with transactional safety |
-| Utility | EX | Package and export for consumption |
-| In-Agent | WS, KI | WS: show lifecycle position, active briefs, and forge tier; KI: list knowledge fragments (both in-agent, no file-based workflow) |
+| Category                  | Workflows      | Description                                                                                                                      |
+| ------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| Core                      | SF, BS, CS, US | Setup, brief, create, and update skills                                                                                          |
+| Feature                   | QS, SS, AN     | Quick skill, stack skill, and analyze source                                                                                     |
+| Quality                   | AS, TS         | Detect skill drift (AS) and verify skill completeness (TS)                                                                       |
+| Architecture Verification | VS, RA         | Pre-code architecture feasibility and refinement                                                                                 |
+| Management                | RS, DS         | Rename and drop skill versions with transactional safety                                                                         |
+| Utility                   | EX             | Package and export for consumption                                                                                               |
+| In-Agent                  | WS, KI         | WS: show lifecycle position, active briefs, and forge tier; KI: list knowledge fragments (both in-agent, no file-based workflow) |
 
 ---
 
@@ -313,12 +313,12 @@ Instead of running one workflow per session, you can chain multiple workflows in
 
 ### Pipeline Aliases
 
-| Alias | Expands To | First Workflow | Required Target |
-|-------|-----------|----------------|-----------------|
-| `forge` | `BS CS TS EX` | BS | GitHub URL or local path **+** skill name |
-| `forge-quick` | `QS TS EX` | QS | GitHub URL **or** package name |
-| `onboard` | `AN CS TS EX` | AN | Project path (defaults to current directory) |
-| `maintain` | `AS US TS EX` | AS | Existing skill name |
+| Alias         | Expands To    | First Workflow | Required Target                              |
+| ------------- | ------------- | -------------- | -------------------------------------------- |
+| `forge`       | `BS CS TS EX` | BS             | GitHub URL or local path **+** skill name    |
+| `forge-quick` | `QS TS EX`    | QS             | GitHub URL **or** package name               |
+| `onboard`     | `AN CS TS EX` | AN             | Project path (defaults to current directory) |
+| `maintain`    | `AS US TS EX` | AS             | Existing skill name                          |
 
 **The first workflow's input contract defines what arguments the pipeline needs.** A bare package name works for `forge-quick` (QS resolves packages via the registry) but **not** for `forge` — BS requires both an unambiguous target (URL or path) and a skill name.
 
@@ -390,6 +390,25 @@ Parent skills and CI pipelines `grep` one line out of the workflow log to learn
 
 **Batch mode (`--batch <file>`).** Drives N targets through the full pipeline (steps 1–7 each) in sequence. Input format: one target per line, `#` comments and blank lines ignored, optional per-line modifiers `language=<lang>` and `scope=<path>`. Per-target output lands in `{skill_package}/` as today; an aggregated summary writes to `{skills_output_folder}/_batch/quick-skill-batch-{ts}.json` (with `quick-skill-batch-latest.json` copy). Per-target boundary events (`{"batch":N,"target":"…","status":"start|done|fail",…}`) and a final `{"batch_summary":true,…}` event extend the per-step event stream above. Full input grammar, summary schema, and exit-code semantics in [`src/skf-quick-skill/SKILL.md`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-quick-skill/SKILL.md) § "Batch Mode".
 
+**Exception — `/skf-brief-skill` headless emits a final result envelope and supports presets.** Headless `/skf-brief-skill` is a first-class building block for scripted brief generation (e.g. seeding briefs for N SaaS SDKs that share scope/authority defaults). Three operational contracts beyond per-gate auto-proceed:
+
+1. **Pre-supplied inputs replace prompts.** Headless args are consumed at step-01's GATE in place of the interactive menus: `target_repo`, `skill_name`, `target_version`, `language`, `source_type`, `source_authority`, `doc_urls`, `scope_type`, `scripts_intent`, `force`, `preset`. Required-arg shape depends on `source_type` (`target_repo` + `skill_name` for source-backed; `doc_urls` + `skill_name` for `docs-only`). Absent `source_authority` and `scope_type` are NOT guessed — they're resolved by signal-driven detection (`gh api user` vs. repo owner for authority; the 5-rule heuristic ladder for scope). Full grammar in [`src/skf-brief-skill/references/headless-args.md`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-brief-skill/references/headless-args.md).
+
+2. **Structured exit-code map.** Every HARD HALT exits with a stable code so pipelines branch on the failure class without grepping message text:
+
+   | Code | Meaning                       |
+   | ---- | ----------------------------- |
+   | 0    | success                       |
+   | 2    | input-missing / input-invalid |
+   | 3    | resolution-failure            |
+   | 4    | write-failure                 |
+   | 5    | overwrite-cancelled           |
+   | 6    | user-cancelled                |
+
+3. **Final result envelope on every terminal exit.** Step-05 emits a single-line `SKF_BRIEF_RESULT_JSON: {…}` envelope on **stdout** before chaining to step-06 on success; every HARD HALT emits the same envelope shape on **stderr** with `status: "error"` and a typed `halt_reason` (`input-missing`, `input-invalid`, `forge-tier-missing`, `target-inaccessible`, `gh-auth-failed`, `write-failed`, `overwrite-cancelled`, `user-cancelled`). Full envelope schema and population rules in [`src/skf-brief-skill/SKILL.md`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-brief-skill/SKILL.md) § "Result Contract (Headless)".
+
+**Presets (`--preset <name>`).** Loads `{sidecar_path}/brief-presets/{name}.yaml` and merges its keys as defaults at step-01 §8; explicit headless args override preset values. The preset file is YAML containing any subset of the headless args above; unknown fields are ignored with a warning. Useful for repeated patterns — e.g. briefing 5 SaaS SDKs that all share `source_authority=community`, `scope_type=full-library`, `scripts_intent=skip`.
+
 ---
 
 ## Terminal Step: Health Check

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-module-skill-forge",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "BMAD module — Turn code and docs into instructions AI agents can actually follow. Progressive capability tiers (Quick/Forge/Forge+/Deep).",
   "keywords": [
     "bmad",
@@ -53,7 +53,7 @@
     "test:cli": "node test/test-cli-integration.js",
     "test:install": "node test/test-installation-components.js",
     "test:knowledge": "node test/test-knowledge-base.js",
-    "test:python": "uv run --with pytest --with pyyaml pytest test/test-compute-score-contract.py test/test-skf-preflight.py test/test-skf-skill-inventory.py test/test-skf-validate-output.py test/test-skf-validate-frontmatter.py test/test-skf-manifest-ops.py test/test-skf-rebuild-managed-sections.py test/test-skf-severity-classify.py test/test-skf-structural-diff.py test/test-skf-detect-tools.py test/test-skf-forge-tier-rw.py test/test-skf-emit-result-envelope.py test/test-skf-qmd-classify-collections.py test/test-skf-merge-ccc-exclusions.py test/test-skf-resolve-package.py test/test-skf-extract-public-api.py test/test-skf-render-quick-metadata.py -v",
+    "test:python": "uv run --with pytest --with pyyaml pytest test/test-compute-score-contract.py test/test-skf-preflight.py test/test-skf-skill-inventory.py test/test-skf-validate-output.py test/test-skf-validate-frontmatter.py test/test-skf-manifest-ops.py test/test-skf-rebuild-managed-sections.py test/test-skf-severity-classify.py test/test-skf-structural-diff.py test/test-skf-detect-tools.py test/test-skf-forge-tier-rw.py test/test-skf-emit-result-envelope.py test/test-skf-qmd-classify-collections.py test/test-skf-merge-ccc-exclusions.py test/test-skf-resolve-package.py test/test-skf-extract-public-api.py test/test-skf-render-quick-metadata.py test/test-skf-validate-brief-inputs.py test/test-skf-emit-brief-result-envelope.py test/test-skf-write-skill-brief.py test/test-skf-detect-workspaces.py test/test-skf-recommend-scope-type.py test/test-skf-detect-language.py -v",
     "test:schemas": "node test/test-agent-schema.js",
     "test:workflow": "node test/test-workflow-state.js",
     "validate:refs": "node tools/validate-file-refs.js --strict",

package/src/shared/scripts/schemas/skf-brief-result-envelope.v1.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/armelhbobdad/bmad-module-skill-forge/src/shared/scripts/schemas/skf-brief-result-envelope.v1.json",
+  "title": "SKF_BRIEF_RESULT_JSON envelope (v1)",
+  "description": "Single-line JSON document emitted by skf-brief-skill step-05 §4b when {headless_mode} is true, prefixed with the literal 'SKF_BRIEF_RESULT_JSON: '. Pipelines grep one line out of the workflow log to branch on the brief outcome without parsing prose. Schema mirrors the contract in src/skf-brief-skill/SKILL.md Result Contract section.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["status", "brief_path", "skill_name", "version", "language", "scope_type", "exit_code", "halt_reason"],
+  "properties": {
+    "status": {
+      "type": "string",
+      "enum": ["success", "error"],
+      "description": "'success' on the terminal happy path (after step-05 wrote the brief and step-06 returned). 'error' on any HARD HALT."
+    },
+    "brief_path": {
+      "type": ["string", "null"],
+      "description": "Absolute path to the written skill-brief.yaml on success. Null when the run errored before any file was written (or when overwrite-cancelled aborted before write)."
+    },
+    "skill_name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Brief's skill_name field — present in every envelope (success and error) since it is captured at step-01 §6 before any of the other failure branches."
+    },
+    "version": {
+      "type": ["string", "null"],
+      "description": "Resolved brief version (target_version if set, else auto-detected, else '1.0.0'). Null when the run errored before step-05's version-resolution ran."
+    },
+    "language": {
+      "type": ["string", "null"],
+      "description": "Detected or user-confirmed primary language. Null when the run errored before step-02's language-detection ran."
+    },
+    "scope_type": {
+      "type": ["string", "null"],
+      "enum": ["full-library", "specific-modules", "public-api", "component-library", "reference-app", "docs-only", null],
+      "description": "Confirmed scope.type from step-03. Null when the run errored before scope was confirmed."
+    },
+    "exit_code": {
+      "type": "integer",
+      "enum": [0, 2, 3, 4, 5, 6],
+      "description": "Process exit code matching the SKILL.md Exit Codes table. Derived deterministically from halt_reason: null→0, input-missing/input-invalid→2, forge-tier-missing/target-inaccessible/gh-auth-failed→3, write-failed→4, overwrite-cancelled→5, user-cancelled→6."
+    },
+    "halt_reason": {
+      "type": ["string", "null"],
+      "enum": [
+        null,
+        "input-missing",
+        "input-invalid",
+        "forge-tier-missing",
+        "target-inaccessible",
+        "gh-auth-failed",
+        "write-failed",
+        "overwrite-cancelled",
+        "user-cancelled"
+      ],
+      "description": "Null on success. One of the documented HALT classes on error. Pipelines branch on this to surface the right operator message without grepping the prose error."
+    }
+  }
+}

package/src/shared/scripts/schemas/skill-brief.v1.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/armelhbobdad/bmad-module-skill-forge/src/shared/scripts/schemas/skill-brief.v1.json",
+  "title": "skill-brief.yaml (v1)",
+  "description": "Canonical schema for the skill-brief.yaml artifact written by skf-brief-skill step-05 and consumed by skf-create-skill, skf-update-skill, skf-audit-skill. Mirrors src/skf-brief-skill/assets/skill-brief-schema.md.",
+  "type": "object",
+  "required": ["name", "version", "source_repo", "language", "description", "forge_tier", "created", "created_by", "scope"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$",
+      "description": "Unique skill identifier (kebab-case)."
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^v?\\d+\\.\\d+\\.\\d+([.\\-+][0-9A-Za-z][0-9A-Za-z.\\-+]*)?$",
+      "description": "Resolved semver. target_version wins; else auto-detected; else 1.0.0."
+    },
+    "target_version": {
+      "type": "string",
+      "pattern": "^v?\\d+\\.\\d+\\.\\d+([.\\-+][0-9A-Za-z][0-9A-Za-z.\\-+]*)?$",
+      "description": "User-specified target. When present, MUST equal version."
+    },
+    "source_type": {
+      "type": "string",
+      "enum": ["source", "docs-only"]
+    },
+    "source_repo": {
+      "type": "string",
+      "minLength": 1,
+      "description": "GitHub URL or local path. Required even for docs-only (set to doc site URL)."
+    },
+    "source_authority": {
+      "type": "string",
+      "enum": ["official", "community", "internal"]
+    },
+    "doc_urls": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["url"],
+        "properties": {
+          "url": { "type": "string", "minLength": 1 },
+          "label": { "type": "string" }
+        }
+      },
+      "minItems": 1,
+      "description": "Required when source_type is docs-only; allowed as supplemental for source."
+    },
+    "language": { "type": "string", "minLength": 1 },
+    "description": { "type": "string", "minLength": 1 },
+    "forge_tier": {
+      "type": "string",
+      "enum": ["Quick", "Forge", "Forge+", "Deep"]
+    },
+    "created": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
+    },
+    "created_by": { "type": "string", "minLength": 1 },
+    "scripts_intent": { "type": "string", "minLength": 1 },
+    "assets_intent": { "type": "string", "minLength": 1 },
+    "scope": {
+      "type": "object",
+      "required": ["type", "include", "exclude", "notes"],
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["full-library", "specific-modules", "public-api", "component-library", "reference-app", "docs-only"]
+        },
+        "include": { "type": "array", "items": { "type": "string" } },
+        "exclude": { "type": "array", "items": { "type": "string" } },
+        "notes": { "type": "string" }
+      }
+    }
+  }
+}

package/src/shared/scripts/schemas/workspace-detection.v1.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://armelhbobdad.github.io/bmad-module-skill-forge/schemas/workspace-detection.v1.json",
+  "title": "Workspace Detection Result (v1)",
+  "description": "Result envelope returned by skf-detect-workspaces.py. Reports whether the inspected target is a monorepo, which manifest kind drives it, and the list of resolved workspaces.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["is_monorepo", "manifest_kind", "workspaces", "warnings"],
+  "properties": {
+    "is_monorepo": {
+      "type": "boolean",
+      "description": "True if any detector matched at least one workspace."
+    },
+    "manifest_kind": {
+      "description": "Which detector produced the result. null when is_monorepo is false.",
+      "oneOf": [
+        {
+          "type": "string",
+          "enum": ["npm-workspaces", "pnpm-workspaces", "lerna", "cargo-workspace", "python-multi-package", "generic-folders"]
+        },
+        { "type": "null" }
+      ]
+    },
+    "workspaces": {
+      "type": "array",
+      "description": "Resolved workspaces. Empty when is_monorepo is false. Each entry has a name, a repository-relative path, and the path to its recognised manifest.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "path", "manifest"],
+        "properties": {
+          "name": { "type": "string", "minLength": 1 },
+          "path": { "type": "string", "minLength": 1 },
+          "manifest": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "warnings": {
+      "type": "array",
+      "description": "Non-fatal parse warnings encountered during detection (e.g. malformed manifests that the detector skipped).",
+      "items": { "type": "string" }
+    }
+  }
+}

package/src/shared/scripts/skf-detect-language.py

@@ -0,0 +1,277 @@
+# /// script
+# requires-python = ">=3.9"
+# dependencies = []
+# ///
+"""SKF Detect Language — deterministic primary-language detection from a flat file tree.
+
+Single source of truth for the language-detection rule table that
+skf-brief-skill step-02 §3 applies. The rule walk is purely deterministic:
+manifest-file presence first (Cargo.toml → rust, package.json → js/ts,
+etc.), then extension-frequency fallback. Moving it into a shared script
+saves ~150-250 tokens per workflow invocation and removes a quiet drift
+seam — the JS-vs-TS disambiguation in particular benefits from being
+co-located with a deterministic rule rather than restated in prose.
+
+Detection rules (apply in order, first match wins):
+
+  1. package.json (with optional tsconfig.json companion):
+       tsconfig.json present → typescript (high)
+       tsconfig.json absent  → javascript (high)
+  2. Cargo.toml          → rust (high)
+  3. pyproject.toml | setup.py | setup.cfg → python (high)
+  4. go.mod              → go (high)
+  5. pom.xml             → java (high)
+  6. build.gradle.kts    → kotlin (high)
+  7. build.gradle (Groovy) — check tree:
+       src/main/kotlin/  → kotlin (medium)
+       else              → java (medium)
+  8. *.csproj | *.sln    → csharp (high)
+  9. Gemfile             → ruby (high)
+ 10. Extension-frequency fallback over the full tree.
+       dominant extension >= 50% of code files → that language (medium)
+       no clear winner                        → unknown (low)
+
+CLI:
+  echo '{"tree": ["path1", "path2", ...]}' | uv run skf-detect-language.py
+  uv run skf-detect-language.py --json '{"tree": [...]}'
+
+Input (JSON object on stdin or via --json):
+  tree — list of repo-relative file paths (required, non-empty)
+
+Output (JSON on stdout):
+  language          — javascript | typescript | rust | python | go
+                       | java | kotlin | csharp | ruby | swift | php
+                       | unknown
+  confidence        — "high" | "medium" | "low"
+  detection_source  — human-readable string naming what fired (manifest
+                       basename, extension share, etc.)
+  fallback_to_extension_frequency — bool (true when rule 10 fired)
+
+Exit codes:
+  0 — recommendation produced (even when language is "unknown")
+  2 — internal error (bad JSON input, IO failure)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections import Counter
+from typing import Any
+
+# Manifest basenames the rule table checks. Kept tight — tree-wide pattern
+# matches (e.g. *.csproj) are handled separately to avoid false positives
+# from generated artifacts under build/ or dist/.
+_MANIFEST_RULES: list[tuple[str, str, str]] = [
+    # (basename, language, detection_source)
+    ("Cargo.toml", "rust", "Cargo.toml present"),
+    ("pyproject.toml", "python", "pyproject.toml present"),
+    ("setup.py", "python", "setup.py present"),
+    ("setup.cfg", "python", "setup.cfg present"),
+    ("go.mod", "go", "go.mod present"),
+    ("pom.xml", "java", "pom.xml present"),
+    ("build.gradle.kts", "kotlin", "build.gradle.kts present"),
+    ("Gemfile", "ruby", "Gemfile present"),
+]
+
+# Glob-style suffix rules — matches anywhere in the tree. csproj/sln are
+# C#-specific. Ordered so the first hit wins.
+_SUFFIX_RULES: list[tuple[str, str, str]] = [
+    (".csproj", "csharp", ".csproj project file present"),
+    (".sln", "csharp", ".sln solution file present"),
+]
+
+# Extension → language for the frequency fallback. Tightly limited to source
+# extensions; keeping this small avoids the fallback being skewed by
+# auto-generated assets (.json, .md, .yaml, etc.).
+_EXTENSION_TO_LANGUAGE: dict[str, str] = {
+    ".py": "python",
+    ".js": "javascript",
+    ".jsx": "javascript",
+    ".mjs": "javascript",
+    ".cjs": "javascript",
+    ".ts": "typescript",
+    ".tsx": "typescript",
+    ".rs": "rust",
+    ".go": "go",
+    ".java": "java",
+    ".kt": "kotlin",
+    ".kts": "kotlin",
+    ".cs": "csharp",
+    ".rb": "ruby",
+    ".swift": "swift",
+    ".php": "php",
+}
+
+_DOMINANCE_THRESHOLD = 0.50
+
+
+def _die(message: str, code: int = 2) -> None:
+    sys.stderr.write(f"skf-detect-language: {message}\n")
+    sys.exit(code)
+
+
+def _basename(path: str) -> str:
+    return path.rsplit("/", 1)[-1]
+
+
+def _has_basename(tree: list[str], basename: str) -> bool:
+    return any(_basename(p) == basename for p in tree)
+
+
+def _has_suffix(tree: list[str], suffix: str) -> bool:
+    return any(p.endswith(suffix) for p in tree)
+
+
+def _has_path_segment(tree: list[str], segment: str) -> bool:
+    """True when any path contains the given segment (e.g. 'src/main/kotlin/')."""
+    return any(segment in p for p in tree)
+
+
+def _extension(path: str) -> str:
+    """Return the lowercased file extension including the leading dot, or empty string."""
+    base = _basename(path)
+    if "." not in base or base.startswith("."):
+        return ""
+    return "." + base.rsplit(".", 1)[-1].lower()
+
+
+def _frequency_fallback(tree: list[str]) -> dict[str, Any]:
+    """Score the tree by source-extension frequency. Returns the result envelope."""
+    counter: Counter[str] = Counter()
+    for path in tree:
+        ext = _extension(path)
+        if ext in _EXTENSION_TO_LANGUAGE:
+            counter[ext] += 1
+
+    total = sum(counter.values())
+    if total == 0:
+        return {
+            "language": "unknown",
+            "confidence": "low",
+            "detection_source": "no recognized source extensions in tree",
+            "fallback_to_extension_frequency": True,
+        }
+
+    # Largest-share extension wins. Ties (e.g. equal counts) broken by
+    # the natural order of _EXTENSION_TO_LANGUAGE — Counter.most_common
+    # is stable for equal counts and we don't rely on which loses.
+    top_ext, top_count = counter.most_common(1)[0]
+    share = top_count / total
+    language = _EXTENSION_TO_LANGUAGE[top_ext]
+
+    if share >= _DOMINANCE_THRESHOLD:
+        confidence = "medium"
+        source = f"extension frequency: {top_ext} is {top_count}/{total} of source files ({share:.0%})"
+    else:
+        confidence = "low"
+        source = f"no dominant extension: top is {top_ext} at {top_count}/{total} ({share:.0%}, threshold {int(_DOMINANCE_THRESHOLD * 100)}%)"
+        # Still surface the best-guess language; caller / step-03 §4 lets
+        # the user override on low confidence.
+    return {
+        "language": language,
+        "confidence": confidence,
+        "detection_source": source,
+        "fallback_to_extension_frequency": True,
+    }
+
+
+def detect(payload: dict[str, Any]) -> dict[str, Any]:
+    """Apply the documented rule walk. Always returns a recommendation."""
+    tree = payload.get("tree")
+    if not isinstance(tree, list):
+        _die("payload.tree must be an array of repo-relative file paths")
+    if len(tree) == 0:
+        _die("payload.tree must be non-empty")
+
+    # Rule 1 — package.json (with tsconfig.json disambiguation)
+    if _has_basename(tree, "package.json"):
+        if _has_basename(tree, "tsconfig.json"):
+            return {
+                "language": "typescript",
+                "confidence": "high",
+                "detection_source": "package.json + tsconfig.json present",
+                "fallback_to_extension_frequency": False,
+            }
+        return {
+            "language": "javascript",
+            "confidence": "high",
+            "detection_source": "package.json present (no tsconfig.json)",
+            "fallback_to_extension_frequency": False,
+        }
+
+    # Rules 2-6 — single-basename manifests walked in priority order. Note
+    # that build.gradle (Groovy DSL) is NOT in this table; it requires
+    # tree-aware Java/Kotlin disambiguation handled in Rule 7b below.
+    # build.gradle.kts IS in the table (returns kotlin high) and fires
+    # here before the Groovy variant is considered.
+    for basename, language, source in _MANIFEST_RULES:
+        if _has_basename(tree, basename):
+            return {
+                "language": language,
+                "confidence": "high",
+                "detection_source": source,
+                "fallback_to_extension_frequency": False,
+            }
+
+    # Rule 7b — build.gradle (Groovy DSL): check src/main/kotlin/ to disambiguate.
+    # This rule sits *after* the basename loop because build.gradle.kts is
+    # already covered by the loop and we don't want it to pre-empt that match.
+    if _has_basename(tree, "build.gradle"):
+        if _has_path_segment(tree, "src/main/kotlin/"):
+            return {
+                "language": "kotlin",
+                "confidence": "medium",
+                "detection_source": "build.gradle (Groovy) + src/main/kotlin/ present",
+                "fallback_to_extension_frequency": False,
+            }
+        return {
+            "language": "java",
+            "confidence": "medium",
+            "detection_source": "build.gradle (Groovy) present without src/main/kotlin/ — defaulting to java",
+            "fallback_to_extension_frequency": False,
+        }
+
+    # Rules 8-9 — suffix-based (csproj, sln)
+    for suffix, language, source in _SUFFIX_RULES:
+        if _has_suffix(tree, suffix):
+            return {
+                "language": language,
+                "confidence": "high",
+                "detection_source": source,
+                "fallback_to_extension_frequency": False,
+            }
+
+    # Rule 10 — extension-frequency fallback
+    return _frequency_fallback(tree)
+
+
+def _parse_argv(argv: list[str]) -> dict:
+    parser = argparse.ArgumentParser(
+        description="Detect primary language from a flat repo file tree by walking the documented rule table.",
+    )
+    parser.add_argument("--json", help="JSON payload (alternative to stdin)")
+    args = parser.parse_args(argv)
+    raw = args.json if args.json is not None else sys.stdin.read()
+    if not raw or not raw.strip():
+        _die("empty input (expected JSON payload on stdin or via --json)")
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError as e:
+        _die(f"invalid JSON input: {e}")
+    if not isinstance(payload, dict):
+        _die("payload must be a JSON object")
+    return payload
+
+
+def main(argv: list[str]) -> int:
+    payload = _parse_argv(argv)
+    result = detect(payload)
+    json.dump(result, sys.stdout, ensure_ascii=False)
+    sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))