bmad-module-skill-forge 0.9.0 → 0.10.1-alpha.0

package/src/skf-analyze-source/assets/skill-brief-schema.md

@@ -0,0 +1,125 @@
+# Skill Brief Schema
+
+## Purpose
+
+Defines the output contract for skill-brief.yaml files generated by analyze-source. Each generated brief must conform to this schema to be consumable by brief-skill and create-skill downstream workflows.
+
+## Required Fields
+
+| Field       | Type   | Constraint                                       | Description                                                                 |
+|-------------|--------|--------------------------------------------------|-----------------------------------------------------------------------------|
+| name        | string | kebab-case `[a-z0-9-]+`                          | Unique skill identifier                                                     |
+| version     | string | Semantic version (`X.Y.Z` or `X.Y.Z-prerelease`) | Auto-detect from source (see Version Detection below), fall back to `1.0.0`. **Side effect on remote sources:** `skf-create-skill` treats `version` as an **implicit** `target_version` hint when `target_version` itself is absent — it will try to resolve `{version}` or `v{version}` to a git tag before cloning and fall back to HEAD with a warning if no tag matches. See `skf-create-skill/references/source-resolution-protocols.md` → "Implicit Tag Resolution". |
+| source_repo | string | GitHub URL or local path                         | Repository or project root (optional when `source_type: "docs-only"`)       |
+| language    | string | Recognized language                              | Primary programming language                                                |
+| scope       | object | See Scope Object below                           | Boundary definition                                                         |
+| description | string | 1-3 sentences                                    | What the skill covers                                                       |
+| forge_tier  | string | `Quick` / `Forge` / `Forge+` / `Deep`            | Inherited from forge-tier.yaml (Title Case)                                 |
+| created     | string | ISO date `YYYY-MM-DD`                            | Generation date                                                             |
+| created_by  | string | user_name from config                            | Who generated the brief                                                     |
+
+## Optional Fields
+
+| Field              | Type   | Constraint                                       | Description                                                                                                                                                                                                                    |
+|--------------------|--------|--------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| source_type        | string | `source` or `docs-only`                          | Default `source`. When `docs-only`: `source_repo` optional, `doc_urls` required                                                                                                                                                |
+| doc_urls           | array  | `{url, label}` objects                           | Documentation URLs for T3 content. Required when `source_type: "docs-only"`                                                                                                                                                    |
+| `scripts_intent`   | string | `detect` / `none` / free-text                    | Describes whether scripts should be extracted. Values: `detect` (auto-detect from source — default when absent), `none` (skip scripts), or a free-text description of expected scripts (e.g., "CLI validation tools in bin/"). |
+| `assets_intent`    | string | `detect` / `none` / free-text                    | Describes whether assets should be extracted. Values: `detect` (auto-detect from source — default when absent), `none` (skip assets), or a free-text description of expected assets (e.g., "JSON schemas in schemas/").        |
+| `target_version`   | string | Semantic version (`X.Y.Z` or `X.Y.Z-prerelease`) | User-specified target version. When present, overrides auto-detection and becomes the skill's version. Recommended for docs-only skills where auto-detection is unavailable.                                                   |
+| `source_authority` | string | `official` / `community` / `internal`            | Default `community`. Set to `official` only when the skill creator is the library maintainer. Forced to `community` when `source_type: "docs-only"`.                                                                           |
+| `source_ref`       | string | Git ref (tag/branch/HEAD)                        | Resolved git ref used for source access. Set automatically during tag resolution — do not set manually.                                                                                                                        |
+
+When `source_type: "docs-only"`:
+- `source_repo` becomes optional (set to doc site URL for reference)
+- `doc_urls` must have at least one entry
+- `source_authority` is forced to `community` (T3 external documentation cannot be `official`)
+- All extracted content gets `[EXT:{url}]` citations
+
+## Version Detection
+
+During brief generation, attempt to auto-detect the source version before defaulting to `"1.0.0"`. Check the first matching file in the source:
+
+- **Python:** `pyproject.toml` `[project] version` (static) → if `dynamic = ["version"]`, check `__init__.py` for `__version__` → `_version.py` if exists → `setup.py` `version=` → `git describe --tags --abbrev=0`
+- **JavaScript/TypeScript:** root `package.json` (`"version"`) → if root has `"private": true` with a `"workspaces"` array or lacks a `"version"` field, fall back to a primary workspace package's `package.json` (e.g., `code/core/package.json`, or the first matching `packages/*/package.json`). For GitHub sources, prefer `gh api repos/{owner}/{repo}/releases/latest` → `tag_name` when a non-pre-release tag exists, over a default-branch pre-release. Treat a version containing `-alpha`, `-beta`, `-rc`, `-next`, or `-canary` as a pre-release.
+- **Rust:** `Cargo.toml` `[package] version` (static) → if `version = { workspace = true }`, resolve from workspace root `Cargo.toml` → `git describe --tags --abbrev=0`
+- **Go:** version tag from `go.mod` or `git describe --tags --abbrev=0`
+
+If the source is a remote GitHub repo, use `gh api repos/{owner}/{repo}/contents/{file}` to read the version file. If the source is local, read the file directly.
+
+If detection succeeds, use the detected version. If it fails or returns a non-semver value, fall back to `"1.0.0"`.
+
+The create-skill workflow (step-03-extract) also performs version reconciliation at extraction time — if the source version has changed since the brief was created, the extraction step warns and uses the source version.
+
+**Target version override:** When `target_version` is present in the brief, it takes precedence over auto-detection. Auto-detection still runs for informational purposes (displayed as "Detected version" alongside the user-specified "Target version"), but the `target_version` value is used as the brief's `version` field. This is particularly useful for docs-only skills (where no package manifest exists) and when the user wants to compile a skill for a specific older version.
+
+**Pre-release handling:** If the detected version contains a pre-release tag (e.g., `1.0.0-beta.0`, `2.0.0-rc.1`), preserve it as-is. Pre-release tags are valid semver and must not be stripped. When comparing versions during reconciliation, use semver-aware comparison that respects pre-release ordering.
+
+## Scope Object
+
+```yaml
+scope:
+  type: full-library | specific-modules | public-api | component-library | docs-only
+  include:
+    - 'src/**/*.ts'          # At least one required
+  exclude:
+    - 'src/**/*.test.ts'     # Optional
+  notes: 'Optional rationale for scope decision'
+  # Additional fields when scope.type is "component-library":
+  # registry_path: "path/to/registry.ts"  # Optional — auto-detected if omitted
+  # ui_variants:                           # Optional — design system variants
+  #   - name: "shadcnui"
+  #     package: "packages/components/react-shadcn"
+  # demo_patterns:                         # Optional — auto-detected if omitted
+  #   - "**/demo/**"
+  #   - "**/*.stories.*"
+```
+
+### Scope Types
+
+| Type              | Use When                                                                             |
+|-------------------|--------------------------------------------------------------------------------------|
+| full-library      | Entire codebase of a unit                                                            |
+| specific-modules  | Selected components or packages                                                      |
+| public-api        | Only exported interfaces                                                             |
+| component-library | UI component libraries with registries, props-based APIs, and design system variants |
+| docs-only         | When source_type is docs-only — no source code available, all content from doc_urls  |
+
+## YAML Template
+
+```yaml
+name: '{unit-name}'
+version: '{detected-version or 1.0.0}'
+source_type: 'source'
+source_repo: '{project_path}'
+language: '{detected_language}'
+scope:
+  type: '{detected_scope_type}'
+  include:
+    - '{include_pattern}'
+  exclude:
+    - '{exclude_pattern}'
+  notes: '{scope_rationale}'
+description: '{1-3 sentence description}'
+forge_tier: '{Quick|Forge|Forge+|Deep}'
+created: '{current_date}'
+created_by: '{user_name}'
+```
+
+## Validation Rules
+
+1. **Name uniqueness**: No duplicate names within forge_data_folder
+2. **Source accessibility**: source_repo path must exist or be reachable
+3. **Language recognized**: Must be a known programming language
+4. **Scope type valid**: Must match one of the five defined types (full-library, specific-modules, public-api, component-library, docs-only)
+5. **Include patterns**: At least one include glob pattern required (exception: `docs-only` scope, where include patterns are optional since no source code is available)
+6. **Forge tier match**: Must match value in forge-tier.yaml
+7. **Docs-only mode**: When `source_type: "docs-only"`, `doc_urls` required (>= 1), `source_repo` optional
+8. Each `doc_urls` entry must have a valid `url` field
+
+## Output Location
+
+Each skill-brief.yaml is written to:
+```
+{forge_data_folder}/{unit-name}/skill-brief.yaml
+```

