@mrciphersmith/keryx 0.2.97 → 0.2.99

package/src/gdskills/bundled/skills/core/reviewer-skill-creator/SKILL.md

@@ -131,7 +131,7 @@ Three fields, three different jobs, and mixing them is the recorded failure mode
 somewhere else and will move on; without the hash, a reviewer built from last
 month's version reads as current forever, and nobody finds out until its findings
 disagree with the standard it claims to encode. With it,
-`keryx review reviewers` reports `drift: changed` the moment the file differs.
+`keryx review reviewers` prints that reviewer's row as `- <name> (<origin> — changed)` the moment the file differs.
 
 Quote the path if it starts with `~` and you want it stored that way; an
 unquoted `~` is expanded by the shell before keryx sees it. Either is fine —
@@ -192,8 +192,8 @@ keryx review reviewers
 
 The second is the one that matters: it is the same call
 `review-orchestrator` makes, so its output is proof the reviewer will be
-dispatched rather than a hope. Check the row shows your reviewer with
-`drift: clean`.
+dispatched rather than a hope. Check the row reads `- <reviewer-name> (<origin> — clean)` — `changed` means the
+source moved, `missing` that it no longer resolves, `no recorded origin` that the reviewer was created without `--origin`.
 
 Then say, in your reply, which of the three piles from Step 1 you kept, which you
 dropped, and what you could not verify against this project.
@@ -216,8 +216,8 @@ dropped, and what you could not verify against this project.
 
 ## Refreshing a reviewer whose source moved on
 
-`keryx review reviewers` reporting `drift: changed` means the source file differs
-from what was imported. It does **not** mean the reviewer is wrong.
+A row of `- <name> (<origin> — changed)` from `keryx review reviewers` means the
+source file differs from what was imported. It does **not** mean the reviewer is wrong.
 
 Re-read the source, diff it against what the skill encodes, and then decide per
 change: fold it in, or record in the skill why this project deliberately differs.
@@ -241,3 +241,40 @@ undocumented is drift that will be silently "fixed" by whoever refreshes next.
 | Decide which reviewers a round dispatches | NO | `review-orchestrator` |
 | Import a tree of overlay reviewers | YES — `keryx skills import --from <dir> --module review` (`keryx review import` alias) | — |
 | Import a non-review SKILL.md / GitHub URL | NO | `entity-skill-creator` / `keryx skills import` |
+
+---
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|----------------|-----------------|
+| "The source's voice is what makes it a good standard — stripping it loses the edge." | A reviewer distilled from someone's tone reviews tone. Step 4 drops the persona pile whole and keeps the method with its reason beside it; a reason transplants into a codebase the author never saw, and an assertion does not. |
+| "I know where the source file lives, so `--origin` adds nothing." | Without the recorded hash, a reviewer built from last month's version of that file reads as current forever, and nobody finds out until its findings disagree with the standard it claims to encode. `drift: changed` is the whole point. |
+| "The target should say what the reviewer is for, so a sentence is clearer." | The target is a routing key that `keryx skills route` matches queries against. A sentence there produces a skill that matches nothing and verifies as permanently stale. The prose belongs in `--note`. |
+| "The source has a clear severity scale, so I will carry it over." | Ten private rubrics feeding one sorted report produce a ranking that means ten things at once. Point at **Severity (canonical)** and add one table saying where this reviewer's recurring conditions land under it. |
+| "The files are written and the frontmatter is valid, so the reviewer is wired." | Creating files is not registration, and registration is not discovery. Until `keryx review reviewers` prints the name, the orchestrator will never dispatch it. |
+| "The source's conventions are sensible, so they will hold in this project too." | They are true of the source's own codebase until verified here. Keep a convention only after checking it against this project, and say in your reply which ones you could not check. |
+| "The row came back `— changed`, so the reviewer is wrong and I will overwrite it." | It means the source moved, not that the reviewer is wrong. Diff the two and decide per change: fold it in, or write down why this project deliberately differs. An undocumented divergence is drift the next refresh silently "fixes". |
+
+---
+
+## Verification
+
+Report done only once all of these hold:
+
+- `keryx skills verify review/<reviewer-name>` passes.
+- `keryx review reviewers` lists the reviewer as `- <reviewer-name> (<origin> — clean)` — that literal row, not a `drift:` field, which the command never prints. This is the
+  same call `review-orchestrator` makes, so its output — not the presence of the
+  files — is what proves the reviewer will be dispatched.
+- The `SKILL.md` carries all six required parts from Step 3: Scope naming the
+  neighbouring reviewers it excludes, a Checklist of performable checks, a
+  pointer to the canonical severity rubric with no rubric of its own, the three
+  shared laws verbatim, the class-scope contract, and the Orchestrated Review
+  Contract with its own finding-id prefix.
+- `--origin` was passed whenever a source file exists, and the recorded path is
+  the one a human would read later.
+- Any method that only works when a command is run — a mutation, a measurement, a
+  probe — is stated as an iron law, together with what the finding is worth
+  without it.
+- The reply says which of Step 1's three piles were kept, which were dropped, and
+  what could not be verified against this project.

