ai-factory 2.13.1 → 2.13.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-factory",
-  "version": "2.13.1",
+  "version": "2.13.2",
   "type": "module",
   "description": "CLI tool for automating AI agent context setup in projects",
   "main": "dist/cli/index.js",

package/skills/aif-distillation/SKILL.md

@@ -5,7 +5,7 @@ description: >-
   Use when source material should become either one reusable skill package or a
   split set of focused skills, each with a concise SKILL.md plus detailed
   references and examples.
-argument-hint: "<path|url> [path|url...] [--name <skill-name>] [--update] [--split|--split-by <strategy>]"
+argument-hint: "<path|url> [path|url...] [--name <skill-name>] [--path <directory>] [--update] [--redact-source-map] [--split|--split-by <strategy>]"
 allowed-tools: Read Write Edit Glob Grep Bash(mkdir *) Bash(ls *) Bash(find *) Bash(wc *) Bash(python3 *) WebFetch WebSearch AskUserQuestion
 disable-model-invocation: false
 metadata:
@@ -32,7 +32,7 @@ If config.yaml doesn't exist, use defaults:
 
 **Read `.ai-factory/skill-context/aif-distillation/SKILL.md`** - MANDATORY if the file exists.
 
-Treat skill-context rules as project-level overrides for this skill. They apply to all generated skill files, references, examples, source maps, and final reports.
+Treat skill-context rules as project-level overrides for this skill. They apply to all generated skill files, references, examples, source-map policy, and final reports.
 
 ## Inputs
 
@@ -41,25 +41,30 @@ Accept `$ARGUMENTS` as one or more:
 - local directories
 - URLs
 - optional `--name <skill-name>`
+- optional `--path <directory>` to save generated skill package directories under a custom output root instead of `{{skills_dir}}`
 - optional `--update` to improve an existing skill instead of creating a duplicate
+- optional `--redact-source-map` to skip generated source-map files and sections entirely, so exact source titles, URLs, local paths, repository paths, and link reference definitions are not written to output
 - optional `--split` to create several focused skills from one material set
 - optional `--split-by <strategy>` to choose the split strategy:
-  - `auto` (default): infer skill boundaries from source topics and use cases
+  - `auto` (default): infer skill boundaries from user goals, triggers, workflows, source topics, and use cases
+  - `goal`: split by user goals or jobs-to-be-done, regardless of domain
   - `topic`: split by major source topics or chapters
   - `workflow`: split by recurring actions an agent performs
   - `audience`: split by distinct user roles or implementation contexts
 