package/src/skf-analyze-source/references/unit-detection-heuristics.md

@@ -0,0 +1,124 @@
+# Unit Detection Heuristics
+
+## Purpose
+
+Rules for identifying discrete skillable units within a project. A "skillable unit" is a self-contained component with clear boundaries that can be documented as an independent skill.
+
+## Detection Signals
+
+### Strong Signals (High Confidence)
+
+| Signal                                         | Description                                  | Example                            |
+|------------------------------------------------|----------------------------------------------|------------------------------------|
+| Independent package.json / Cargo.toml / go.mod | Unit has its own dependency manifest         | `packages/auth/package.json`       |
+| Separate entry point                           | Unit has a main/index file                   | `services/api/src/index.ts`        |
+| Docker/service definition                      | Unit runs as an independent service          | `docker-compose.yml` service entry |
+| Distinct export surface                        | Unit exports a public API consumed by others | `src/lib/index.ts` with re-exports |
+| Workspace member                               | Listed in root workspace configuration       | `pnpm-workspace.yaml` packages     |
+
+### Moderate Signals (Medium Confidence)
+
+| Signal                   | Description                                       | Example                             |
+|--------------------------|---------------------------------------------------|-------------------------------------|
+| Directory depth boundary | Top-level directory with self-contained structure | `src/modules/payments/`             |
+| Naming convention        | Follows organizational naming pattern             | `@org/package-name`                 |
+| Separate test suite      | Has its own test directory or config              | `packages/auth/__tests__/`          |
+| README.md presence       | Has documentation at directory level              | `libs/utils/README.md`              |
+| CI/CD pipeline reference | Referenced in build/deploy configuration          | `.github/workflows/deploy-auth.yml` |
+
+### Weak Signals (Low Confidence — Require Corroboration)
+
+| Signal             | Description                                 | Example                       |
+|--------------------|---------------------------------------------|-------------------------------|
+| Large directory    | Many files in a subtree                     | 50+ files under one directory |
+| Comment boundaries | Code comments marking sections              | `// --- Auth Module ---`      |
+| Import clustering  | Files that import primarily from each other | Tight import graph cluster    |
+
+## Boundary Classification
+
+### Service Boundary
+- Independent deployable unit
+- Own process, port, or container
+- Clear network interface (REST, gRPC, message queue)
+- Scope type: `full-library`
+
+### Package Boundary
+- Workspace member or independently versioned package
+- Own dependency manifest
+- Exports consumed by other packages
+- Scope type: `full-library` or `specific-modules`
+
+### Module Boundary
+- Logical grouping within a single package
+- Shared namespace or directory structure
+- Internal cohesion, external coupling through defined interface
+- Scope type: `specific-modules` or `public-api`
+
+### Library Boundary
+- Third-party dependency with significant project-specific usage patterns
+- Custom wrappers, configurations, or integration code
+- Scope type: `public-api`
+
+### Component Library Boundary
+- Contains a component registry or catalog file (array of component definitions with IDs, names, categories)
+- Has `components/`, `packages/components/`, or similar multi-component directory structure
+- Multiple design system variant directories (e.g., `react-shadcn/`, `react-baseui/`, `react-carbon/`)
+- Significant demo/story/example file ratio (>30% of total files)
+- CLI-based installation pattern (e.g., `npx <tool> add <component-id>`)
+- Props interfaces outnumber function signatures as primary API surface
+- Scope type: `component-library`
+
+## Disqualification Rules
+
+Do NOT recommend as a skillable unit if:
+
+1. **Too small**: Fewer than 3 source files or 100 lines of code
+2. **Generated code**: Auto-generated files (protobuf, GraphQL codegen, etc.)
+3. **Pure configuration**: Only config files with no logic
+4. **Test-only**: Test utilities with no production code
+5. **Vendor/dependency**: Third-party code copied into project
+6. **Already skilled**: Existing skill found in forge_data_folder (recommend update-skill instead)
+
+## Script/Asset Detection Signals
+
+During per-unit analysis, check for scripts and assets alongside code exports.
+
+**Script signals:**
+
+| Strength | Signal                                                                                        | Example                                             |
+|----------|-----------------------------------------------------------------------------------------------|-----------------------------------------------------|
+| Strong   | Entry point in `package.json` `bin`, Cargo.toml `[[bin]]`, pyproject.toml `[project.scripts]` | `"bin": { "migrate": "scripts/migrate.js" }`        |
+| Strong   | Shebang + executable file                                                                     | `#!/usr/bin/env python` in `scripts/setup.py`       |
+| Moderate | File in `scripts/`, `bin/`, `tools/`, `cli/` directory                                        | `scripts/validate.sh`                               |
+| Moderate | CI/CD reference to script                                                                     | `.github/workflows/test.yml` runs `scripts/test.sh` |
+
+**Asset signals:**
+
+| Strength | Signal                                                                         | Example                          |
+|----------|--------------------------------------------------------------------------------|----------------------------------|
+| Strong   | JSON Schema file with `$schema` key                                            | `schemas/config.schema.json`     |
+| Strong   | Config template with `.example` or `.template` extension                       | `config.yaml.example`            |
+| Moderate | File in `assets/`, `templates/`, `schemas/`, `configs/`, `examples/` directory | `templates/report.hbs`           |
+| Moderate | OpenAPI/GraphQL definition                                                     | `openapi.json`, `schema.graphql` |
+
+**Per-unit output:** Record `has_scripts: boolean`, `has_assets: boolean`, `script_files: string[]`, `asset_files: string[]`.
+
+**Disqualify:** Generated files (dist/, build/), vendored dependencies, IDE configs (.vscode/, .idea/), binary files (.so, .dll, .jar).
+
+## Stack Skill Candidate Detection
+
+Flag units as stack skill candidates when:
+
+1. **Co-import frequency**: Two or more units are imported together in 3+ files
+2. **Integration adapter**: A unit exists primarily to bridge two other units
+3. **Shared state**: Multiple units read/write to the same data store
+4. **Orchestration layer**: A unit coordinates calls across multiple other units
+
+## Tier-Aware Scanning Depth
+
+| Forge Tier | Scanning Approach                                                                                  |
+|------------|----------------------------------------------------------------------------------------------------|
+| Quick      | File structure analysis: directory trees, manifest files, entry points, naming conventions         |
+| Forge      | AST analysis: export surfaces, import graphs, dependency trees, type hierarchies                   |
+| Forge+     | AST + CCC: semantic file pre-ranking before structural analysis, CCC signals for relevance scoring |
+| Deep       | AST + QMD: temporal evolution, refactoring patterns, semantic relationships, architectural drift   |