package/src/gdskills/bundled/skills/orchestration/code-verifier/SKILL.md

@@ -1,20 +1,21 @@
 ---
 name: code-verifier
 model_tier: light
-description: "Use when running a full quality gate after implementation — lint, type-check, tests, and import validation. Mandatory step in job-orchestrator after task-implementer and after fix iterations. Use standalone when you need a structured verification report."
+description: "Use when running a full quality gate after implementation — lint, type-check, tests, and import validation. Mandatory step in job-orchestrator after task-implementer and after fix iterations. Use standalone when you need a structured verification report. NOT for: fixing what the gate reports — this skill is read-only (use task-implementer)."
 triggers:
+  - "verify code"
+  - "run checks"
+  - "quality gate"
   - "Run verification"
-  - "Quality gate"
   - "Check code quality"
   - "Run lint and tests"
   - "Verify implementation"
-  - "Run checks"
 metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
-  category: "verification"
+  category: "orchestration"
   agent_worthy: true
-  compatible_harnesses: "cursor,codex,zed,opencode"
+  compatible_harnesses: "cursor,codex,zed,opencode,claude"
 license: "MIT"
 ---
 
@@ -61,56 +62,43 @@ Code Verifier Progress:
 
 ### Phase 1: DETECT
 
-Auto-detect the project stack and available verification tools.
+Determine scope. Stack and tool discovery is delegated to `keryx health run`
+and `keryx test run` — do NOT hand-roll package-manager or
+lint/type-check/test tool detection here.
 
-**1.1 Package manager and runner:**
-
-```bash
-cd <codebase_path>
-
-if   [ -f bun.lock ] || [ -f bun.lockb ]; then PM=bun;    RUNNER="bun run"
-elif [ -f pnpm-lock.yaml ];    then PM=pnpm;   RUNNER="pnpm run"
-elif [ -f yarn.lock ];         then PM=yarn;   RUNNER="yarn"
-elif [ -f package-lock.json ]; then PM=npm;    RUNNER="npm run"
-elif [ -f pyproject.toml ] || [ -f requirements.txt ]; then PM=python; RUNNER=""
-elif [ -f go.mod ];            then PM=go;     RUNNER=""
-else PM=unknown; RUNNER=""
-fi
-```
-
-**1.2 Detect available check commands:**
-
-| Check | How to detect | Command |
-|---|---|---|
-| Lint | `package.json` has `"lint"` script | `$RUNNER lint` |
-| Lint (auto) | `eslint.config.*` or `.eslintrc*` present | `npx eslint . --max-warnings 0` |
-| Biome | `biome.json` present | `npx biome check .` |
-| Type-check | `package.json` has `"type-check"` or `"typecheck"` script | `$RUNNER type-check` |
-| Type-check (auto) | `tsconfig.json` present | `npx tsc --noEmit` |
-| Tests | `package.json` has `"test"` script | `$RUNNER test --run` (vitest) or `$RUNNER test` |
-| pytest | `pytest` in `pyproject.toml` or `requirements.txt` | `pytest --tb=short -q` |
-| Go tests | `go.mod` present | `go test ./...` |
-| Circular imports | `madge` in devDependencies | `npx madge --circular src/` |
-
-**1.3 Determine scope:**
+**1.1 Determine scope:**
 
 ```
 IF scope = "changed" (default when dispatched by orchestrator):
   FILES = git diff --name-only <base_branch>...HEAD
-  Run tests only for files related to changed code
-  Run lint only on changed files: npx eslint <changed_files>
-  Run type-check on full project (tsc doesn't support file-level scope)
+  Pass --changed to keryx health run and keryx test run below.
 
 IF scope = "full":
-  Run all checks on full project
+  Run all checks on the full project (omit --changed).
 ```
 
