ai-factory 2.3.0 → 2.4.0

package/skills/aif-rules/SKILL.md

@@ -12,6 +12,28 @@ Add short, actionable rules and conventions for the current project. Rules are s
 
 ## Workflow
 
+### Step 0: Load Skill Context
+
+**Read `.ai-factory/skill-context/aif-rules/SKILL.md`** — MANDATORY if the file exists.
+
+This file contains project-specific rules accumulated by `/aif-evolve` from patches,
+codebase conventions, and tech-stack analysis. These rules are tailored to the current project.
+
+**How to apply skill-context rules:**
+- Treat them as **project-level overrides** for this skill's general instructions
+- When a skill-context rule conflicts with a general rule written in this SKILL.md,
+  **the skill-context rule wins** (more specific context takes priority — same principle as nested CLAUDE.md files)
+- When there is no conflict, apply both: general rules from SKILL.md + project rules from skill-context
+- Do NOT ignore skill-context rules even if they seem to contradict this skill's defaults —
+  they exist because the project's experience proved the default insufficient
+- **CRITICAL:** skill-context rules apply to ALL outputs of this skill — including the RULES.md
+  format and rule formulation. If a skill-context rule says "rules MUST follow format X" or
+  "RULES.md MUST include section Y" — you MUST comply. Generating rules that violate skill-context
+  is a bug.
+
+**Enforcement:** After generating any output artifact, verify it against all skill-context rules.
+If any rule is violated — fix the output before presenting it to the user.
+
 ### Step 1: Determine Mode
 
 ```
@@ -103,3 +125,4 @@ Total rules: [count]
 3. **No duplicates** — check for existing rules with the same meaning before adding
 4. **Actionable language** — rules should be clear directives ("Always...", "Never...", "Use...", "Routes must...")
 5. **RULES.md location** — always `.ai-factory/RULES.md`, create `.ai-factory/` directory if needed
+6. **Ownership boundary** — this command owns `.ai-factory/RULES.md`; other context artifacts stay read-only unless explicitly requested by the user

package/skills/aif-security-checklist/SKILL.md

@@ -90,6 +90,30 @@ When audit results are shown, append this section at the end:
 
 ---
 
+### Project Context
+
+**Read `.ai-factory/skill-context/aif-security-checklist/SKILL.md`** — MANDATORY if the file exists.
+
+This file contains project-specific rules accumulated by `/aif-evolve` from patches,
+codebase conventions, and tech-stack analysis. These rules are tailored to the current project.
+
+**How to apply skill-context rules:**
+- Treat them as **project-level overrides** for this skill's general instructions
+- When a skill-context rule conflicts with a general rule written in this SKILL.md,
+  **the skill-context rule wins** (more specific context takes priority — same principle as nested CLAUDE.md files)
+- When there is no conflict, apply both: general rules from SKILL.md + project rules from skill-context
+- Do NOT ignore skill-context rules even if they seem to contradict this skill's defaults —
+  they exist because the project's experience proved the default insufficient
+- **CRITICAL:** skill-context rules apply to ALL outputs of this skill — including security
+  checklists, the Pre-Deployment Checklist, and SECURITY.md. If a skill-context rule says
+  "checklist MUST include X" or "audit MUST cover Y" — you MUST augment the checklists accordingly.
+  Producing a security report that ignores skill-context rules is a bug.
+
+**Enforcement:** After generating any output artifact, verify it against all skill-context rules.
+If any rule is violated — fix the output before presenting it to the user.
+
+---
+
 ## Quick Automated Audit
 
 Run the automated security audit script:

package/skills/aif-skill-generator/SKILL.md

@@ -14,6 +14,28 @@ metadata:
 
 You are an expert Agent Skills architect. You help users create professional, production-ready skills that follow the [Agent Skills](https://agentskills.io/specification) open standard.
 
+### Project Context
+
+**Read `.ai-factory/skill-context/aif-skill-generator/SKILL.md`** — MANDATORY if the file exists.
+
+This file contains project-specific rules accumulated by `/aif-evolve` from patches,
+codebase conventions, and tech-stack analysis. These rules are tailored to the current project.
+
+**How to apply skill-context rules:**
+- Treat them as **project-level overrides** for this skill's general instructions
+- When a skill-context rule conflicts with a general rule written in this SKILL.md,
+  **the skill-context rule wins** (more specific context takes priority — same principle as nested CLAUDE.md files)
+- When there is no conflict, apply both: general rules from SKILL.md + project rules from skill-context
+- Do NOT ignore skill-context rules even if they seem to contradict this skill's defaults —
+  they exist because the project's experience proved the default insufficient
+- **CRITICAL:** skill-context rules apply to ALL outputs of this skill — including the generated
+  SKILL.md and skill package structure. If a skill-context rule says "generated skills MUST include X"
+  or "SKILL.md MUST have section Y" — you MUST augment the output accordingly. Generating a skill
+  that violates skill-context rules is a bug.
+
+**Enforcement:** After generating any output artifact, verify it against all skill-context rules.
+If any rule is violated — fix the output before presenting it to the user.
+
 ## CRITICAL: Security Scanning
 
 **Every skill MUST be scanned for prompt injection before installation or use.**

package/skills/aif-skill-generator/scripts/validate.sh

@@ -43,7 +43,7 @@ fi
 pass "SKILL.md exists"
 
 # Extract frontmatter (between first two --- lines)
-FRONTMATTER=$(awk '/^---$/{if(++n==1)next; if(n==2)exit} n==1' "$SKILL_MD")
+FRONTMATTER=$(tr -d '\r' < "$SKILL_MD" | awk '/^---$/{if(++n==1)next; if(n==2)exit} n==1')
 
 if [[ -z "$FRONTMATTER" ]]; then
     error "No YAML frontmatter found (must be between --- markers)"
@@ -88,7 +88,7 @@ else
 fi
 
 # Check description field - handle multiline (read directly from file to avoid quoting issues)
-DESC=$(awk '
+DESC=$(tr -d '\r' < "$SKILL_MD" | awk '
     /^---$/ { n++; next }
     n == 1 && /^description:/ {
         found = 1
@@ -105,7 +105,7 @@ DESC=$(awk '
     n == 1 && found && /^[^[:space:]]/ { exit }
     n == 2 { exit }
     END { print desc }
-' "$SKILL_MD")
+' )
 
 if [[ -z "$DESC" ]]; then
     error "Missing required 'description' field"
@@ -144,7 +144,7 @@ if [[ -n "$ARG_HINT_LINE" ]]; then
 fi
 
 # Count body lines (after second ---)
-BODY_LINES=$(awk '/^---$/{if(++n==2){found=1; next}} found' "$SKILL_MD" | wc -l | tr -d ' ')
+BODY_LINES=$(tr -d '\r' < "$SKILL_MD" | awk '/^---$/{if(++n==2){found=1; next}} found' | wc -l | tr -d ' ')
 
 if [[ $BODY_LINES -gt 500 ]]; then
     warn "SKILL.md body exceeds 500 lines ($BODY_LINES). Consider moving content to references/"

package/skills/aif-verify/SKILL.md

@@ -23,6 +23,15 @@ Verify that the completed implementation matches the plan, nothing was missed, a
 
 ## Step 0: Load Context
 
+### 0.0 Load Ownership and Gate Contract
+
+- Read `references/CONTEXT-GATES-AND-OWNERSHIP.md` first.
+- Treat it as the canonical source for:
+  - command-to-artifact ownership,
+  - read-only behavior for `aif-commit`/`aif-review`/`aif-verify`,
+  - normal vs strict context-gate thresholds.
+- If this contract conflicts with older examples in this file, follow the contract.
+
 ### 0.1 Find Plan File
 
 Same logic as `/aif-implement`:
@@ -49,6 +58,29 @@ Options:
 - Read the plan file to understand what was supposed to be implemented
 - `TaskList` → get all tasks and their statuses
 - Read `.ai-factory/DESCRIPTION.md` for project context (tech stack, conventions)
+- Read `.ai-factory/ARCHITECTURE.md` for dependency and boundary rules (if present)
+- Read `.ai-factory/RULES.md` for project-specific conventions (if present)
+- Read `.ai-factory/ROADMAP.md` for milestone alignment checks (if present)
+
+**Read `.ai-factory/skill-context/aif-verify/SKILL.md`** — MANDATORY if the file exists.
+
+This file contains project-specific rules accumulated by `/aif-evolve` from patches,
+codebase conventions, and tech-stack analysis. These rules are tailored to the current project.
+
+**How to apply skill-context rules:**
+- Treat them as **project-level overrides** for this skill's general instructions
+- When a skill-context rule conflicts with a general rule written in this SKILL.md,
+  **the skill-context rule wins** (more specific context takes priority — same principle as nested CLAUDE.md files)
+- When there is no conflict, apply both: general rules from SKILL.md + project rules from skill-context
+- Do NOT ignore skill-context rules even if they seem to contradict this skill's defaults —
+  they exist because the project's experience proved the default insufficient
+- **CRITICAL:** skill-context rules apply to ALL outputs of this skill — including the Verification
+  Report template. If a skill-context rule says "verification MUST check X" or "report MUST include
+  section Y" — you MUST augment the report accordingly. Generating a verification that ignores
+  skill-context rules is a bug.
+
+**Enforcement:** After generating any output artifact, verify it against all skill-context rules.
+If any rule is violated — fix the output before presenting it to the user.
 
 ### 0.3 Gather Changed Files
 
@@ -206,6 +238,61 @@ Check if `.ai-factory/DESCRIPTION.md` reflects the current state:
 - Architecture changes → should be reflected
 - New integrations → should be documented
 
+### 3.5 Context Gates (Architecture / Roadmap / Rules)
+
+Apply the canonical contract from `references/CONTEXT-GATES-AND-OWNERSHIP.md`.
+
+Evaluate and report each gate explicitly:
+
+- **Architecture gate**
+  - Pass: implementation follows documented boundaries and dependency rules
+  - Warn: architecture mapping is ambiguous or stale
+  - Fail: clear violation of explicit architecture constraints
+
+- **Rules gate**
+  - Pass: implementation follows explicit project rules
+  - Warn: relevance/verification is ambiguous
+  - Fail: clear violation of explicit rule text
+
+- **Roadmap gate**
+  - Pass: work aligns with existing milestone direction (prefer `## Roadmap Linkage` from the plan when present)
+  - Warn: `.ai-factory/ROADMAP.md` missing, ambiguous mapping, or no milestone linkage for `feat`/`fix`/`perf` scope
+  - Fail (strict mode): clear roadmap contradiction after all available roadmap context is considered
+
+Normal mode behavior:
+- Architecture/rules clear violations fail verification.
+- Roadmap mismatch and missing milestone linkage are warnings unless contradiction is explicit and severe.
+
+Strict mode behavior:
+- Architecture and rules clear violations fail verification.
+- Clear roadmap mismatch fails verification.
+- Missing milestone linkage for `feat`/`fix`/`perf` remains a warning (even when `.ai-factory/ROADMAP.md` exists).
+
+Logging/reporting format:
+- Non-blocking findings: `WARN [gate-name] ...`
+- Blocking findings: `ERROR [gate-name] ...`
+
+### 3.6 Context Drift (Optional Remediation)
+
+`/aif-verify` is **read-only** for context artifacts. Do not edit or regenerate `.ai-factory/*` files here.
+
+If you detect that a context artifact is stale, missing, or ambiguous, report it as a drift finding and provide the owner-command remediation:
+
+- `DESCRIPTION.md` drift → suggest `/aif` (or note that `/aif-implement` should have updated it during implementation)
+- `ARCHITECTURE.md` drift → suggest `/aif-architecture`
+- `ROADMAP.md` drift → suggest `/aif-roadmap check` (or `/aif-roadmap <update request>`)
+- `RULES.md` drift → suggest `/aif-rules <rule text>`
+
+Ask the user a single optional question **only if** drift was detected and fixing it now would materially improve correctness:
+
+```
+AskUserQuestion: Context drift detected. Capture updates now?
+
+Options:
+1. Yes — show the exact commands to run (recommended)
+2. No — proceed without updating context
+```
+
 ---
 
 ## Step 4: Verification Report