package/src/{workflows/analyze-source → skf-analyze-source}/steps-c/step-01-init.md

@@ -1,11 +1,8 @@
 ---
-name: 'step-01-init'
-description: 'Initialize analysis workflow — load config, detect continuation, accept project path, check existing skills, create report'
-
 nextStepFile: './step-02-scan-project.md'
 continueFile: './step-01b-continue.md'
 outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
-templateFile: '../templates/analysis-report-template.md'
+templateFile: 'templates/analysis-report-template.md'
 ---
 
 # Step 1: Initialize Analysis
@@ -14,44 +11,11 @@ templateFile: '../templates/analysis-report-template.md'
 
 To initialize the analyze-source workflow by loading configuration, detecting continuation state, accepting the target project path, checking for existing skills, and creating the analysis report document.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-### Universal Rules:
-
-- 🛑 NEVER generate content without user input
-- 📖 CRITICAL: Read the complete step file before taking any action
-- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
-- 📋 YOU ARE A FACILITATOR, not a content generator
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
-- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
-
-### Role Reinforcement:
-
-- ✅ You are a source code analyst and decomposition architect (Ferris Architect mode)
-- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
-- ✅ Prescriptive precision — zero-hallucination, only report what is found
-- ✅ File:line citation tracing for all claims
-
-### Step-Specific Rules:
-
-- 🎯 Focus only on initialization — do NOT begin scanning or analysis
-- 🚫 FORBIDDEN to analyze source code in this step
-- 💬 Collect project path and scope hints from user
-- 📋 Verify prerequisites before proceeding
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Follow the MANDATORY SEQUENCE exactly
-- 💾 Create output document from template when initialization complete
-- 📖 Update output frontmatter with initialization data
-- 🚫 FORBIDDEN to proceed without valid project path and forge-tier.yaml
+## Rules
 