+**1.2 Checks used:**
+
+| Check | Command |
+|---|---|
+| Lint + type-check | `keryx health run --changed --source eslint,typescript` (drop `--changed` for full scope) |
+| Tests | `keryx test run --changed --strict` (drop `--changed` for full scope) |
+| Circular imports | the project's own package-manager runner + `madge --circular --extensions ts,tsx src/`, if `madge` is a devDependency — optional; not covered by `keryx health run` / `keryx test run` |
+
+`src/health/sources/eslint.ts` and `src/health/sources/typescript.ts` resolve
+the real lint/type-check invocation for the project; `src/testing/service.ts`
+detects `bun` / `pnpm` / `yarn` / `npm` from the lockfile and builds the test
+invocation from the project's own test script. Do NOT hard-code a package
+manager, linter, type-checker, or test binary here — that is the if-chain
+these commands already resolve. On a project with no keryx health/testing
+config, fall back to the project's own configured lint/type-check/test
+command (discovered from its `package.json` scripts or equivalent, not a
+hardcoded tool).
+
 **Output of Phase 1:**
 ```
 TOOLING:
-  pm: bun | pnpm | yarn | npm | python | go | unknown
-  runner: "bun run" | ...
-  checks_available: [lint, type-check, tests, circular-imports]
+  checks_available: [lint+type-check, tests, circular-imports]
   checks_skipped: [<reason>]
   scope: changed | full
   changed_files: [<paths>]
@@ -120,54 +108,44 @@ TOOLING:
 
 ### Phase 2: RUN
 
-Execute each available check in order. Capture full output.
+Execute each available check. Capture full output.
 
-**Execution order:** lint → type-check → tests → import-check
+**Execution order:** lint+type-check → tests → import-check
 
 **Do NOT abort early** — run all checks even if one fails. The orchestrator needs the complete picture.
 
-**2.1 Lint:**
+**2.1 Lint + type-check:**
 ```bash
-# Changed files only (faster, more actionable)
-npx eslint <changed_files> --format=json --max-warnings 0
-# OR if lint script exists:
-$RUNNER lint
+keryx health run --changed --source eslint,typescript
+# OR, full scope:
+keryx health run --source eslint,typescript
 ```
 
-Capture:
-- Exit code (0 = pass, non-zero = fail)
+Read the result with `keryx health status` (or the report path the command
+prints). Capture:
+- Gate status (pass/fail) per source
 - Number of errors and warnings
-- Per-file error list (file path, line, column, rule, message)
+- Per-finding: file, line, column, rule/TS code, message
 
-**2.2 Type-check:**
+**2.2 Tests:**
 ```bash
-npx tsc --noEmit 2>&1
-# OR:
-$RUNNER type-check
+keryx test run --changed --strict
+# OR, full scope:
+keryx test run --strict
 ```
 
 Capture:
-- Exit code
-- Number of errors
-- Per-error: file, line, column, message, TS error code
-
-**2.3 Tests:**
-```bash
-$RUNNER test --run 2>&1        # vitest
-# OR: npx jest --ci 2>&1
-# OR: pytest --tb=short -q 2>&1
-# OR: go test ./... 2>&1
-```
-
-Capture:
-- Exit code
+- Report status / exit code
 - Tests passed / failed / skipped counts
 - Per-failure: test name, file, error message, stack (first 5 lines)
 
-**2.4 Circular import check (if madge available):**
+**2.3 Circular import check (if madge available):**
 ```bash