-If the target skill name is missing, derive a concise, general, lowercase-hyphenated name from the material topic, such as `clean-code-style`, `api-design-rules`, or `ddd-modeling`.
+If the target skill name is missing, derive a concise, general, lowercase-hyphenated name from the material topic or user goal, such as `clean-code-style`, `api-design-rules`, `decision-making`, `writing-feedback`, or `meeting-facilitation`.
 
 Before any write, validate the final target skill name:
 - It must match `^[a-z0-9]+(?:-[a-z0-9]+)*$`.
 - Reject empty names, overlong names, `.`, `..`, dots, path separators (`/` or `\`), absolute paths, Windows drive paths, and hidden names.
 - Reject reserved `aif-*` names unless the user explicitly says they are developing AI Factory itself.
-- Resolve the final destination path and confirm it is inside `{{skills_dir}}` before creating or updating files.
+- Resolve the output root: `--path <directory>` when present, otherwise `{{skills_dir}}`.
+- Treat relative `--path` values as relative to the current working directory. Create the output root if it does not exist; reject it if it resolves to an existing file.
+- Resolve the final destination path and confirm it is inside the resolved output root before creating or updating files.
 
-Default destination for single-skill mode: `{{skills_dir}}/<skill-name>/` for the current agent.
+Default destination for single-skill mode: `<output-root>/<skill-name>/`, where `<output-root>` is `{{skills_dir}}` unless `--path` is present.
 
-Default destination for split mode: `{{skills_dir}}/<generated-skill-name>/` for each generated child skill. `--name` becomes a naming seed or namespace prefix, not one enclosing package directory, unless the user explicitly asks for an index-only parent skill.
+Default destination for split mode: `<output-root>/<prefix>-<child-scope>/` for each generated child skill. Every split child name must share one namespace prefix to prevent collisions with existing skills. Use `--name` as the preferred prefix when present; otherwise derive a concise prefix from the book title or primary material title. If `--redact-source-map` is present and the exact source title should not be exposed, use `--name` as the public namespace or derive a neutral topic prefix.
 
 Do not save distilled skills into the package `skills/` directory unless the user is explicitly developing AI Factory itself.
 
@@ -79,34 +84,42 @@ Do not save distilled skills into the package `skills/` directory unless the use
 
 3. Choose single-skill or split-skill design.
    - Default to single-skill mode unless `--split` or `--split-by` is present.
-   - In split mode, create a skill boundary map before writing: proposed skill name, trigger description, owned source topics, references/examples needed, and overlap risks.
-   - Prefer split mode when the material contains independent practices that should trigger separately, such as readability refactoring, naming cleanup, testability checks, exception-flow review, or framework-specific passes.
+   - In split mode, resolve one shared namespace prefix before writing the boundary map. Use `--name` when present; otherwise use a normalized book/material title. Every proposed child name must start with `<prefix>-`.
+   - In split mode, create a skill boundary map before writing: proposed prefixed skill name, user-facing job, trigger description, owned source topics, references/examples needed, and overlap risks.
+   - Prefer split mode when the material contains independent goals that should trigger separately, such as reviewing, planning, diagnosing, rewriting, teaching, deciding, testing, facilitating, auditing, or troubleshooting.
+   - Name split children by the user goal or job-to-be-done, not by an abstract source theme. Choose the goal taxonomy from the material's domain: for software this may be `refactoring-review`, `test-design`, or `framework-fit-review`; for writing this may be `argument-edit` or `style-review`; for operations this may be `incident-triage` or `runbook-review`; for management this may be `decision-brief` or `stakeholder-analysis`; for learning this may be `concept-coach` or `practice-drill`.
+   - Avoid vague lifecycle or chapter names such as `framework-evolution`, `principles`, `philosophy`, `chapter-4`, `mindset`, or `overview` unless that exact name is the user's requested public taxonomy.
    - Do not split into tiny skills that differ only by wording. Merge candidates when their triggers, workflow, and reference needs substantially overlap.
-   - Keep every generated child skill independently useful: clear frontmatter, focused workflow, relevant references/examples, and its own source map or source-map section.
+   - Keep every generated child skill independently useful: clear frontmatter, focused workflow, and relevant references/examples. If `--redact-source-map` is absent, include its own source map; if present, do not create `references/SOURCE-MAP.md` or a source-map section.
 
 4. Design the target skill package.
    - Keep target `SKILL.md` focused on purpose, triggers, and workflow.
+   - Make the generated skill self-explanatory from its directory name and frontmatter. The description must start with an action verb and say what the skill reviews, improves, generates, or checks.
+   - Near the top of every generated `SKILL.md`, answer in plain language: what this skill does, when to use it, and what output it should produce. A user should not need to inspect the source material to understand why the skill exists.
    - Put detailed knowledge in `references/`.
    - Put reusable prompts, cases, and transformed examples in `examples/`.
    - If the material teaches programming with code examples, create or update an examples file with original before/after snippets or compact code patterns. Do not omit code examples only because verbatim copying is inappropriate.
    - For book-scale or broad code material, cover every major code-facing topic with an adapted example, or state why a topic does not need one. Split examples into multiple files when one file would become a shallow sampler.
    - Add scripts only when the workflow needs repeatable processing.
-   - In single-skill mode, save the package under `{{skills_dir}}/<skill-name>/` using the chosen concise name.
-   - In split mode, save each child package directly under `{{skills_dir}}/<child-skill-name>/`. If `--name` is present, use it as a concise prefix only when it improves discoverability and does not make names bulky.
+   - Resolve `<output-root>` from `--path` or `{{skills_dir}}` before writing. Treat `--path` as a parent directory for generated skill packages, not as the skill package name.
+   - In single-skill mode, save the package under `<output-root>/<skill-name>/` using the chosen concise name.
+   - In split mode, save each child package directly under `<output-root>/<prefix>-<child-scope>/`. Do not drop the shared prefix even when the child scope is clear on its own.
+   - When `--redact-source-map` is present, do not create `references/SOURCE-MAP.md`, do not create a "Source Map" section in any generated file, and remove any empty `SOURCE-MAP.md` accidentally created during drafting. In `--update` mode, leave an existing non-empty `SOURCE-MAP.md` unchanged unless the user explicitly asks to remove or rewrite it.
    - Use resolved `language.artifacts` for generated skill content unless the source material or user explicitly requires another language.
 
 5. Check existing content before writing.
    - If the target skill already has matching references or examples, update them in place.
    - Do not create near-duplicate files with different names.
    - Preserve useful existing material and add only missing or better distilled content.
-   - In split mode, also check existing sibling skills under `{{skills_dir}}` for matching triggers. Update a matching skill with `--update` instead of creating a new near-duplicate child.
+   - In split mode, also check existing sibling skills under `<output-root>` for matching triggers. Update a matching skill with `--update` instead of creating a new near-duplicate child.
 
 6. Validate usefulness.
    - The skill must tell an agent what to do, when to do it, what good output looks like, and what mistakes to avoid.
+   - The name and description must be invocation-ready. If a user would ask "what does this skill actually do?", rename it or rewrite the trigger before finishing.
    - References must be dense and navigable.
    - Examples must demonstrate decisions or transformations, not decorative filler.
    - If source material contained meaningful code snippets or worked examples, the generated skill must include adapted examples. Missing adapted examples is a failure to fix before finishing.
-   - Example coverage must match the source map: major code-facing source areas should point to concrete examples, not just prose references.
+   - Example coverage must match source coverage: when `--redact-source-map` is absent, record this in the source map; when present, validate coverage internally without writing source-map files or sections.
    - Generated skills must include an artifact ownership/config policy section when they write or read project artifacts.
    - Generated quality-gate skills must follow the `aif-gate-result` contract from `/aif-verify` references.
    - In split mode, every child skill must have a distinct activation trigger. If two children would activate for the same request and tell the agent to do the same work, merge them before finishing.
@@ -122,6 +135,6 @@ Use `examples/REQUESTS.md` for invocation patterns.
 
 ## Artifact Ownership
 
-- Primary ownership: generated or updated skill packages under `{{skills_dir}}/<skill-name>/`, or multiple direct child skill packages under `{{skills_dir}}/<child-skill-name>/` in split mode.
+- Primary ownership: generated or updated skill packages under `<output-root>/<skill-name>/`, or multiple direct child skill packages under `<output-root>/<prefix>-<child-scope>/` in split mode. `<output-root>` is `{{skills_dir}}` unless the user passes `--path <directory>`.
 - Read-only context: `.ai-factory/config.yaml`, existing AI Factory context artifacts, and existing skill files except the selected target skill in update mode.
 - Config policy: config-aware for `language.ui`, `language.artifacts`, and `language.technical_terms` only. Do not write `config.yaml`.

package/skills/aif-distillation/examples/REQUESTS.md

@@ -38,12 +38,38 @@ Expected behavior:
 Expected behavior:
 
 - infer focused child skills from distinct practices rather than creating one broad skill
-- use `code-quality` only as a naming seed when it helps; prefer clear child names such as `readability-refactor`, `naming-cleanup`, `condition-simplifier`, or `testability-pass`
-- write each child directly under `{{skills_dir}}/<child-skill-name>/`
+- use `code-quality` as the required shared namespace prefix
+- prefer clear child names such as `code-quality-readability-refactor`, `code-quality-naming-cleanup`, `code-quality-condition-simplifier`, or `code-quality-testability-pass`
+- write each child directly under `{{skills_dir}}/<prefix>-<child-scope>/`
 - give every child a distinct frontmatter description and activation trigger
-- include source attribution for every child
+- include source attribution for every child unless `--redact-source-map` is present
 - merge or skip candidates whose triggers overlap too much
 
+## Save to a Custom Output Root
+
+```text
+/aif-distillation ./books/domain-driven-design.pdf --name ddd-practices --path ./distilled-skills
+```
+
+Expected output:
+
+- `./distilled-skills/ddd-practices/SKILL.md`
+- `./distilled-skills/ddd-practices/references/SOURCE-MAP.md`
+- no writes to the current agent `{{skills_dir}}`
+- resolved destination stays inside the resolved `--path` output root
+
+## Split into a Custom Output Root
+
+```text
+/aif-distillation ./books/code-quality.pdf --split --name code-quality --path ./distilled-skills
+```
+
+Expected behavior:
+
+- create direct child package directories under `./distilled-skills/`
+- name every child with the shared `code-quality-` prefix
+- do not create a parent `code-quality/` wrapper directory unless explicitly requested as an index/router skill
+
 ## Split by a Specific Strategy
 
 ```text
@@ -53,10 +79,38 @@ Expected behavior:
 Expected behavior:
 
 - split by recurring actions an agent performs, not by arbitrary file count
+- name every child with the shared `review-` prefix, such as `review-triage` or `review-findings`
 - create a boundary map before writing
 - update matching existing child skills when `--update` is also present
 - report created, updated, merged, and skipped candidates
 
+## Split Non-Code Material by User Goals
+
+```text
+/aif-distillation ./books/decision-making.pdf --split-by goal --name decisions
+```
+
+Expected behavior:
+
+- split by jobs the user wants help with, not by chapter titles
+- create names such as `decisions-decision-brief`, `decisions-risk-review`, or `decisions-stakeholder-analysis`
+- make every child explain what it does, when to use it, and what output it should produce
+- avoid vague children such as `decisions-principles`, `decisions-mindset`, or `decisions-chapter-2`
+
+## Redact Source Map Paths and Links
+
+```text
+/aif-distillation ./books/internal-review-guide.pdf --name review-guide --redact-source-map
+```
+
+Expected behavior:
+
+- generate the skill normally
+- do not create `references/SOURCE-MAP.md`
+- do not create a "Source Map" section in `SKILL.md` or any reference file
+- omit exact book titles, URLs, local paths, repository paths, filenames, and link reference definitions from generated files
+- keep source coverage only in private working notes while still producing useful distilled instructions, references, and examples
+
 ## Create a Skill from a Docs Folder
 
 ```text
@@ -86,7 +140,7 @@ Expected behavior:
 - reject the request before writing files
 - explain that skill names must match `^[a-z0-9]+(?:-[a-z0-9]+)*$`
 - reserve `aif-*` names unless the user explicitly says they are developing AI Factory itself
-- confirm the resolved target path would stay under `{{skills_dir}}`
+- confirm the resolved target path would stay under the resolved output root (`{{skills_dir}}` by default, or `--path` when present)
 
 ## Update an Existing Skill
 
@@ -111,5 +165,5 @@ Expected behavior:
 
 - fetch the pages
 - follow only critical sub-pages
-- source-map all URLs used
+- source-map all URLs used unless `--redact-source-map` is present; with redaction, do not create `SOURCE-MAP.md`
 - summarize rules and examples without long quoted passages

package/skills/aif-distillation/references/DISTILLATION-PROTOCOL.md

@@ -16,6 +16,12 @@ Create a source inventory:
 
 For folders, group files by topic before reading deeply. For books, read the table of contents first, then sample each major part before deep extraction.
 
+When the user passes `--redact-source-map`, keep any exact URLs, local paths,
+repository paths, and source titles only in your private working inventory.
+Generated skill files must use neutral source labels such as `Source A`,
+`Book section 1`, or `Internal guide: authentication`, while preserving the
+type, scope, and usage of each source.
+
 ## 2. Extraction
 
 Extract only material that can drive agent behavior:
@@ -90,21 +96,33 @@ Use this section only when the user passes `--split` or `--split-by <strategy>`.
 Split source material into multiple skills when the material contains separate
 capabilities that should activate on different user requests. A split set should
 feel like a small toolkit of focused passes, not a chopped-up book summary.
+If `--path <directory>` is present, create the split set under that output root
+instead of the current agent `{{skills_dir}}`.
 
 Supported strategies:
 
 | Strategy | Use when | Boundary signal |
 |----------|----------|-----------------|
-| `auto` | the user wants several skills but did not prescribe boundaries | strongest distinct triggers from topics, workflows, examples, and target users |
+| `auto` | the user wants several skills but did not prescribe boundaries | strongest distinct goals, triggers, workflows, examples, and target users |
+| `goal` | the material supports several different jobs-to-be-done | each child helps the user accomplish a different outcome |
 | `topic` | the source has clean domain or chapter boundaries | each topic produces different decisions or checks |
 | `workflow` | the source teaches multiple actions | each action has a different input, output, or quality gate |
 | `audience` | the source serves different roles or project contexts | each role/context needs different operating instructions |
 
 Before writing split skills, create a boundary map:
 
-| Child skill | Trigger | Source topics | References/examples | Merge risk |
-|-------------|---------|---------------|---------------------|------------|
-| <name> | <when it should activate> | <topics> | <files> | low/medium/high |
+| Child skill | User goal | Trigger | Source topics | References/examples | Merge risk |
+|-------------|-----------|---------|---------------|---------------------|------------|
+| <name> | <outcome it helps achieve> | <when it should activate> | <topics> | <files> | low/medium/high |
+
+First resolve a shared split namespace prefix:
+
+- use `--name` when the user supplied it
+- otherwise derive the prefix from the book title or primary material title
+- if source-map redaction is requested and the real title should stay private,
+  use a neutral topic prefix instead of the exact title
+- validate the prefix with the same skill-name rules as ordinary skills
+- every generated child name must start with `<prefix>-`
 
 Merge or drop a child candidate when:
 
@@ -119,9 +137,24 @@ passes such as readability refactoring, naming cleanup, condition
 simplification, magic value extraction, exception-flow review, testability, and
 framework-specific review. These names are examples, not required output.
 
-Every child skill must include its own source attribution. For small children,
+For non-code material, use the same goal-first rule. Examples:
+
+- writing or communication: `argument-edit`, `style-review`, `message-critique`
+- strategy or management: `decision-brief`, `stakeholder-analysis`, `risk-review`
+- operations or support: `incident-triage`, `runbook-review`, `escalation-plan`
+- learning material: `concept-explainer`, `practice-drill`, `understanding-check`
+- research material: `evidence-synthesis`, `claim-audit`, `literature-map`
+
+Avoid source-theme children with unclear invocation intent.
+If a candidate name makes a user ask "what does this do?", rename it around the
+goal and expected output.
+
+Every child skill must include its own source attribution unless
+`--redact-source-map` is present. For small non-redacted children,
 `references/SOURCE-MAP.md` may be the only reference; for larger children, add
-focused references and examples.
+focused references and examples. In redaction mode, do not create
+`references/SOURCE-MAP.md`; keep source coverage in the private working
+inventory and ship only the distilled instructions, references, and examples.
 
 ## 6. Existing-File Merge
 
@@ -150,7 +183,8 @@ description and workflow already cover the same capability.
 
 ## 7. Traceability
 
-Every distilled skill should include a source map in a reference:
+Every distilled skill should include a source map in a reference unless
+`--redact-source-map` is present:
 
 ```markdown
 ## Source Map
@@ -160,7 +194,16 @@ Every distilled skill should include a source map in a reference:
 | <path-or-url> | <principles, workflow, examples, checks> |
 ```
 
-Do not imply that every rule is a direct quote. Distillation is synthesis; source maps explain provenance.
+When `--redact-source-map` is present, do not create `references/SOURCE-MAP.md`
+and do not add a "Source Map" section to any generated file. Do not write link
+reference definitions, raw path fragments, repository paths, filenames that
+reveal the source, exact URLs, or exact book/document titles anywhere as source
+attribution. If a draft creates an empty `SOURCE-MAP.md`, remove it before
+finishing. In `--update` mode, leave an existing non-empty `SOURCE-MAP.md`
+unchanged unless the user explicitly asks to remove or rewrite it.
+
+For non-redacted source maps, do not imply that every rule is a direct quote.
+Distillation is synthesis; source maps explain provenance.
 
 ## 8. Quality Gate
 
@@ -175,7 +218,8 @@ Before finishing, check:
 - Example coverage maps to the source areas. If references mention many
   code-facing topics but examples cover only a few, the skill is incomplete.
 - Existing references/examples were updated instead of duplicated.
-- Split mode only: each child skill has a distinct trigger, direct `{{skills_dir}}/<child>/` location, source attribution, and enough references/examples to operate independently.
+- Split mode only: each child skill has a distinct trigger, direct `<output-root>/<prefix>-<child>/` location, source attribution when not redacted, no `SOURCE-MAP.md` when redacted, and enough references/examples to operate independently.
+- Split mode only: all generated child names share the same prefix derived from `--name`, the book title, or a neutral material namespace.
 - Split mode only: no generated child is a near-duplicate of another generated or existing sibling skill.
 - Temporary extraction files were removed.
 - No long copyrighted passages were copied.

package/skills/aif-distillation/references/LARGE-MATERIALS.md

@@ -28,6 +28,11 @@ Optional flags:
 
 Read `source-index.md` first. Then read only the chunks needed for each section of the target skill.
 
+When `--redact-source-map` is present, treat `source-index.md` as a private
+working index only. Do not copy its raw URLs, local paths, filenames, or exact
+source titles into generated files. Do not create `references/SOURCE-MAP.md`
+for redacted output.
+
 ## Chunking Strategy
 
 Use this order:

package/skills/aif-distillation/references/OUTPUT-STRUCTURE.md

@@ -5,10 +5,10 @@ Use this structure for skills created by `aif-distillation`.
 ## Target Package
 
 ```text
-{{skills_dir}}/<skill-name>/
+<output-root>/<skill-name>/
 ├── SKILL.md
 ├── references/
-│   ├── SOURCE-MAP.md
+│   ├── SOURCE-MAP.md   # omit when --redact-source-map is present
 │   ├── CORE-PRINCIPLES.md
 │   ├── WORKFLOW.md
 │   └── CHECKLISTS.md
@@ -33,22 +33,23 @@ When the user passes `--split` or `--split-by <strategy>`, create multiple
 focused skill packages instead of one broad package:
 
 ```text
-{{skills_dir}}/
-├── <child-skill-a>/
+<output-root>/
+├── <prefix>-<child-skill-a>/
 │   ├── SKILL.md
 │   ├── references/
-│   │   ├── SOURCE-MAP.md
+│   │   ├── SOURCE-MAP.md   # omit when --redact-source-map is present
 │   │   └── <focused-reference>.md
 │   └── examples/
 │       └── <focused-examples>.md
-├── <child-skill-b>/
+├── <prefix>-<child-skill-b>/
 │   └── SKILL.md
 └── <optional-index-skill>/
     └── SKILL.md
 ```
 
 Do not create a parent directory that contains child skills. Agent runtimes
-discover skills as direct children of `{{skills_dir}}`.
+discover skills as direct children of the output root when that root is an
+agent skills directory.
 
 Create an optional index/router skill only when it is genuinely useful, for
 example when the split set is large or users need a single command-style entry
@@ -62,28 +63,50 @@ boundaries include:
 - a distinct refactoring operation, such as `early-return-simplifier`
 - a distinct framework or runtime practice, such as `laravel-query-boundaries`
 - a distinct writing or analysis workflow, such as `comments-curator`
+- a distinct non-code goal, such as `argument-edit`, `decision-brief`,
+  `incident-triage`, `practice-drill`, or `risk-review`
 
 Avoid split boundaries based only on source chapter titles when the resulting
 skills would have the same trigger and workflow.
 
 ## Destination
 
-Save the distilled skill in the configured skills directory of the currently active agent:
+Save the distilled skill in the configured skills directory of the currently active agent by default:
 
 ```text
 {{skills_dir}}/<skill-name>/
 ```
 
 `{{skills_dir}}` is resolved by AI Factory for the active agent installation.
+If the user passes `--path <directory>`, use that directory as the output root
+instead:
+
+```text
+<directory>/<skill-name>/
+```
+
+`--path` is a parent output directory for generated skill package directories,
+not the skill package name itself. Resolve relative `--path` values from the
+current working directory. Create the output root if it does not exist; reject
+it if it resolves to an existing file. For a single exact destination, the user
+should pass `--path <parent-dir> --name <directory-name>`.
 
 Do not write distilled output into AI Factory's package `skills/` directory unless the task is explicitly to add a built-in AI Factory skill.
 
-Before writing, resolve and canonicalize the final destination path. It must stay inside the resolved `{{skills_dir}}` directory.
+Before writing, resolve and canonicalize the output root and final destination
+path. The final destination must stay inside the resolved output root. When
+`--path` is absent, the output root is `{{skills_dir}}`.
 
 For split mode, apply this same validation to every generated child skill path.
-If `--name <seed>` is supplied, use it as a naming seed or short prefix only
-when it improves discoverability. Prefer clear standalone names over repetitive
-prefixes.
+Every generated child name must use one shared namespace prefix:
+
+- use `--name <skill-name>` as the prefix when supplied
+- otherwise derive a concise prefix from the book title or primary material title
+- when source-map redaction is requested, avoid exposing a private title and use
+  `--name` or a neutral material/topic prefix instead
+- write children as `<output-root>/<prefix>-<child-scope>/`
+- do not create unprefixed split children, even when the child scope reads well
+  by itself
 
 ## Naming
 
@@ -101,6 +124,10 @@ Good:
 - `domain-modeling`
 - `api-design-rules`
 - `incident-review`
+- `argument-edit`
+- `decision-brief`
+- `practice-drill`
+- `risk-review`
 
 Avoid:
 
@@ -112,11 +139,15 @@ Avoid:
 
 In split mode, generate a name list before writing and check it as a set:
 
+- every name must start with the same resolved namespace prefix plus `-`
 - every name must pass the same validation rules
 - no name may collide with another generated child
 - no generated child may shadow a built-in `aif-*` skill
-- names should describe activation scope, not provenance
-- when multiple child names share a long prefix, remove the prefix unless it is needed to prevent ambiguity
+- the suffix after the prefix should describe the user goal and expected action, not provenance
+- avoid double-prefixing names when a candidate suffix already contains the prefix
+- avoid abstract source-theme suffixes such as `principles`, `philosophy`,
+  `evolution`, `mindset`, or `chapter-3` unless the user explicitly requested
+  that taxonomy
 
 ## SKILL.md Rules
 
@@ -147,7 +178,7 @@ For AI Factory-style skills, also include:
 
 | File | Purpose |
 |------|---------|
-| `SOURCE-MAP.md` | Sources, coverage, and attribution |
+| `SOURCE-MAP.md` | Sources, coverage, and attribution; omit entirely when `--redact-source-map` is present |
 | `CORE-PRINCIPLES.md` | Dense distilled concepts and rules |
 | `WORKFLOW.md` | Step-by-step operating procedure |
 | `CHECKLISTS.md` | Review gates and quality criteria |
@@ -156,6 +187,15 @@ For AI Factory-style skills, also include:
 
 Prefer stable, obvious filenames over clever names.
 
+When `--redact-source-map` is present:
+
+- do not create `references/SOURCE-MAP.md`
+- do not create a "Source Map" section in `SKILL.md` or any reference file
+- remove any empty `SOURCE-MAP.md` created while drafting
+- in `--update` mode, leave an existing non-empty `SOURCE-MAP.md` unchanged
+  unless the user explicitly asks to remove or rewrite it
+- keep source coverage checks in the private working notes only
+
 ## Example File Roles
 
 Examples should show how to apply the distilled knowledge: