ai-factory 2.2.2 → 2.4.0

package/skills/aif-plan/SKILL.md

@@ -34,6 +34,36 @@ Use this context when:
 - Planning file structure (follow project conventions)
 - **Follow architecture guidelines from `.ai-factory/ARCHITECTURE.md` when planning file structure and task organization**
 
+**Read `.ai-factory/skill-context/aif-plan/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 PLAN.md
+  template and task format. The plan template from TASK-FORMAT.md is a **base structure**. If a
+  skill-context rule says "tasks MUST include X" or "plan MUST have section Y" — you MUST augment
+  the template accordingly. Generating a plan 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.
+
+**OPTIONAL (recommended):** Read `.ai-factory/ROADMAP.md` if it exists:
+- Use it to link this plan to a specific milestone (when applicable)
+- This reduces ambiguity in `/aif-implement` milestone completion and `/aif-verify` roadmap gates
+
+**OPTIONAL (recommended):** Read `.ai-factory/RESEARCH.md` if it exists:
+- Treat `## Active Summary (input for /aif-plan)` as an additional requirements source
+- Carry over constraints/decisions into tasks and plan settings
+- Prefer the summary over raw notes; use `## Sessions` only when you need deeper rationale
+- If the user omitted the feature description, use `Active Summary -> Topic:` as the default description
+
 ### Step 0.1: Ensure Git Repository
 
 ```bash
@@ -57,6 +87,10 @@ full        → Full mode (first word)
 - Remaining text becomes the description
 - `--list` and `--cleanup` execute immediately and **STOP** (do NOT continue to Step 1+)
 
+**If the description is empty:**
+- If `.ai-factory/RESEARCH.md` exists and its `Active Summary` has a non-empty `Topic:`, default the description to that topic (no extra user input required)
+- Otherwise, ask the user for a short feature description
+
 **If `--list` is present**, jump to [--list Subcommand](#--list-subcommand).
 **If `--cleanup` is present**, jump to [--cleanup Subcommand](#--cleanup-subcommand).
 
@@ -73,6 +107,10 @@ Options:
 2. Fast — quick plan, no branch, saves to PLAN.md
 ```
 
+If the user did not provide a description and `.ai-factory/RESEARCH.md` exists:
+- Mention that you will default the description to the `Active Summary` topic
+- Only ask for `full` vs `fast` (no description prompt needed)
+
 For concrete parsing examples and expected behavior per command shape, read `references/EXAMPLES.md` (Argument Parsing).
 
 ---
@@ -140,7 +178,11 @@ AskUserQuestion: Before we start, a few questions:
    - [ ] Yes, update docs (/aif-docs)
    - [ ] No, skip docs
 
-4. Any specific requirements or constraints?
+4. Roadmap milestone linkage (only if `.ai-factory/ROADMAP.md` exists):
+   - [ ] Link this plan to a milestone
+   - [ ] Skip — no linkage (allowed; `/aif-verify --strict` should report WARN, not fail, for missing linkage alone)
+
+5. Any specific requirements or constraints?
 ```
 
 **Default to verbose logging.** AI-generated code benefits greatly from extensive logging because:
@@ -150,6 +192,11 @@ AskUserQuestion: Before we start, a few questions:
 
 Store all preferences — they will be used in the plan file and passed to `/aif-implement`.
 
+**If `.ai-factory/ROADMAP.md` exists and the user chose milestone linkage:**
+- Read `.ai-factory/ROADMAP.md` and list candidate milestones (prefer unchecked items)
+- Ask the user to pick one milestone (or type a custom one)
+- Store the selected milestone name and a 1-sentence rationale for inclusion in the plan file
+
 ### Step 1.4: Create Branch or Worktree
 
 **If `--parallel` flag is set → create worktree:**
@@ -179,6 +226,7 @@ WORKTREE="../${DIRNAME}-<branch-name-with-hyphens>"
 # Project context
 cp .ai-factory/DESCRIPTION.md "${WORKTREE}/.ai-factory/DESCRIPTION.md" 2>/dev/null
 cp .ai-factory/ARCHITECTURE.md "${WORKTREE}/.ai-factory/ARCHITECTURE.md" 2>/dev/null
+cp .ai-factory/RESEARCH.md "${WORKTREE}/.ai-factory/RESEARCH.md" 2>/dev/null
 
 # Past lessons / patches
 cp -r .ai-factory/patches/ "${WORKTREE}/.ai-factory/patches/" 2>/dev/null
@@ -242,6 +290,10 @@ AskUserQuestion: Before we start:
    - [ ] No, skip tests
 
 2. Any specific requirements or constraints?
+
+3. Roadmap milestone linkage (only if `.ai-factory/ROADMAP.md` exists):
+   - [ ] Link this plan to a milestone
+   - [ ] Skip — no linkage (allowed; `/aif-verify --strict` should report WARN, not fail, for missing linkage alone)
 ```
 
 **Plan file:** Always `.ai-factory/PLAN.md` (no branch, no branch-named file).
@@ -330,9 +382,19 @@ mkdir -p .ai-factory/plans  # only when saving to branch-named plan files
 - Title with feature name
 - Branch and creation date
 - `Settings` section (Testing, Logging, Docs)
+- `Roadmap Linkage` section (optional, only if `.ai-factory/ROADMAP.md` exists)
+- `Research Context` section (optional, if `.ai-factory/RESEARCH.md` exists)
 - `Tasks` section grouped by phases
 - `Commit Plan` section when there are 5+ tasks
 
+If `.ai-factory/ROADMAP.md` exists:
+- If the user linked a milestone, write `## Roadmap Linkage` with `Milestone: "..."` and `Rationale: ...`
+- If the user skipped linkage, write `## Roadmap Linkage` with `Milestone: "none"` and `Rationale: "Skipped by user"`
+
+If `.ai-factory/RESEARCH.md` exists:
+- Include `## Research Context` by copying only the `Active Summary` (do not paste full `Sessions`)
+- Keep it compact; it should be readable as a one-screen requirements snapshot
+
 Use the canonical template in `references/TASK-FORMAT.md` (Plan File Template).
 
 **Commit Plan Rules:**
@@ -466,6 +528,8 @@ Use canonical examples in `references/TASK-FORMAT.md`:
 6. **Include file paths** — Help implementer know where to work
 7. **Commit checkpoints for large plans** — 5+ tasks need commit plan with checkpoints every 3-5 tasks
 8. **Plan file location** — Fast mode: `.ai-factory/PLAN.md`. Full mode: `.ai-factory/plans/<branch-name>.md`
+9. **Ownership boundary** — This command owns plan files only (`.ai-factory/PLAN.md`, `.ai-factory/plans/<branch>.md`). Use owner commands (`/aif-roadmap`, `/aif-rules`, `/aif-explore`) for their artifacts.
+10. **Roadmap linkage (when available)** — If `.ai-factory/ROADMAP.md` exists, include a `## Roadmap Linkage` section in the plan (or explicitly state it was skipped).
 
 ## Plan File Handling
 

package/skills/aif-plan/references/EXAMPLES.md

@@ -16,6 +16,14 @@
 -> mode=full, description="Add user authentication with OAuth"
 ```
 
+### Full mode with description omitted (defaults from RESEARCH.md)
+
+```text
+/aif-plan full
+-> mode=full
+-> description defaults to .ai-factory/RESEARCH.md Active Summary Topic (if present)
+```
+
 ### Full mode with parallel worktree
 
 ```text
@@ -44,6 +52,14 @@
 -> ask mode interactively, description="Add user authentication"
 ```
 
+### No mode + no description (defaults from RESEARCH.md)
+
+```text
+/aif-plan
+-> ask mode interactively
+-> description defaults to .ai-factory/RESEARCH.md Active Summary Topic (if present)
+```
+
 ## Flow Scenarios
 
 ### Scenario 1: Fast mode
@@ -67,6 +83,7 @@
 -> mode=full
 -> Quick reconnaissance
 -> Branch: feature/user-authentication
+-> If ROADMAP.md exists: asks about milestone linkage, user picks one (or skips)
 -> Asks about tests (Yes), logging (Verbose), docs (Yes)
 -> Creates branch
 -> Explores codebase deeply
@@ -83,6 +100,7 @@
 -> mode=full, parallel=true
 -> Quick reconnaissance
 -> Branch: feature/stripe-checkout
+-> If ROADMAP.md exists: asks about milestone linkage, user picks one (or skips)
 -> Asks about tests (No), logging (Verbose), docs (No)
 -> Creates worktree ../my-project-feature-stripe-checkout
 -> Copies context files, cd into worktree

package/skills/aif-plan/references/TASK-FORMAT.md

@@ -13,6 +13,20 @@ Created: [date]
 - Logging: verbose/standard/minimal
 - Docs: yes/no
 
+## Roadmap Linkage (optional)
+<!-- Only when .ai-factory/ROADMAP.md exists -->
+Milestone: "[milestone name from ROADMAP.md]"  # or "none"
+Rationale: [1 short sentence]
+
+## Research Context (optional)
+<!-- If .ai-factory/RESEARCH.md exists, copy/paste the Active Summary here -->
+Source: .ai-factory/RESEARCH.md (Active Summary)
+
+Goal:
+Constraints:
+Decisions:
+Open questions:
+
 ## Commit Plan
 <!-- For plans with 5+ tasks, define commit checkpoints -->
 - **Commit 1** (after tasks 1-3): "feat: add base models and types"

package/skills/aif-review/SKILL.md

@@ -3,6 +3,7 @@ name: aif-review
 description: Perform code review on staged changes or a pull request. Checks for bugs, security issues, performance problems, and best practices. Use when user says "review code", "check my code", "review PR", or "is this code okay".
 argument-hint: "[PR number or empty]"
 allowed-tools: Bash(git *) Bash(gh *) Read Glob Grep
+disable-model-invocation: false
 ---
 
 # Code Review Assistant
@@ -23,6 +24,42 @@ Perform thorough code reviews focusing on correctness, security, performance, an
 2. Use `gh pr diff <number>` to get the diff
 3. Review all changes in the PR
 
+## Context Gates (Read-Only)
+
+Before finalizing review findings, run read-only context gates:
+
+- Check `.ai-factory/ARCHITECTURE.md` (if present) for boundary/dependency alignment issues.
+- Check `.ai-factory/RULES.md` (if present) for explicit convention violations.
+- Check `.ai-factory/ROADMAP.md` (if present) for milestone alignment and mention missing linkage for likely `feat`/`fix`/`perf` work.
+
+Gate result severity:
+- `WARN` for non-blocking inconsistencies or missing optional files.
+- `ERROR` only for explicit blocking criteria requested by the user/review policy.
+
+`/aif-review` is read-only for context artifacts by default. Do not modify context files unless user explicitly asks.
+
+### Project Context
+
+**Read `.ai-factory/skill-context/aif-review/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 review
+  summary format and the checklist criteria. If a skill-context rule says "review MUST check X"
+  or "summary MUST include section Y" — you MUST augment the output accordingly. Producing a
+  review 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.
+
 ## Review Checklist
 
 ### Correctness