-npx madge --circular --extensions ts,tsx src/ 2>&1
+<pm> exec madge --circular --extensions ts,tsx src/ 2>&1
 ```
+`<pm>` is the project's own package-manager runner for devDependency
+binaries (`pnpm exec`, `yarn`, or the npm-based equivalent), resolved the
+same way `keryx test run` resolves it from the lockfile — not hardcoded.
 
 Capture:
 - Exit code
@@ -298,7 +276,7 @@ code-verifier:
 code-verifier:
   codebase_path: <worktree_path>
   scope: changed
-→ If gate still FAIL after 2 iterations → report as BLOCKED, skip to report
+→ If gate still FAIL after 3 iterations → report as BLOCKED, skip to report
 → If gate: PASS → proceed to report
 ```
 
@@ -351,3 +329,18 @@ code-verifier:
 3. **Scope to changed files** by default — full scans are slow and produce noise.
 4. **Be specific** in findings — include file, line, rule, message. Vague "lint failed" is not actionable.
 5. Return `VERIFICATION_RESULT` as the **final message** to the orchestrator.
+
+---
+
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "Lint already failed, so running the type-check and tests adds nothing." | Rule 1: run ALL checks. The orchestrator sizes one fix wave from the full picture. Aborting early means it fixes lint, re-dispatches, then discovers the type errors — one wave per check instead of one wave. |
+| "This type error is a one-line fix — faster to correct it than to report it." | Rule 2: this gate is read-only. A verifier that edits has verified its own edit, and the diff the reviewer sees no longer matches what the implementer wrote. Report it; let the fix come back through the loop. |
+| "The lint binary isn't installed, so there is nothing wrong — the gate passes." | A check that did not run is `status: skipped`, never `pass`. `gate: PASS` on an empty check set is a false all-clear, and zero checks available is `STATUS: BLOCKED` by the Error Handling table. |
+| "`gate: FAIL`, so my STATUS must be BLOCKED." | STATUS reports whether THIS SKILL ran, not what it found. A complete report of a failing gate is `STATUS: DONE`. `BLOCKED` tells the orchestrator verification never happened and it must resolve tooling — a different, wrong branch. |
+| "That failing test is unrelated to the diff, so I'll record it as skipped." | `skipped` means it did not run. A failure you judged out of scope is still `failed`, with a finding. Deciding what is in scope is the orchestrator's call, and it cannot make it on a result you rewrote. |
+| "I hit `max_findings_reported`, so the remaining findings can go unmentioned." | The cap limits the list, not the count. Report the true totals in `checks:` and say in `summary` that the finding list is truncated, or the orchestrator plans a fix wave against a number that is quietly too small. |

package/src/gdskills/bundled/skills/orchestration/context-collector/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: context-collector
-description: "Use when a job needs a unified context document — gathering docs, libraries, and references for sub-agents before execution."
+description: "Use when a job needs a unified context document — gathering docs, libraries, and references for sub-agents before execution. NOT for: deciding what to build from that context (use interview, or job-orchestrator for the whole pipeline)."
 triggers:
-  - "Collect context"
-  - "Build context"
-  - "Gather context"
+  - "collect context"
+  - "gather context"
+  - "build context"
   - "Update context"
   - "Refresh context"
   - "Context for job"
@@ -12,9 +12,9 @@ triggers:
 metadata:
   author: "MrCipherSmith"
   version: "1.1.0"
-  category: "context"
+  category: "orchestration"
   agent_worthy: true
-  compatible_harnesses: "cursor,codex,zed,opencode"
+  compatible_harnesses: "cursor,codex,zed,opencode,claude"
 license: "MIT"
 ---
 
@@ -600,7 +600,7 @@ When the orchestrator dispatches this skill as a sub-agent:
 You are the context-collector agent. Your task is to research and build
 a context document for the current job.
 
-Load the skill from: skills/orchestration/context-collector/SKILL.md
+Load the skill from: .metaproject/skills/gdskills/orchestration/context-collector/SKILL.md
 
 ACTION: collect
 JOB_NAME: <job-name>
@@ -622,7 +622,7 @@ For updates:
 You are the context-collector agent. Your task is to update the existing
 context document for this job.
 
-Load the skill from: skills/orchestration/context-collector/SKILL.md
+Load the skill from: .metaproject/skills/gdskills/orchestration/context-collector/SKILL.md
 
 ACTION: update
 JOB_NAME: <job-name>