@@ -348,6 +435,11 @@ When invoked with `--strict`:
 - **Lint must pass** — zero warnings, zero errors
 - **No TODOs/FIXMEs** in changed files
 - **No undocumented environment variables**
+- **Architecture gate must pass** — fail on clear boundary/dependency violations
+- **Rules gate must pass** — fail on clear rule violations
+- **Roadmap gate must pass** — fail on clear roadmap mismatch
+- Missing milestone linkage for `feat`/`fix`/`perf` is a warning even in strict mode
+- Do not fail strict verification solely because milestone linkage is missing
 
 Strict mode is recommended before merging to main or creating a pull request.
 

package/skills/aif-verify/references/CONTEXT-GATES-AND-OWNERSHIP.md

@@ -0,0 +1,75 @@
+# Context Gates and Artifact Ownership Contract
+
+Canonical contract for AI Factory workflow commands. This file defines:
+- which command owns each artifact,
+- which commands consume artifacts as read-only context,
+- and how context gates behave in normal vs strict verification.
+
+## Command-to-Artifact Matrix
+
+| Command            | Primary write ownership                                                                  | Read-only context                                                                            | Approved exceptions                                                                                                                                                   |
+|--------------------|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `aif`              | `.ai-factory/DESCRIPTION.md`, `AGENTS.md` (setup map), skill installation and MCP config | Existing project files and context artifacts                                                 | May invoke `aif-architecture` to create/update `.ai-factory/ARCHITECTURE.md` during setup                                                                             |
+| `aif-architecture` | `.ai-factory/ARCHITECTURE.md`                                                            | `.ai-factory/DESCRIPTION.md`                                                                 | May update `DESCRIPTION.md` architecture pointer and `AGENTS.md` context table                                                                                        |
+| `aif-roadmap`      | `.ai-factory/ROADMAP.md`                                                                 | `.ai-factory/DESCRIPTION.md`, `.ai-factory/ARCHITECTURE.md`                                  | `aif-implement` may mark completed milestones after implementation                                                                                                    |
+| `aif-rules`        | `.ai-factory/RULES.md`                                                                   | Existing project context                                                                     | None                                                                                                                                                                  |
+| `aif-plan`         | `.ai-factory/PLAN.md`, `.ai-factory/plans/<branch>.md`                                   | `.ai-factory/DESCRIPTION.md`, `.ai-factory/ARCHITECTURE.md`, `.ai-factory/RESEARCH.md`       | `aif-improve` may refine existing plan files                                                                                                                          |
+| `aif-implement`    | Plan progress updates (checkboxes/task status)                                           | `.ai-factory/RULES.md`, `.ai-factory/ARCHITECTURE.md`, `.ai-factory/DESCRIPTION.md`, patches | May update `.ai-factory/DESCRIPTION.md` and `.ai-factory/ARCHITECTURE.md` only when stack/structure changed; may update `.ai-factory/ROADMAP.md` milestone completion |
+| `aif-fix`          | `.ai-factory/FIX_PLAN.md` (plan mode), `.ai-factory/patches/*.md`                        | `.ai-factory/DESCRIPTION.md`, existing patches                                               | None (context artifacts remain read-only by default)                                                                                                                  |
+| `aif-evolve`       | `.ai-factory/evolutions/*.md`, `.ai-factory/skill-context/*`                             | `.ai-factory/DESCRIPTION.md`, `.ai-factory/patches/*.md`                                     | None                                                                                                                                                                  |
+| `aif-docs`         | `README.md`, `docs/*`, `AGENTS.md` documentation section                                 | Project/context files for factual docs                                                       | None                                                                                                                                                                  |
+| `aif-explore`      | `.ai-factory/RESEARCH.md` only                                                           | All context and codebase files for analysis                                                  | None                                                                                                                                                                  |
+| `aif-commit`       | Git commit object/message only                                                           | Context artifacts are read-only gates                                                        | No context artifact writes by default                                                                                                                                 |
+| `aif-review`       | Review output/comments only                                                              | Context artifacts are read-only gates                                                        | No context artifact writes by default unless user explicitly asks                                                                                                     |
+| `aif-verify`       | Verification report output                                                               | Context artifacts are read-only gates                                                        | May move to fix flow after user confirmation; no default context artifact writes                                                                                      |
+
+## Artifact Update Policy (Recommended)
+
+- **Owner writes only:** An artifact should be updated by its owner command.
+- **Implement may do factual deltas:** `aif-implement` may update `.ai-factory/DESCRIPTION.md` and `.ai-factory/ARCHITECTURE.md` only when implementation materially changed stack/structure; it may mark roadmap milestones complete when evidence is clear.
+- **Verify stays read-only:** `aif-verify` reports drift and suggests owner commands; it does not update context artifacts by default.
+- **Rules are explicit:** Only `aif-rules` edits `.ai-factory/RULES.md`. Other commands may propose candidate rules and instruct the user to run `/aif-rules`.
+
+## Context Gates (commit/review/verify)
+
+These commands evaluate context consistency against:
+- `.ai-factory/ARCHITECTURE.md`
+- `.ai-factory/ROADMAP.md` (optional, graceful if missing)
+- `.ai-factory/RULES.md` (optional, graceful if missing)
+
+Gate outputs must use:
+- `WARN` for non-blocking mismatches or missing optional files
+- `ERROR` for blocking violations
+
+### Architecture Gate
+- **Pass:** Changes follow documented module/layer boundaries.
+- **Warn:** Architecture document appears stale or mapping is ambiguous.
+- **Fail:** Clear boundary/dependency violation against explicit architecture rules.
+
+### Rules Gate
+- **Pass:** Changes comply with explicit project rules.
+- **Warn:** Rule relevance is uncertain or cannot be verified confidently.
+- **Fail:** Clear violation of an explicit rule in `.ai-factory/RULES.md`.
+
+### Roadmap Gate
+- **Pass:** Changes align with an active milestone or approved roadmap direction.
+- **Warn:** `.ai-factory/ROADMAP.md` missing, ambiguous milestone mapping, or no milestone linkage for `feat`/`fix`/`perf` work.
+- **Fail (strict verify only):** Clear mismatch with roadmap direction after all available roadmap context is considered.
+
+## Threshold Decisions (Resolved)
+
+### Verify normal mode
+- Architecture/rules clear violations: **fail**
+- Roadmap mismatch: **warn** unless contradiction is explicit and severe
+- Missing milestone linkage for `feat`/`fix`/`perf`: **warn**
+
+### Verify strict mode
+- Architecture clear violations: **fail**
+- Rules clear violations: **fail**
+- Roadmap clear mismatch: **fail**
+- Missing milestone linkage for `feat`/`fix`/`perf` when `.ai-factory/ROADMAP.md` exists: **warn**
+
+### Commit and review mode
+- Context gates are read-only and non-destructive.
+- Missing roadmap linkage for `feat`/`fix`/`perf`: **warn** by default.
+- Blocking behavior is only allowed when explicitly requested by the user or policy extension.