@@ -70,6 +107,9 @@ Perform thorough code reviews focusing on correctness, security, performance, an
 **Files Reviewed:** [count]
 **Risk Level:** 🟢 Low / 🟡 Medium / 🔴 High
 
+### Context Gates
+[Architecture / Rules / Roadmap gate results with WARN/ERROR labels]
+
 ### Critical Issues
 [Must be fixed before merge]
 

package/skills/aif-roadmap/SKILL.md

@@ -23,6 +23,26 @@ Create and maintain a high-level project roadmap with major milestones.
 - Chosen architecture pattern and folder structure
 - Module boundaries and communication patterns
 
+**Read `.ai-factory/skill-context/aif-roadmap/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 ROADMAP.md
+  template. The template in this SKILL.md is a **base structure**. If a skill-context rule says
+  "roadmap MUST include X" or "milestones MUST have Y" — you MUST augment the template accordingly.
+  Generating a roadmap 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.
+
 ### Step 1: Determine Mode
 
 If argument is `check` → Mode 3: Check Progress (requires ROADMAP.md)
@@ -271,3 +291,4 @@ Next up: **Milestone Name**
 3. **Never remove milestones silently** — always confirm with user before removing
 4. **Completed table tracks history** — every checked milestone gets a date entry
 5. **NO implementation** — this skill only plans, use `/aif-plan` to start a feature and `/aif-implement` to execute
+6. **Ownership boundary** — this command owns roadmap structure/content; `/aif-implement` may only mark milestones completed when implementation evidence is clear

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

@@ -3,6 +3,7 @@ name: aif-security-checklist
 description: Security audit checklist based on OWASP Top 10 and best practices. Covers authentication, injection, XSS, CSRF, secrets management, and more. Use when reviewing security, before deploy, asking "is this secure", "security check", "vulnerability".
 argument-hint: "[auth|injection|xss|csrf|secrets|api|infra|prompt-injection|race-condition|ignore <item>]"
 allowed-tools: Read Glob Grep Write Edit Bash(npm audit) Bash(grep *)
+disable-model-invocation: false
 ---
 
 # Security Checklist
@@ -89,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

@@ -3,6 +3,7 @@ name: aif-skill-generator
 description: Generate professional Agent Skills for AI agents. Creates complete skill packages with SKILL.md, references, scripts, and templates. Use when creating new skills, generating custom slash commands, or building reusable AI capabilities. Validates against Agent Skills specification.
 argument-hint: '[skill-name or "search <query>" or URL(s)]'
 allowed-tools: Read Grep Glob Write Bash(mkdir *) Bash(npx skills *) Bash(python *security-scan*) Bash(rm -rf *) WebFetch WebSearch
+disable-model-invocation: false
 metadata:
   author: skill-generator
   version: "2.1"
@@ -13,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

@@ -6,7 +6,7 @@ description: >-
   Use after "/aif-implement" completes, or when user says "verify", "check work", "did we miss anything".
 argument-hint: "[--strict]"
 allowed-tools: Read Edit Glob Grep Bash(git *) Bash(npm *) Bash(npx *) Bash(yarn *) Bash(pnpm *) Bash(bun *) Bash(go *) Bash(python *) Bash(php *) Bash(composer *) Bash(cargo *) Bash(make *) Bash(task *) Bash(just *) Bash(mage *) TaskList TaskGet AskUserQuestion Questions
-disable-model-invocation: true
+disable-model-invocation: false
 metadata:
   author: AI Factory
   version: "1.0"
@@ -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.