@@ -653,3 +653,19 @@ Execute update flow and return a CONTEXT_RESULT block.
 10. **DO NOT** fetch external docs for standard well-known patterns already covered by project rules.
 11. **DO NOT** modify any project files — this is a read + research + write-to-jobs skill only.
 12. **DO NOT** skip the metadata block and update log — they are mandatory for version tracking.
+
+---
+
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "More context is safer, so I'll include everything I found." | Rule 9 caps `context.md` at ~500 lines, and 3.4 admits only HIGH and MEDIUM findings. A 1200-line context is read by no sub-agent; the three paragraphs that mattered are now buried, which is the same as not having collected them. |
+| "I know this library well, so I can write the API section from memory." | Phase 3 fetches the docs for the version the project actually pins. A remembered signature is the single most expensive thing in this document: every sub-agent downstream implements against it without checking. |
+| "The task mentions React, so I should fetch React documentation." | Rule 10: no external fetch for well-known patterns already covered by project rules. External research is for the specific API, version gotcha or convention this task turns on — not for a topic overview. |
+| "This section of the existing context looks stale, so I'll drop it while updating." | 4.3 and Rule 4: preserve existing sections unless they are explicitly outdated. "Looks stale" from inside a scoped update usually means "I did not re-research it" — removing it silently deletes a decision another agent is relying on. |
+| "I fixed the small inconsistency I noticed in the source file while reading it." | Rule 11: this skill writes only into the job folder. An edit made during collection lands in a diff nobody attributed to a task, and the implementer inherits it without knowing. |
+| "The context is written, so I can return — job-documenter can be called later." | Phase 5 is part of the skill. A `context.md` that was never persisted through `job-documenter` is absent from the README index, and the next phase resolves the path to nothing. |
+| "The content changed only slightly, so bumping the Version and update log is overkill." | Rule 12 and Rule 3: version, timestamp and update log are mandatory. Without them, two agents reading different revisions have no way to tell which one they have. |

package/src/gdskills/bundled/skills/orchestration/context-collector/orchestrator-prompt.md

@@ -58,7 +58,7 @@ IF ACTION == "update":
 You are the context-collector agent. Your task is to research and build
 a context document for the current job.
 
-Load the skill from: skills/orchestration/context-collector/SKILL.md
+Load the skill from: .metaproject/skills/gdskills/orchestration/context-collector/SKILL.md
 
 DO NOT ask the user any questions. Execute all phases autonomously.
 
@@ -85,7 +85,7 @@ and return a CONTEXT_RESULT block as your final message.
 You are the context-collector agent. Your task is to update the existing
 context document for this job.
 
-Load the skill from: skills/orchestration/context-collector/SKILL.md
+Load the skill from: .metaproject/skills/gdskills/orchestration/context-collector/SKILL.md
 
 DO NOT ask the user any questions. Execute the update flow autonomously.
 

package/src/gdskills/bundled/skills/orchestration/feature-analyzer/SKILL.detail.md

@@ -224,26 +224,16 @@ grep -r "focus_keyword" --include="*.spec.ts" --include="*.test.ts" src/
 
 ### Output for Mode B
 