-## CONTEXT BOUNDARIES:
-
-- Available: SKF module config (loaded by workflow.md), forge_data_folder, skills_output_folder, forge_tier
-- Focus: Setup and validation only — no analysis
-- Limits: Do not read source files beyond checking prerequisites
-- Dependencies: setup-forge must have been run (forge-tier.yaml must exist)
+- Focus only on initialization — do not begin scanning or analysis
+- Collect project path and scope hints from user
+- Verify prerequisites before proceeding
 
 ## MANDATORY SEQUENCE
 
@@ -73,7 +37,7 @@ Look for {outputFile}.
 
 **Check forge-tier.yaml:**
 - Look for `{sidecar_path}/forge-tier.yaml`
-- **IF missing:** HARD HALT — "**Cannot proceed.** forge-tier.yaml not found at `{sidecar_path}/forge-tier.yaml`. Please run the setup-forge workflow first to configure your forge tier (Quick/Forge/Forge+/Deep)."
+- **IF missing:** HARD HALT — "**Cannot proceed.** forge-tier.yaml not found at `{sidecar_path}/forge-tier.yaml`. Please run the setup workflow first to configure your forge tier (Quick/Forge/Forge+/Deep)."
 - **IF found:** Read and note the forge tier value
 
 **Apply tier override:** Read `{sidecar_path}/preferences.yaml`. If `tier_override` is set and is a valid tier value (Quick, Forge, Forge+, or Deep), use it instead of the detected tier.
