bmad-module-skill-forge 1.9.0 → 2.0.1

package/src/skf-verify-stack/scripts/skf-verdict-rollup.py

@@ -0,0 +1,258 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.10"
+# dependencies = []
+# ///
+"""Deterministic overall-feasibility verdict rollup for skf-verify-stack (synthesize.md §1).
+
+Deciding each individual finding — is this integration Blocked, is that technology
+Missing, is a requirement Not Addressed — is judgment and happens upstream in
+Steps 02-04, persisted to the report frontmatter/tables. Rolling those already-decided
+counts up into the single overall verdict is *not* judgment: it is a fixed threshold
+ladder with one correct answer per input. Walking a five-tier ordered ladder (with a
+short-circuit, a downgrade rule, and a post-verdict guard) in-prompt lets the headline
+verdict drift between runs, so the token computation lives here. The rationale prose —
+which co-occurring problems to name, how to phrase the recommendation — stays in the
+prompt; this script emits only the token plus the stable condition codes the prompt
+cites when it writes that rationale.
+
+The ladder (exactly mirrors synthesize.md §1; evaluate top-to-bottom, first match wins):
+
+  1. Zero-coverage short-circuit  — coveragePercentage == 0  -> NOT_FEASIBLE
+     (no live coverage: analysis is vacuous; the remainder of the ladder is skipped).
+  2. NOT_FEASIBLE                  — any integration Blocked (pairsBlocked > 0).
+  3. CONDITIONALLY_FEASIBLE        — ANY of: a Missing technology (missingCount > 0),
+     a Risky integration (pairsRisky > 0), or — only when the requirements pass ran —
+     a Not Addressed or Partially Fulfilled requirement.
+  4. FEASIBLE                      — none of the above AND zero pairs capped at
+     Plausible (pairsPlausible == 0). If any pair sits at Plausible, downgrade to
+     CONDITIONALLY_FEASIBLE.
+
+  Post-verdict zero-integration-pairs guard (applied after ANY verdict): when all four
+  integration counts are 0 AND the user continued past a step-2 zero-state [C] gate,
+  the guard fires — a FEASIBLE verdict is overridden to CONDITIONALLY_FEASIBLE, and
+  regardless of verdict the prompt appends the "no integration claims found" note.
+
+Note that coveragePercentage and missingCount are independent inputs on purpose: half-up
+rounding means a stack with covered=199, missing=1 rounds to coveragePercentage == 100
+while missingCount is still > 0, so the Missing trigger reads missingCount directly.
+
+CLI usage:
+  uv run skf-verdict-rollup.py '<JSON>'                  # JSON literal positional
+  uv run skf-verdict-rollup.py --json-input '<JSON>'     # explicit flag form
+  cat input.json | uv run skf-verdict-rollup.py --stdin  # piped input
+
+Input schema (one object; counts come straight from the report frontmatter/tables):
+  {
+    "coveragePercentage": <int 0..100>,      # from coverage.md (coverage-tally)
+    "missingCount": <int>,                   # Missing technologies (Replaced excluded)
+    "pairsBlocked": <int>,                   # from integrations.md
+    "pairsRisky": <int>,
+    "pairsPlausible": <int>,                 # includes Check-4-missing caps
+    "pairsVerified": <int>,
+    "requirementsEvaluated": <bool>,         # optional (default false): requirementsPass == "completed"
+    "requirementsNotAddressed": <int>,       # optional (default 0); ignored unless evaluated
+    "requirementsPartial": <int>,            # optional (default 0); ignored unless evaluated
+    "continuedPastZeroState": <bool>         # optional (default false): user pressed [C] past a step-2 zero-state gate
+  }
+
+Output (stdout, one object):
+  {
+    "overallVerdict": "FEASIBLE" | "CONDITIONALLY_FEASIBLE" | "NOT_FEASIBLE",
+    "matchedConditions": [<condition codes, in ladder order>],
+    "zeroPairsGuardFired": <bool>
+  }
+
+Condition codes (stable; the prompt cites these when synthesizing the rationale):
+  zero-coverage · blocked-integration · missing-coverage · risky-integration ·
+  requirements-not-addressed · requirements-partial · plausible-cap · zero-integration-pairs
+
+Exit codes:
+  0  — verdict emitted successfully
+  1  — no input / input could not be parsed as JSON
+  2  — input parsed but schema/semantics invalid (error object emitted as JSON)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+VERDICTS = ("FEASIBLE", "CONDITIONALLY_FEASIBLE", "NOT_FEASIBLE")
+REQUIRED_COUNTS = (
+    "missingCount",
+    "pairsBlocked",
+    "pairsRisky",
+    "pairsPlausible",
+    "pairsVerified",
+)
+OPTIONAL_COUNTS = ("requirementsNotAddressed", "requirementsPartial")
+
+
+def make_error(message):
+    return {"error": message, "code": "INVALID_INPUT"}
+
+
+def _is_nonneg_int(value):
+    # bool is a subclass of int; reject it so a stray true/false can't pose as a count.
+    return isinstance(value, int) and not isinstance(value, bool) and value >= 0
+
+
+def _validate(inp):
+    if inp is None or not isinstance(inp, dict):
+        return "Input must be a JSON object"
+
+    pct = inp.get("coveragePercentage")
+    if not isinstance(pct, int) or isinstance(pct, bool) or not (0 <= pct <= 100):
+        return "coveragePercentage must be an integer in 0..100"
+
+    for field in REQUIRED_COUNTS:
+        if field not in inp:
+            return f"missing required field: {field}"
+        if not _is_nonneg_int(inp[field]):
+            return f"{field} must be a non-negative integer"
+
+    for field in OPTIONAL_COUNTS:
+        if field in inp and inp[field] is not None and not _is_nonneg_int(inp[field]):
+            return f"{field} must be a non-negative integer when present"
+
+    for field in ("requirementsEvaluated", "continuedPastZeroState"):
+        if field in inp and not isinstance(inp[field], bool):
+            return f"{field} must be a boolean when present"
+
+    return None
+
+
+def rollup(inp):
+    """Pure verdict rollup over the persisted counts. See module docstring for the ladder."""
+    err = _validate(inp)
+    if err:
+        return make_error(err)
+
+    pct = inp["coveragePercentage"]
+    missing = inp["missingCount"]
+    blocked = inp["pairsBlocked"]
+    risky = inp["pairsRisky"]
+    plausible = inp["pairsPlausible"]
+    verified = inp["pairsVerified"]
+    req_eval = bool(inp.get("requirementsEvaluated", False))
+    not_addressed = inp.get("requirementsNotAddressed") or 0
+    partial = inp.get("requirementsPartial") or 0
+    continued = bool(inp.get("continuedPastZeroState", False))
+
+    matched: list[str] = []
+
+    # 1. Zero-coverage short-circuit — wins over everything else.
+    if pct == 0:
+        verdict = "NOT_FEASIBLE"
+        matched.append("zero-coverage")
+    # 2. Any Blocked integration is a fundamental incompatibility.
+    elif blocked > 0:
+        verdict = "NOT_FEASIBLE"
+        matched.append("blocked-integration")
+        # Co-occurring problems the rationale should also name (§1).
+        if missing > 0:
+            matched.append("missing-coverage")
+        if risky > 0:
+            matched.append("risky-integration")
+    else:
+        # 3. Any gap / risk / unmet requirement -> conditional.
+        conditional: list[str] = []
+        if missing > 0:
+            conditional.append("missing-coverage")
+        if risky > 0:
+            conditional.append("risky-integration")
+        if req_eval and not_addressed > 0:
+            conditional.append("requirements-not-addressed")
+        if req_eval and partial > 0:
+            conditional.append("requirements-partial")
+        if conditional:
+            verdict = "CONDITIONALLY_FEASIBLE"
+            matched.extend(conditional)
+        elif plausible > 0:
+            # 4. Clean bar except for Check-4-missing caps -> downgrade.
+            verdict = "CONDITIONALLY_FEASIBLE"
+            matched.append("plausible-cap")
+        else:
+            verdict = "FEASIBLE"
+
+    # Post-verdict zero-integration-pairs guard.
+    zero_pairs = blocked == 0 and risky == 0 and plausible == 0 and verified == 0
+    guard_fired = zero_pairs and continued
+    if guard_fired:
+        if verdict == "FEASIBLE":
+            verdict = "CONDITIONALLY_FEASIBLE"
+        matched.append("zero-integration-pairs")
+
+    return {
+        "overallVerdict": verdict,
+        "matchedConditions": matched,
+        "zeroPairsGuardFired": guard_fired,
+    }
+
+
+# --- CLI --------------------------------------------------------------------
+
+
+def _build_parser():
+    parser = argparse.ArgumentParser(
+        prog="skf-verdict-rollup",
+        description=(
+            "Deterministic overall-feasibility verdict rollup (synthesize.md §1). "
+            "Consumes the persisted coverage / integration / requirements counts and "
+            "emits the FEASIBLE / CONDITIONALLY_FEASIBLE / NOT_FEASIBLE token plus the "
+            "condition codes the prompt cites in its rationale."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "Example:\n"
+            "  uv run skf-verdict-rollup.py "
+            "'{\"coveragePercentage\":100,\"missingCount\":0,\"pairsBlocked\":0,"
+            "\"pairsRisky\":0,\"pairsPlausible\":0,\"pairsVerified\":3}'"
+        ),
+    )
+    src = parser.add_mutually_exclusive_group()
+    src.add_argument("json_input", nargs="?", help="JSON object as a positional argument.")
+    src.add_argument("--json-input", dest="json_input_flag", help="JSON object passed via flag.")
+    src.add_argument("--stdin", action="store_true", help="Read the JSON object from stdin.")
+    return parser
+
+
+def _resolve_input(args):
+    if args.stdin:
+        return sys.stdin.read()
+    if args.json_input_flag is not None:
+        return args.json_input_flag
+    if args.json_input is not None:
+        return args.json_input
+    return ""
+
+
+def main(argv=None):
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    raw = _resolve_input(args)
+    if not raw.strip():
+        parser.print_usage(file=sys.stderr)
+        print(
+            "error: no input provided (positional arg, --json-input, or --stdin)",
+            file=sys.stderr,
+        )
+        return 1
+
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        print(json.dumps(make_error(f"Invalid JSON: {exc.msg}"), indent=2))
+        return 1
+
+    result = rollup(data)
+    print(json.dumps(result, indent=2))
+    if isinstance(result, dict) and result.get("code") == "INVALID_INPUT":
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/tools/cli/lib/ui.js

@@ -356,8 +356,9 @@ class UI {
         `${chalk.white.bold('Get Started')}`,
         `1. Open this folder in ${ideDisplay}`,
         `2. Activate Ferris:  ${activateLine}`,
-        '3. Ferris (your Skill Architect) will guide you through',
-        '   setting up and forging your first agent skill',
+        '3. Ferris (your Skill Architect) guides you through forge setup',
+        `4. Fastest first skill — ask Ferris to run ${brand.gold('forge-auto <repo-or-doc-url>')}:`,
+        '   one command auto-scopes, compiles, tests, and exports a verified skill',
       ].join('\n');
     }
 

package/docs/deepwiki.md

@@ -1,89 +0,0 @@
----
-title: deepwiki
-description: Zero-ceremony wiki-skill creation — one command turns a GitHub repo, doc URL, or pinned version into a verified wiki skill
----
-
-deepwiki is a [pipeline alias](../workflows/#pipeline-aliases) that chains five workflows into a single command. Give it a repo URL, a documentation URL, or a pinned version, and it produces a verified wiki skill in 3–5 minutes with zero configuration.
-
-If you're new to SKF and want to try it without reading anything else, start here.
-
----
-
-## Invocation
-
-Three input types, one command pattern:
-
-```
-@Ferris deepwiki https://github.com/honojs/hono                  — repo URL
-@Ferris deepwiki https://docs.example.com                         — doc URL (docs-only)
-@Ferris deepwiki https://github.com/honojs/hono --pin v4.6.0      — pinned version
-```
-
-- **Repo URL** — analyzes the full source repository, extracts exports, and compiles a wiki skill from code + docs.
-- **Doc URL** — skips source analysis entirely and builds the skill from documentation alone. Useful for closed-source libraries or when the docs are the canonical reference.
-- **`--pin <version>`** — targets a specific release. The version tag is resolved during analysis so the resulting skill is locked to that exact API surface.
-
----
-
-## Pipeline Stages
-
-deepwiki expands to `AN[auto] BS[auto] CS TS[min:90] EX`. Each stage runs in [headless mode](../workflows/#headless-mode) — no confirmation gates, no interactive prompts.
-
-| Stage | Workflow | Mode | What Happens |
-|-------|----------|------|-------------|
-| 1 | **Analyze Source** (AN) | `[auto]` | Scans the target, detects shape (library/framework/tool/app), discovers exports, and generates a scope + brief automatically. |
-| 2 | **Brief Skill** (BS) | `[auto]` | Enriches the auto-generated brief with doc detection results. No interactive scoping — the brief is assembled from AN's output. |
-| 3 | **Create Skill** (CS) | standard | Compiles the skill from the enriched brief. Extracts exports, resolves documentation sources, validates structure. |
-| 4 | **Test Skill** (TS) | `[min:90]` | Verifies completeness with a **90% quality threshold** (stricter than the default 80%). Fail halts the pipeline. |
-| 5 | **Export Skill** (EX) | standard | Validates the package, generates context snippets, and injects into your IDE's context file. |
-
-Data flows automatically between stages — the brief path from AN feeds BS, the skill name from CS feeds TS, and so on. See [Pipeline Mode](../workflows/#pipeline-mode) for the general mechanics.
-
----
-
-## Automatic Behaviors
-
-deepwiki's `[auto]` flags activate several behaviors that normally require manual input:
-
-- **Auto-scope** — shape detection (library, framework, tool, application) drives scope decisions. No interactive scope confirmation.
-- **Auto-brief** — the brief is generated and enriched with doc-detection results in one pass, without the interactive discovery flow that `BS` uses standalone.
-- **Coexistence detection** — if a skill for the same target already exists, deepwiki detects it and offers three options: create alongside (new version), merge into the existing skill, or skip.
-- **Auto-decomposition** — for massive repos (>500 exports or >3 packages), AN automatically decomposes into multiple analysis units before proceeding.
-
----
-
-## Expected Output
-
-A successful deepwiki run produces a complete skill package in your forge data directory, exported and ready for use. The skill includes:
-
-- `SKILL.md` — the compiled wiki skill with provenance-cited instructions
-- `metadata.json` — version, source, confidence tier breakdown
-- Context snippet injected into your IDE context file (CLAUDE.md, .cursorrules, AGENTS.md, etc.)
-
-The quality threshold is 90% — if the skill scores below that, the pipeline halts at TS with a gap report. Run `@Ferris US` to address gaps, then `@Ferris TS EX` to re-test and export.
-
----
-
-## Timing
-
-A typical library (50–200 exports) takes **3–5 minutes** end to end. Factors that increase time:
-
-- Massive repos (>500 exports) trigger auto-decomposition, adding 1–3 minutes
-- Doc-only targets depend on documentation site size and structure
-- Deep-tier projects (with QMD and CCC) spend more time on enrichment
-
----
-
-## Migration from onboard
-
-deepwiki replaces the older `onboard` alias. `onboard` still works but shows a deprecation notice on every invocation and will be removed in v2.0.
-
-The key difference: `onboard` runs `AN CS TS EX` with standard (interactive) modes. deepwiki adds auto-scope, auto-brief, a stricter quality gate (90% vs 80%), and accepts repo URLs and doc URLs — not just project paths.
-
----
-
-## Related
-
-- [Workflows](../workflows/) — pipeline mode mechanics, headless mode, circuit breakers
-- [Concepts](../concepts/) — provenance, confidence tiers, drift, version pinning
-- [BMAD Synergy](../bmad-synergy/) — how deepwiki fits into BMAD phases, and standalone SKF usage

package/src/skf-rename-skill/references/rebuild-context.md

@@ -1,110 +0,0 @@
----
-# Static reference loaded by execute.md §7. The carve removes ~70
-# lines of context-rebuild loop logic from the main execute.md so
-# the §1–§6 + §8–§10 critical-path stays tight; §7 itself is always
-# reached on the success path so this file loads on every successful
-# rename, but the rollback paths (§4–§6 failure jumps) skip §7
-# entirely and never load this reference.
----
-
-<!-- Config: communicate in {communication_language}. Render the rebuilt-files report in {document_output_language}. -->
-
-# Rename: Rebuild Context Files (per-IDE managed-section sweep)
-
-## Purpose
-
-After §6 re-keys the manifest from `{old_name}` to `{new_name}`, every IDE's context file (`CLAUDE.md`, `.cursorrules`, `AGENTS.md`, etc.) still contains the old name in its managed-section snippet rows. This step rewrites each one in-place via the surgical between-marker swap so the on-disk managed sections reflect the new name.
-
-Loaded by `execute.md` §7 once `manifest_updated == true` (§6 succeeded) and the rollback paths in §4–§6 were not taken.
-
-## Resolve target_context_files
-
-Load the `ides` list from `config.yaml`. The installer writes IDE identifiers — these must be mapped to context files and skill roots using the "IDE → Context File Mapping" table in `{managedSectionLogic}`:
-
-1. For each entry in `config.yaml.ides`, look up its `context_file` and `skill_root` from the mapping table.
-2. For any entry not found in the table, default to AGENTS.md / `.agents/skills/` and emit a warning: `Unknown IDE '{value}' in config.yaml — defaulting to AGENTS.md`.
-3. Deduplicate by `context_file` — when multiple IDEs map to the same context file, use the first configured IDE's `skill_root`.
-4. If `config.yaml.ides` is absent or the mapping yields an empty list, fall back to `[{context_file: "AGENTS.md", skill_root: ".agents/skills/"}]` and emit a note: `No IDEs configured in config.yaml — defaulting to AGENTS.md`.
-
-Store the result as `target_context_files`.
-
-## Per-file loop
-
-For each entry in `target_context_files`:
-
-### 1. Resolve target file
-
-Resolve the absolute path at `{context_file}`.
-
-### 2. Read the current file
-
-- If the file does not exist, skip this context file (nothing to rebuild — the file will be re-created the next time export-skill runs).
-- If the file exists but contains no `<!-- SKF:BEGIN -->` marker, skip this context file (no managed section to rewrite).
-- If the file contains `<!-- SKF:BEGIN -->` but no matching `<!-- SKF:END -->`, record the error against that context file and continue to the next entry — do not halt the entire rename on a malformed context file.
-
-### 3. Build the exported skill set (version-aware, deprecated-excluded)
-
-Use the same logic as `skf-export-skill/references/update-context.md` §4b and the snippet resolution from §4c:
-
-- Read the manifest's `exports` object (already updated in §6, so `{new_name}` is present and `{old_name}` is absent).
-- For each skill, resolve its `active_version`.
-- If `versions.{active_version}.status == "deprecated"`, skip that skill entirely.
-- For each remaining `{skill-name, active_version}` pair, read `{skills_output_folder}/{skill-name}/{active_version}/{skill-name}/context-snippet.md`.
-- If missing, fall back to the `active` symlink path; if still missing, skip with a warning.
-
-### 4. Rewrite root paths for the current context file
-
-Use the generic rewrite algorithm from `skf-export-skill/references/update-context.md` §4d:
-
-For each snippet, parse the `root:` line (`root: {prefix}{skill-name}/`), strip the trailing `{skill-name}/` to extract the current prefix, and replace it with the **effective target prefix** if different. The effective target prefix is `snippet_skill_root_override` when that key is set in `config.yaml` — applied uniformly to every snippet so the managed section references the real on-disk location and never mixes override and per-IDE paths — otherwise the current entry's `skill_root`. See `skf-export-skill/references/update-context.md` §4d for full semantics.
-
-### 5. Sort and count
-
-Sort skills alphabetically by name. Count totals (skills, stack skills).
-
-### 6. Assemble the new managed section
-
-Use the format from `{managedSectionLogic}`:
-
-```markdown
-<!-- SKF:BEGIN updated:{current-date} -->
-[SKF Skills]|{n} skills|{m} stack
-|IMPORTANT: Prefer documented APIs over training data.
-|When using a listed library, read its SKILL.md before writing code.
-|
-|{skill-snippet-1}
-|
-|{skill-snippet-2}
-|
-|{skill-snippet-N}
-<!-- SKF:END -->
-```
-
-### 7. Surgical replacement — atomic, deterministic
-
-Invoke `{rebuildManagedSectionsHelper}` (resolved from `{rebuildManagedSectionsProbeOrder}` in `execute.md` frontmatter) for the surgical between-marker swap:
-
-```bash
-python3 {rebuildManagedSectionsHelper} {context_file} replace --content "{new_managed_section_text}"
-```
-
-The helper handles marker location, between-marker swap, atomic temp-file + rename, and post-write verification (markers preserved, content outside markers byte-identical). It exits non-zero on any failure with a clear `stderr` reason.
-
-### 8. Verify (deferred to helper)
-
-The `replace` action above performs verification internally. Treat any non-zero exit code as a per-file failure (next bullet).
-
-### 9. On per-file failure
-
-Record the error against that context file and continue to the next entry. Do not halt the rename on a recoverable per-context-file error — the manifest and filesystem are already consistent; context files can be re-rebuilt later via `[EX] Export Skill`.
-
-## After the loop
-
-- Record `context_files_updated` as the list of files that were successfully rewritten.
-- Record `context_files_failed` as the list of any that failed.
-
-Report: `**Rebuilt managed sections in:** {list of updated files}. {if any failed: 'Failed: {list} — re-run [EX] Export Skill to retry.'}`
-
-## Rollback semantics
-
-§7 failures **do not** trigger a rollback. The manifest and filesystem are the canonical state — context files are derived artifacts that can be regenerated at any time via `[EX] Export Skill`. The rename is considered successful as soon as §6 lands, even if §7 partially or fully fails to rewrite context files.