-Generate **Feature Specification Document** instead of Change Analysis:
-
-```
-<DOCS_ROOT>/analysis/<feature>-current-state-<date>/
-├── README.md
-├── specification/
-│   ├── en/feature-specification.md
-│   ├── ru/feature-specification.md
-│   └── ai/feature-specification.md
-├── architecture/
-│   ├── data-flow.md
-│   ├── component-diagram.md
-│   └── api-contracts.md
-├── usage/
-│   ├── examples.md
-│   └── patterns.md
-└── tests/
-    └── test-coverage.md
+Generate **Feature Specification Document** instead of Change Analysis, using the same flat analysis-category layout as Mode A:
+
+```
+<DOCS_ROOT>/analysis/<feature-name>/
+├── report.md                    # Feature specification: purpose, API contracts, business logic, data flow, architecture, usage examples, test coverage
+└── implementation-plan.md       # Only if formalization surfaces follow-up implementation work
 ```
 
+No date-stamped folder, no `-current-state-<date>` suffix, and no mandatory `en`/`ru`/`ai` split — add language variants only if the user explicitly asks.
+
 ---
 
 ## Timeouts and Limits
@@ -397,7 +387,7 @@ Analyzing only new changes...
       "branch": "feature-name",
       "sha": "abc123",
       "base_sha": "def456",
-      "path": "feature-name-2024-01-15",
+      "path": "feature-name",
       "created_at": "2024-01-15T10:00:00Z",
       "updated_at": "2024-01-15T10:00:00Z",
       "status": "complete",
@@ -526,7 +516,7 @@ git log --oneline "${BASE_SHA}..HEAD"
 
 ## Step 10: Gherkin Output Format (Full)
 
-The AI-readable format in `report/ai/report.md` and `plans/ai/implementation-plan.md` uses Gherkin-style scenarios.
+Gherkin-style scenarios in `report.md` (and its `ai` language variant, when one is generated) make analysis results parseable by other AI agents. The same applies to `implementation-plan.md` for Phase scenarios.
 
 **Purpose**: Enable other AI agents to parse analysis results programmatically.
 
@@ -633,7 +623,7 @@ Feature: [Concise Feature Name]
     And the risk level is "[Low/Medium/High]"
 ```
 