@@ -175,27 +139,3 @@ Display: "**Proceeding to project scan...**"
 
 ONLY WHEN the output report has been created with populated frontmatter (project_paths, forge_tier, existing_skills) will you load and read fully {nextStepFile} to execute and begin the project scan.
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- Continuation detection performed correctly
-- forge-tier.yaml verified present and tier noted
-- Valid project path collected from user
-- Optional scope hints collected
-- Existing skills scanned and documented
-- Analysis report created from template with populated frontmatter
-- Auto-proceeded to step 02
-
-### ❌ SYSTEM FAILURE:
-
-- Skipping forge-tier.yaml check
-- Accepting an invalid project path
-- Not checking for existing skills
-- Not creating the output report before proceeding
-- Beginning source analysis in this step
-- Hardcoded paths instead of using frontmatter variables
-
-**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/{workflows/analyze-source → skf-analyze-source}/steps-c/step-01b-continue.md

@@ -1,7 +1,4 @@
 ---
-name: 'step-01b-continue'
-description: 'Handle workflow continuation from previous session'
-
 outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
 nextStepOptions:
   step-02: './step-02-scan-project.md'
@@ -17,42 +14,11 @@ nextStepOptions:
 
 To resume the analyze-source workflow from where it was left off in a previous session by reading the analysis report's progress state and routing to the correct next step.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-### Universal Rules:
-
-- 🛑 NEVER generate content without user input
-- 📖 CRITICAL: Read the complete step file before taking any action
-- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
-- 📋 YOU ARE A FACILITATOR, not a content generator
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
-- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
-
-### Role Reinforcement:
-
-- ✅ You are a source code analyst and decomposition architect (Ferris Architect mode)
-- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
-- ✅ Prescriptive precision — resume exactly where we left off
-
-### Step-Specific Rules:
-
-- 🎯 Focus only on reading state and routing — do NOT perform any analysis
-- 🚫 FORBIDDEN to re-run completed steps
-- 💬 Present progress summary to user before resuming
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Follow the MANDATORY SEQUENCE exactly
-- 💾 Update lastContinued in output frontmatter
-- 📖 Route to the correct next step based on stepsCompleted
-- 🚫 FORBIDDEN to skip the progress summary
+## Rules
 
-## CONTEXT BOUNDARIES:
-
-- Available: Existing analysis report with stepsCompleted array
-- Focus: State detection and routing only
-- Limits: Do not modify any existing report content
-- Dependencies: Output file must exist with valid stepsCompleted
+- Focus only on reading state and routing — do not perform any analysis
+- Do not re-run completed steps
+- Present progress summary to user before resuming
 
 ## MANDATORY SEQUENCE
 
@@ -121,24 +87,3 @@ lastContinued: '{current_date}'
 
 ONLY WHEN the progress state has been read, summarized to the user, and lastContinued updated will you load the appropriate next step file to resume the workflow.
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- Analysis report loaded and progress state read
-- Progress summary presented to user
-- Correct next step identified from stepsCompleted
-- lastContinued updated in frontmatter
-- Routed to correct step file
-
-### ❌ SYSTEM FAILURE:
-
-- Not reading stepsCompleted from report
-- Skipping progress summary
-- Routing to wrong step
-- Re-running already completed steps
-- Not updating lastContinued
-
-**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/{workflows/analyze-source → skf-analyze-source}/steps-c/step-02-scan-project.md

@@ -1,10 +1,7 @@
 ---
-name: 'step-02-scan-project'
-description: 'Map project structure, detect service boundaries, and identify package manifests'
-
 nextStepFile: './step-03-identify-units.md'
 outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
-heuristicsFile: '../data/unit-detection-heuristics.md'
+heuristicsFile: 'references/unit-detection-heuristics.md'
 ---
 
 # Step 2: Scan Project
@@ -13,46 +10,12 @@ heuristicsFile: '../data/unit-detection-heuristics.md'
 
 To map the complete project structure by scanning directory trees, detecting service boundaries, identifying package manifests, and cataloging entry points — building the foundation that subsequent steps use for unit identification.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-### Universal Rules:
-
-- 🛑 NEVER generate content without user input
-- 📖 CRITICAL: Read the complete step file before taking any action
-- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
-- 📋 YOU ARE A FACILITATOR, not a content generator
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
-- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
-
-### Role Reinforcement:
-
-- ✅ You are a source code analyst and decomposition architect (Ferris Architect mode)
-- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
-- ✅ Prescriptive precision — zero-hallucination, only report what is found
-- ✅ File:line citation tracing for all claims
-
-### Step-Specific Rules:
-
-- 🎯 Focus only on structural scanning — do NOT classify units or map exports yet
-- 🚫 FORBIDDEN to read source file contents beyond manifest files and entry points
-- 💬 Use subprocess optimization (Pattern 1) for scanning across many files
-- 📋 Tier-aware scanning depth: Quick (file structure only), Forge (+ manifest parsing), Deep (+ config analysis)
-
-**AST Degradation Fallback:** If the AST tool (ast-grep) is unavailable at Forge or Deep tier, degrade to Quick-tier behavior for this step and emit a warning: "AST tool unavailable — falling back to file-structure scanning for this step."
-
-## EXECUTION PROTOCOLS:
+## Rules
 