-### 7. Implementation Plan (in plans/ai/)
+### 7. Implementation Plan (in implementation-plan.md)
 ```gherkin
 Feature: Implementation Plan for [Feature Name]
   Background:
@@ -711,7 +701,7 @@ Feature: Implementation Plan for [Feature Name]
 
 ## Step 13: Full Metrics and Complexity Score
 
-Track and report in `metrics/analysis-metrics.md`:
+Track and report in the `## Analysis Metrics` section of `report.md`:
 
 ```markdown
 ## Analysis Metrics

package/src/gdskills/bundled/skills/orchestration/feature-analyzer/SKILL.md

@@ -1,7 +1,10 @@
 ---
 name: feature-analyzer
-description: "Use when analyzing feature branch changes across repos, planning implementation, or understanding backend→frontend contracts. Requires the source repository, target repository, and branch as confirmed input; the skill's PRE-STEP validates them before any analysis."
+description: "Use when analyzing feature branch changes across repos, planning implementation, or understanding backend→frontend contracts. Requires the source repository, target repository, and branch as confirmed input; the skill's PRE-STEP validates them before any analysis. NOT for: breaking an issue into implementable tasks (use issue-analyzer)."
 triggers:
+  - "analyze feature"
+  - "study module"
+  - "investigate branch"
   - "Analyze branch"
   - "Analyze changes"
   - "Analyze commit"
@@ -12,8 +15,8 @@ triggers:
 metadata:
   author: "MrCipherSmith"
   version: "2.4.0"
-  category: "analysis"
-  compatible_harnesses: "cursor,codex,zed,opencode"
+  category: "orchestration"
+  compatible_harnesses: "cursor,codex,zed,opencode,claude"
 license: "MIT"
 ---
 
@@ -275,7 +278,7 @@ When focus specified: boost files matching focus keywords to P0; select ALL focu
 1. **Dependency search**: find all target files importing changed DTOs/APIs from source
 2. **Contract divergence**: compare new source contracts with current target implementation
 3. **Target deep dive**: read 2-3 key components that will need changes
-4. **Target rules compliance**: check `.cursor/rules/core/*.mdc` in target repo
+4. **Target rules compliance**: check `.metaproject/rules/core/*.mdc` in target repo
 
 ---
 
@@ -333,24 +336,14 @@ Wait for user confirmation before generating full report.
 ### Output Structure
 
 ```
-<DOCS_ROOT>/analysis/<feature-name>-<YYYY-MM-DD>/
-├── README.md                    # Index and navigation
-├── report/
-│   ├── en/report.md             # English for humans
-│   ├── ru/report.md             # Russian for humans
-│   └── ai/report.md             # Structured for AI agents (EN)
-├── plans/
-│   ├── en/implementation-plan.md
-│   ├── ru/implementation-plan.md
-│   └── ai/implementation-plan.md
-├── contracts/
-│   ├── api-changes.md           # API contract diff
-│   └── dto-comparison.md        # Before/after DTOs
-└── metrics/
-    └── analysis-metrics.md      # Analysis metadata
+<DOCS_ROOT>/analysis/<feature-name>/
+├── report.md                    # Findings, API contract diff, DTO comparison, cross-repo impact, analysis metrics
+└── implementation-plan.md       # Actionable implementation plan derived from the analysis
 ```
 
-The AI-readable format (`report/ai/`, `plans/ai/`) uses Gherkin-style scenarios.
+No date-stamped folder: update `report.md`/`implementation-plan.md` in place for a rerun on the same feature rather than creating a parallel copy. Default output is a single English (`en`) pair. Add other language variants only if the user explicitly asks for them, and keep any variants you create synchronized.
+
+`report.md` should use Gherkin-style scenarios where they make findings easier for other AI agents to parse.
 > For full Gherkin output format and syntax rules, see `SKILL.detail.md`.
 
 ---
@@ -360,7 +353,7 @@ The AI-readable format (`report/ai/`, `plans/ai/`) uses Gherkin-style scenarios.
 - Every claim MUST reference specific code: `[filename.ts:L123](file:///absolute/path#L123)`
 - Minimum 3 code examples per report
 - Mermaid diagrams for architecture, tables for DTO changes, flowcharts for data flow
-- Multi-language: `en/` for humans, `ru/` for humans, `ai/` for AI agents
+- Default to a single `en` document; add `ru`/`ai` (or other) variants only when the user explicitly asks, keeping them synchronized
 
 ---
 
@@ -378,7 +371,7 @@ The AI-readable format (`report/ai/`, `plans/ai/`) uses Gherkin-style scenarios.
 
 ## Step 13: Analysis Metrics
 
-Track and include in `metrics/analysis-metrics.md`:
+Track and include in the `## Analysis Metrics` section of `report.md`:
 - Duration, files analyzed (P0/P1/P2), lines changed
 - Cross-repo dependencies, API endpoints changed, DTOs modified
 - Breaking changes count, test coverage %, risk level
@@ -415,19 +408,39 @@ Follow `documentation-management.mdc`: update `<DOCS_ROOT>/readme.md`, add entry
 4. **Never assume** — ask user when unclear
 5. **Never skip** intermediate review for complex analyses (P0 files > 3)
 6. **Always provide** concrete, actionable recommendations
-7. **Always include** both human-readable and AI-readable formats
+7. **Always default** to a single-language document (`en`); add other language variants only when the user explicitly asks
 
 ---
 
-## Success Criteria
+## Red Flags
+
+Stop and re-read this skill if you are thinking:
+
+| Rationalization | Rebuttal |
+|---|---|
+| "The user named a branch, so I have enough to start." | The PRE-STEP needs source repo, target repo and branch, each confirmed. A branch without its repo pair is how a cross-repo analysis quietly becomes source-only and reports no frontend impact because it never looked at the frontend. |
+| "`git diff` came back empty, so the branch changed nothing." | Step 12 names the three usual causes: the wrong BASE_SHA, changes that are staged or untracked, and the wrong branch checked out. Report "no changes" only after `--cached`, `git status` and the branching point all agree. |
+| "I read the diff hunks, so I understand the change." | A hunk shows the lines that moved, not the contract they belong to. The Deep Dive Protocol reads P0 files whole because the breaking part of a change is usually the caller the diff never touched. |
+| "The finding is clear from the code I just read — the line reference can wait." | Step 11 makes a `file:L123` citation mandatory for every claim. An uncited claim cannot be checked by the developer acting on it, and a report of uncited claims is indistinguishable from a plausible guess. |
+| "There are 6 P0 files but the picture is obvious, so I'll skip the intermediate review." | Rule 5 forbids skipping it above 3 P0 files. The intermediate review is the only point where the user can correct the scope before a full report is written against the wrong one. |
+| "An analysis for this feature already exists, so I'll write mine into a new folder." | Step 10 requires updating `report.md` and `implementation-plan.md` in place. Parallel copies mean the next reader picks one, and nothing marks which is current. |
+| "GitHub MCP is unavailable, so issue and PR context is out of reach." | Step 12's fallback is git history plus a notice to the user — not silence. An analysis that drops the issue context without saying so reads as if the issue held nothing relevant. |
+
+---
+
+## Exit Criteria
+
+Do not report the analysis as complete until all of these hold:
 
-Analysis is successful when:
-- Business logic is fully understood and documented
-- API contracts are clearly specified
-- Breaking changes are identified
-- Implementation plan is actionable
-- User confirms understanding via intermediate review
-- All P0 files analyzed completely
+- The PRE-STEP inputs (source repo + branch, target repo + branch, mode) were confirmed by the user, not inferred — and the report states them.
+- Mode A: `BASE_SHA` is recorded in the report. Mode B: the report says explicitly that it describes current state, not a diff.
+- Every P0 file was read in full and appears in the analysed-files list; the P0/P1/P2 counts in `## Analysis Metrics` match that list.
+- `report.md` contains at least 3 code examples, and every claim carries a `file:line` reference.
+- API contracts and breaking changes each have a section — a "none found" is written out with what was checked to reach it.
+- `implementation-plan.md` exists and every step names a file or module to touch; no step reads "investigate".
+- `## Analysis Metrics` includes the computed complexity score and its inputs.
+- The user answered the intermediate review prompt (mandatory whenever P0 files > 3), and any correction they made is reflected in the final report.
+- Step 15 post-analysis is done: `<DOCS_ROOT>/readme.md` and the analysis index name this analysis.
 
 ---
 

package/src/gdskills/bundled/skills/orchestration/feature-analyzer/analysis-request.md

@@ -57,6 +57,6 @@
 | Field | Value |
 |-------|-------|
 | Base Dir | `.metaproject/jobs/<job-name>/ai/analysis` |
-| Folder Name | `async-search-current-state` |
-| Languages | `en, ru, ai` |
+| Folder Name | `async-search` |
+| Languages | `en` |
 | Include Metrics | `true` |

package/src/gdskills/bundled/skills/orchestration/feature-analyzer/analysis-request.template.md

@@ -75,5 +75,5 @@
 |-------|-------|
 | Base Dir | `<DOCS_ROOT>/analysis` |
 | Folder Name | |
-| Languages | `en, ru, ai` |
+| Languages | `en` |
 | Include Metrics | `true` |

package/src/gdskills/bundled/skills/orchestration/feature-analyzer/input-contract.schema.json

@@ -225,7 +225,7 @@
         },
         "folder_name": {
           "type": "string",
-          "description": "Custom folder name. Defaults to <feature>-<date> for Mode A, <feature>-current-state-<date> for Mode B"
+          "description": "Custom folder name. Defaults to <feature-name> (no date suffix) for both Mode A and Mode B"
         },
         "languages": {
           "type": "array",
@@ -233,13 +233,13 @@
             "type": "string",
             "enum": ["en", "ru", "ai"]
           },
-          "default": ["en", "ru", "ai"],
-          "description": "Which report languages to generate. ai = Gherkin format for AI agents"
+          "default": ["en"],
+          "description": "Which report languages to generate. Defaults to a single 'en' document; add 'ru'/'ai' only when the user explicitly asks for them. ai = Gherkin format for AI agents"
         },
         "include_metrics": {
           "type": "boolean",
           "default": true,
-          "description": "Include analysis-metrics.md in output"
+          "description": "Include an Analysis Metrics section in report.md"
         }
       }
     }

package/src/gdskills/bundled/skills/orchestration/feature-analyzer/orchestrator-prompt.md

@@ -19,7 +19,7 @@
                     ↓
   [Субагент]     → выполняет SKILL.md feature-analyzer автономно
                     ↓
-  [Результат]    → docs/analysis/<feature>-<date>/
+  [Результат]    → docs/analysis/<feature>/
 -->
 
 ## Инструкция для оркестратора
@@ -211,7 +211,7 @@ TICKET REFERENCE:
 
 Base directory: {{output.base_dir | default("<DOCS_ROOT>/analysis")}}
 Folder name:    {{output.folder_name | default("auto-generated per SKILL.md rules")}}
-Languages:      {{output.languages | default("en, ru, ai")}}
+Languages:      {{output.languages | default("en")}}
 Include metrics: {{output.include_metrics | default("true")}}
 
 ═══════════════════════════════════════════════