-- 🎯 Follow the MANDATORY SEQUENCE exactly
-- 💾 Append "## Project Scan" section to {outputFile}
-- 📖 Update stepsCompleted in {outputFile} frontmatter
-- 🚫 FORBIDDEN to proceed without presenting scan results to user
-
-## CONTEXT BOUNDARIES:
-
-- Available: project_path, forge_tier, scope_hints, existing_skills from report frontmatter
-- Focus: Project structure mapping only — directory tree, manifests, entry points, service configs
-- Limits: Do not analyze exports, imports, or integration points (that's steps 03-04)
-- Dependencies: step-01-init must have created the report with valid project_path
+- Focus only on structural scanning — do not classify units or map exports yet
+- Do not read source file contents beyond manifest files and entry points
+- Use subprocess Pattern 1 for scanning across many files
+- Tier-aware scanning depth: Quick (file structure), Forge (+ manifest parsing), Deep (+ config analysis)
 
 ## MANDATORY SEQUENCE
 
@@ -183,34 +146,10 @@ Display: "**Select:** [C] Continue to Unit Identification"
 #### EXECUTION RULES:
 
 - ALWAYS halt and wait for user input after presenting menu
+- **GATE [default: C]** — If `{headless_mode}`: auto-proceed with [C] Continue, log: "headless: auto-continue past scan results"
 - ONLY proceed to next step when user selects 'C'
 
 ## CRITICAL STEP COMPLETION NOTE
 
 ONLY WHEN the Project Scan section has been appended to {outputFile} with complete boundary, manifest, and entry point catalogs, and frontmatter stepsCompleted has been updated, will you load and read fully {nextStepFile} to begin unit identification.
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- Complete directory structure mapped
-- All package manifests found and cataloged
-- Entry points identified
-- Service boundaries detected with confidence levels
-- Scope hints applied correctly
-- Results presented to user for confirmation
-- Report updated with Project Scan section
-- stepsCompleted updated in frontmatter
-
-### ❌ SYSTEM FAILURE:
-
-- Incomplete directory scan (missing subdirectories)
-- Not detecting workspace configuration files
-- Reading source file contents (only manifests/configs allowed)
-- Not presenting results for user confirmation
-- Classifying units in this step (that's step 03)
-- Hardcoded paths instead of using frontmatter variables
-
-**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/{workflows/analyze-source → skf-analyze-source}/steps-c/step-03-identify-units.md

@@ -1,10 +1,7 @@
 ---
-name: 'step-03-identify-units'
-description: 'Classify discrete skillable units from scan results using detection heuristics and assign scope types'
-
 nextStepFile: './step-04-map-and-detect.md'
 outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
-heuristicsFile: '../data/unit-detection-heuristics.md'
+heuristicsFile: 'references/unit-detection-heuristics.md'
 ---
 
 # Step 3: Identify Units
@@ -13,44 +10,11 @@ heuristicsFile: '../data/unit-detection-heuristics.md'
 
 To classify each detected boundary from the project scan into discrete skillable units by applying detection heuristics, assigning boundary types and scope types, and filtering out disqualified candidates.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-### Universal Rules:
-
-- 🛑 NEVER generate content without user input
-- 📖 CRITICAL: Read the complete step file before taking any action
-- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
-- 📋 YOU ARE A FACILITATOR, not a content generator
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
-- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
-
-### Role Reinforcement:
-
-- ✅ You are a source code analyst and decomposition architect (Ferris Architect mode)
-- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
-- ✅ Prescriptive precision — zero-hallucination, only report what is found
-- ✅ File:line citation tracing — cite detection signals with specific file paths
-
-### Step-Specific Rules:
-
-- 🎯 Focus only on unit classification — do NOT map exports or integration points yet
-- 🚫 FORBIDDEN to generate skill-brief.yaml in this step
-- 💬 Apply heuristics systematically to each detected boundary
-- 📋 Every classification must cite the detection signals that justify it
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Follow the MANDATORY SEQUENCE exactly
-- 💾 Append "## Identified Units" section to {outputFile}
-- 📖 Update stepsCompleted in {outputFile} frontmatter
-- 🚫 FORBIDDEN to proceed without presenting classifications to user
+## Rules
 
-## CONTEXT BOUNDARIES:
-
-- Available: Project Scan section from report (boundaries, manifests, entry points, configs)
-- Focus: Classification of boundaries into skillable units with scope types
-- Limits: Do not analyze file contents beyond what's needed for classification
-- Dependencies: step-02-scan-project must have populated the Project Scan section
+- Focus only on unit classification — do not map exports or integration points yet
+- Do not generate skill-brief.yaml in this step
+- Every classification must cite the detection signals that justify it
 
 ## MANDATORY SEQUENCE
 
@@ -166,34 +130,10 @@ Display: "**Select:** [C] Continue to Export Mapping and Integration Detection"
 #### EXECUTION RULES:
 
 - ALWAYS halt and wait for user input after presenting menu
+- **GATE [default: C]** — If `{headless_mode}`: accept all classifications and auto-proceed, log: "headless: auto-accept unit classifications"
 - ONLY proceed to next step when user selects 'C'
 
 ## CRITICAL STEP COMPLETION NOTE
 
 ONLY WHEN the Identified Units section has been appended to {outputFile} with complete classification tables, disqualification records, and language detection results, and frontmatter stepsCompleted has been updated, will you load and read fully {nextStepFile} to begin export mapping and integration detection.
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- Every detected boundary evaluated against heuristics
-- Detection signals cited with specific file paths
-- Scope types assigned to each qualifying unit
-- Disqualification rules applied and documented
-- Existing skills cross-referenced
-- Primary language detected per unit
-- Classifications presented to user for confirmation
-- Report updated with Identified Units section
-
-### ❌ SYSTEM FAILURE:
-
-- Classifying without citing detection signals
-- Missing disqualification checks
-- Not cross-referencing existing_skills
-- Mapping exports or integrations in this step (that's step 04)
-- Generating skill-brief.yaml in this step (that's step 06)
-- Not presenting classifications for user confirmation
-
-**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.