npm - testeiya - Versions diffs - 0.8.1 → 0.9.0 - Mend

testeiya 0.8.1 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/README.md CHANGED Viewed

@@ -23,6 +23,7 @@ its own browser, and syncs with your Testomat.io project.
 | OS | Download |
 |---|---|
 | macOS (Apple Silicon) | [`stable-macos-arm64-Testeiya.dmg`](https://github.com/testomatio/testeiya-app/releases/latest/download/stable-macos-arm64-Testeiya.dmg) |
+| macOS (Intel) | [`stable-macos-x64-Testeiya.dmg`](https://github.com/testomatio/testeiya-app/releases/latest/download/stable-macos-x64-Testeiya.dmg) |
 | Windows (x64) | [`stable-win-x64-Testeiya.zip`](https://github.com/testomatio/testeiya-app/releases/latest/download/stable-win-x64-Testeiya.zip) |
 | Linux (x64) | [`Testeiya-x86_64.AppImage`](https://github.com/testomatio/testeiya-app/releases/latest/download/Testeiya-x86_64.AppImage) |

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "testeiya",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "AI testing agent — QA-focused coding agent for manual and automated tests",
   "type": "module",
   "license": "MIT",

package/skills/codeceptjs/lint-codeceptjs-tests/SKILL.md ADDED Viewed

@@ -0,0 +1,104 @@
+---
+name: lint-codeceptjs-tests
+description: >
+  Use when a CodeceptJS 4 suite needs a static quality gate — before committing
+  tests, reviewing a PR that touches tests, hardening CI, or on direct asks:
+  "lint the tests", "find I.wait / setTimeout sleeps", "leftover .only or
+  pause()", "missing await on grab", "passwords printed in logs", "why are
+  tests slow/flaky". Runs `@codeceptjs/lint` — an AST-based linter that needs
+  no CodeceptJS install and no browser.
+---
+# Lint CodeceptJS 4 Tests
+`@codeceptjs/lint` reads tests, page objects and helpers as an AST and reports the smells that make suites slow, flaky or leaky — fixed sleeps, `if` branching, raw `fetch`, missing `await` on grabbers, plain-text credentials, leftover `.only`/`pause()`. One finding per line; exit codes `0` / `1` (errors found) / `2` (bad input, unparsable file) drop straight into CI.
+## Commands
+```bash
+npx @codeceptjs/lint                          # files from codecept.conf.js in cwd
+npx @codeceptjs/lint tests/ pages/login.js    # explicit paths (no config needed)
+npx @codeceptjs/lint -r no-pause -r no-only   # only these rules (or --rules a,b)
+npx @codeceptjs/lint rules                    # list rules + defaults
+npx @codeceptjs/lint --json                   # file, line, column, rule, level, message, source
+npx @codeceptjs/lint -c e2e/codecept.conf.js  # config in another directory
+```
+Without paths it reads `codecept.conf.js|ts|cjs|mjs` and lints everything matched by `tests`, local `include` files (page objects, steps file) and helpers loaded via `require`. TypeScript is parsed with Node's type stripping (Node 22.13+); `enum`/`namespace` report as parse errors. A TS config importing `./x.js` for an `x.ts` file (tsx convention) loads when the project has `tsx` installed.
+## Rules and the fix for each
+| Rule | Default | Detects → fix |
+|---|---|---|
+| `no-fixed-wait` | error | `I.wait(5)` → `I.waitForElement` / `I.waitForText` / `I.see` |
+| `no-sleep` | error | bare and `window.`/`globalThis.` `setTimeout`, incl. `await new Promise(r => setTimeout(r, ms))` and `timers/promises`, outside helpers → condition wait |
+| `no-if-in-test` | error | `if` inside a Scenario/hook → `tryTo()` from `codeceptjs/effects` |
+| `no-fetch` | error | `fetch()` (incl. `window.fetch`, `globalThis.fetch`) outside helpers → REST helper `I.sendGetRequest` / `I.sendPostRequest` |
+| `no-console` | warn | `console.*` outside helpers → `I.say()` (lands in the report) |
+| `no-only` | error on CI, warn locally | `Scenario.only`, `Feature.only`, `Data(...).only` → remove before commit |
+| `no-pause` | error on CI, warn locally | `pause()`, `this.pause()` → remove before commit |
+| `no-skip` | warn | `Scenario.skip`, `Feature.skip`, `xScenario`, `xFeature` → intentional? suppress with a comment explaining why |
+| `secret-credentials` | error | credential-ish `process.env.X` / `process.env['X']` or a password/token/secret/api-key locator passed to `I.*` → wrap with `secret()` |
+| `await-grab` | error | `I.grab*()` assigned, destructured or passed without `await` (`await Promise.all([...])` and `.then()` chains are fine) → add `await` |
+| `no-actor-in-helper` | error | `I` inside a class extending `Helper` → `this.helpers['Name']` |
+| `raw-browser-in-test` | warn | `I.use*To`, `I.executeScript` in a Scenario → move into a helper or page object |
+"On CI" = the `CI` env var is set — local debugging stubs (`pause()`, `.only`) stay warnings so they don't fail the lint while investigating.
+## Configuring per project
+Levels live in the config, next to the tests they govern:
+```js
+export const config = {
+  tests: './*_test.js',
+  lint: {
+    rules: { 'no-if-in-test': 'warn', 'raw-browser-in-test': 'off' },
+  },
+}
+```
+Levels: `error`, `warn`, `off`. For a single deliberate case, suppress inline — rule id required, never disable a rule project-wide for one line:
+```js
+I.wait(1) // codeceptjs-lint-disable-line no-fixed-wait
+```
+## Workflow
+1. Run `npx @codeceptjs/lint` at the project root; if no config loads (secrets, tsx-less TS config), pass paths explicitly.
+2. Fix errors first (they fail CI), warnings by judgment. Triage by cost: sleeps and missing `await` are the flakiness drivers; `secret()` fixes are one-line.
+3. For bulk cleanup, feed `--json` output to drive file-by-file edits — the `source` field holds the offending line (truncated to 120 chars).
+4. Add the gate so it stays clean:
+```yaml
+# CI, before codeceptjs run
+- run: npx @codeceptjs/lint
+```
+For agent-driven work, a Claude Code `PreToolUse` hook blocks edits that *add* a new error (pre-existing errors and warnings never block; a failing hook allows the edit):
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      { "matcher": "Write|Edit|MultiEdit", "hooks": [{ "type": "command", "command": "npx @codeceptjs/lint --hook claude" }] }
+    ]
+  }
+}
+```
+## Things to avoid
+- "Fixing" `await-grab` by deleting the `await` usage — the grab result is a promise, the fix is `await`, not removal.
+- Replacing `I.wait` with a longer `I.wait`.
+- Suppressing `no-if-in-test` when the branch is load-bearing — that's `tryTo()` or a helper's job.
+- Adding the CI step before triaging existing findings — the suite goes red on day one.
+- Skipping the hook's config scope check — it only lints files the config covers.
+## Related skills
+- `debugging-codeceptjs-tests` — `I.wait(N)` as a timing probe is fine mid-debug, lint-clean it before committing
+- `refactoring-codeceptjs-tests` — bulk cleanup of a lint-red suite (extract helpers, tame locators)
+- `writing-codeceptjs-tests` — write clean tests from the start
+- `ci-fix-tests` — run the lint gate first so CI fixes don't reintroduce smells

package/skills/skills.lock.json CHANGED Viewed

@@ -3,12 +3,14 @@
     {
       "source": "testomatio/skills",
       "ref": null,
-      "sha": "050ece13c42d3bc0f0020336aabebe21fe62cb41",
+      "sha": "e1cf03227adfcb553c94ea5ee08c0eebc397e875",
       "folder": "testomatio",
       "skills": [
         "automate-manual-test-cases",
+        "catalog-features",
         "debug-fix-failed-flaky-autotests",
         "detect-duplicate-test-cases",
+        "detect-product-mismatches",
         "detect-useless-tests",
         "epic-requirements-specification",
         "explorbot-fundamentals",
@@ -46,7 +48,7 @@
     {
       "source": "codeceptjs/skills",
       "ref": null,
-      "sha": "d3d6a4e0e29207b1afb051eeb6f5f36984f4752b",
+      "sha": "c9a82e3e237c908ba53ec47d2c841c680b88e03a",
       "folder": "codeceptjs",
       "skills": [
         "ci-fix-tests",
@@ -55,6 +57,7 @@
         "codeceptjs-fundamentals",
         "codeceptjs-run-analysis",
         "debugging-codeceptjs-tests",
+        "lint-codeceptjs-tests",
         "migrate-codeceptjs-4",
         "migrate-cypress-to-codeceptjs",
         "migrate-protractor-to-codeceptjs",

package/skills/testomatio/qa-process/testing-workflow/SKILL.md CHANGED Viewed

@@ -17,7 +17,9 @@ Orchestrates the test case lifecycle by routing requests to specialized skills a
 | `qa-thinking`                        | Analyze a feature as QA — edge cases, negative flows, abuses, risk scenarios      |
 | `qa-split-testing-levels-pyramid`    | Apply the test pyramid — assign scenarios to testing levels, coverage split       |
 | `write-user-story`                    | Write user stories and acceptance criteria (the requirements)                     |
-| `wiki-from-code`                      | Build or refresh a product wiki from implemented code (implicit requirements)     |
+| `wiki-from-code`                     | Build a whole-product wiki from code, or update it after large changes            |
+| `catalog-features`                   | Catalog features of one source: code, issue tracker, requirements, user docs      |
+| `detect-product-mismatches`          | Compare code, issues, requirements, user docs with each other — mismatches        |
 | `qa-requirement-reviewer`            | Review requirements for ambiguity, gaps, and testability                          |
 | `qa-write-test-cases`                | Generate new test cases and checklists from requirements                          |
 | `improve-test-cases`                 | Improve existing test cases quality                                               |
@@ -38,7 +40,9 @@ Orchestrates the test case lifecycle by routing requests to specialized skills a
 - Flows are examples, not exhaustive. Combine or extend them when a request spans several tasks.
 - When suggesting next steps, take into account the flows, context, user request, and results of previous steps.
 - **Write / draft user stories** (requirements, spec, acceptance criteria) → route to the `write-user-story` skill. Review of existing requirements → `qa-requirement-reviewer`.
-- **Wiki / spec from code** (build or refresh wiki, implicit requirements, as-implemented docs) → route to the `wiki-from-code` skill.
+- **Wiki / spec from code** (build or update the whole-product wiki, actual behavior, implicit requirements) → route to the `wiki-from-code` skill.
+- **Catalog features of a source** (codebase, Jira, Confluence, Notion, user docs, etc.; import or sync into the wiki) → route to the `catalog-features` skill.
+- **Compare sources** (code, issues, requirements, user docs: not implemented, differs, unspecified, undocumented) → route to the `detect-product-mismatches` skill.
 - **Behavior questions** ("what happens when…", "can a user…", "is X supported") ask what the product does rather than for an artifact → route to the `qa-explain-behavior` skill first, then continue with the flow the answer points to.
 - **Strategic intent** ("where do I start", "improve our QA process", "QA maturity review") → route to the `qa-lead-strategy-advisor` skill instead. It owns the high-level roadmap and delegates execution back here.
@@ -47,14 +51,15 @@ Orchestrates the test case lifecycle by routing requests to specialized skills a
 ### Wiki from Code Flow
 ```
-User: asks to build/refresh a wiki, requirements, or spec from the codebase
+User: asks to build/update a wiki, requirements, or spec from the codebase
 =>
-Use `wiki-from-code` skill to bootstrap or refresh `wiki/` from implemented code
+Use `wiki-from-code` skill to build or update `wiki/` from implemented code
 =>
 After the wiki is written, suggest next actions:
-1. 🧠 Risk scenarios from a capability (with `qa-thinking` skill)
-2. 📝 Test cases from a capability (with `qa-write-test-cases` skill)
-3. 📘 User stories from a capability (with `write-user-story` skill)
+1. 🔍 Cross-check with issues, requirements, user docs (with `detect-product-mismatches` skill)
+2. 🧠 Risk scenarios from a feature (with `qa-thinking` skill)
+3. 📝 Test cases from a feature (with `qa-write-test-cases` skill)
+4. 📘 User stories from a feature (with `write-user-story` skill)
 ```
 ### Test Generation Flow

package/skills/testomatio/requirements/catalog-features/SKILL.md ADDED Viewed

@@ -0,0 +1,132 @@
+---
+name: catalog-features
+description: >-
+  Builds a catalog of product features from one source: a tree that mirrors the source, each feature as a key, title, and link to the source. Code, issues, requirements, docs, etc. are supported.
+  Use when asked to catalog/list features, existing functionality, issues, requirements, specs, PRDs, user docs or similar sources.
+metadata:
+  author: Testomat.io
+  version: 1.0.0
+---
+# Catalog features
+Catalog of **the source's features**: a tree that mirrors the source, each feature with its key, title, and link. Its behaviors (description, requirements, acceptance criteria, etc.) stay at the source.
+Output folder: given by the calling skill or the user. Default: `features/.catalog/`. Write only inside it.
+## Modes
+`build` from scratch; `update` from an existing catalog. When `update`, use info from the catalog README.
+## Source roles
+| Role       | Description                                                 |
+| ---------- | ----------------------------------------------------------- |
+| Actual     | Actual behavior of the product. Code, configs, etc.         |
+| Intended   | What we attempted to implement. Requirements, tickets, etc. |
+| Documented | What the product says it does. User docs, etc.              |
+## Rules
+- **Read-only on the source.** Do NOT edit the source even when the tools offer it.
+- One catalog per source.
+## Sources
+### Code
+- Tree: areas → features, named from what the product does for its users, not from the stack or code folders, classes, files, or functions.
+- Feature: one per feature, not per file; same feature in two places → one feature. Link: repo paths of the main implementation (route, screen, job), not every file.
+- Scope: features users can reach now. Not stubs, routes users cannot reach, or features behind disabled flags; comments, docs, and tests do not make a feature.
+- `update`: `git diff --name-status -M {baseline}..HEAD`; take into account renamed, moved, deleted files.
+- Role: Actual.
+- History: No.
+### Issue tracker
+- Tree: the tracker's hierarchy: initiatives, epics, parent issues, issues, sub-tasks, etc.
+- Scope: a query (JQL, `gh` search, Linear filter, etc.); ask the user for it and store it. "Done" issues only (typical successfully resolved statuses); ask the user when in doubt.
+- Role: Intended.
+- History: Yes (unless user specified). Because different issues may be related to the same feature. Need to store date of creation and resolution to determine which issue overrides the other.
+### Requirements
+- Word, PDF: extract the text first.
+- Tree: area by heading or other logical structure.
+- Scope: ask user for the scope and other crucial filters. Take into account that there could be drafts, deprecated pages, copies. Process them accordingly.
+- Role: Intended.
+- History: No.
+### User docs
+- Tree: keep the original structure with required hierarchy levels.
+- Role: Documented.
+- Scope: ask user.
+- History: No.
+### Other
+Any source that describes the product. Agree on role, coverage, history with the user before syncing.
+## Steps
+```
+- [ ] 1. Source and domain
+- [ ] 2. Inventory
+- [ ] 3. Write the tree
+- [ ] 4. Validate
+- [ ] 5. Report
+```
+Read [references/layout.md](references/layout.md) before writing files.
+## 1. Source and domain
+Ask the user in one message, unless given:
+- Type and access: repository, MCP, CLI, URL, export, or file path. No access → stop and ask for an MCP connection or an export.
+- Scope as a concrete, repeatable filter: repo paths, tracker query (JQL, project, label), root page or space, docs root.
+- Domain: what the product does and for whom, key terms. Not given → infer it from the source.
+Name area and features in the domain terms.
+Several sources in one run → one output folder each; define all of them first, then run steps 2–4 per source.
+## 2. Inventory
+List every feature in scope with key or URL, title, status. Navigate all the pages.
+When `update`: take into account renamed, moved, deleted files. Process them accordingly.
+If source is code create areas and features based on features and logic, not just files, classes, functions.
+## 3. Write the tree
+Catalog README and area READMEs, as [references/layout.md](references/layout.md) describes.
+## 4. Validate
+```markdown
+Structure
+- [ ] Catalog README has every fact and the counts; indexes every area
+- [ ] Every area README lists its subareas and features; the tree mirrors the source
+Content
+- [ ] Every feature yml is according to the `references/layout.md`
+- [ ] Code: areas and features named from the product, not the stack
+- [ ] Update: features gone from scope removed
+- [ ] Only existing keys and urls are used in the catalog
+```
+## 5. Report
+Where to start. Features synced, skipped by reason.
+To a calling skill: features added, changed, and removed.
+## Next actions
+- `detect-product-mismatches`
+- Feature pages from the code → `wiki-from-code`
+- `qa-requirement-reviewer`
+- Test cases from requirements → `qa-write-test-cases`

package/skills/testomatio/requirements/catalog-features/references/layout.md ADDED Viewed

@@ -0,0 +1,43 @@
+# Catalog layout
+The tree mirrors how the source groups its content: code areas, epics, page tree, docs nav.
+```
+features/.catalog/           # output folder
+  README.md                  # source facts, counts, areas, ungrouped features
+  {area}/                    # code area, epic, parent page, nav section; any depth
+    README.md                # the area's own link/path, subarea if any, its features
+    {feature}.yaml           # feature page
+    {subarea}/               # subarea (optional)
+      README.md              # the subarea own link/path, name, its features; breadcrumbs
+      {feature}.yaml         # feature page; breadcrumbs; feature info (below)
+    ...
+```
+## Formatting
+Every `.md` should include info about its entity and child entities list (if any). Relative links between catalog pages.
+README.md in catalog root:
+| Fact    | Value                                                                                                 |
+| ------- | ----------------------------------------------------------------------------------------------------- |
+| Type    | Code, issue tracker, requirements, user docs or any other                                             |
+| Role    | Actual, Intended, or Documented (SKILL.md › Source roles)                                             |
+| Scope   | Defined by user (or inferred)                                                                         |
+| History | Important for sources like issue tracker                                                              |
+| Access  | MCP, CLI, URL, files                                                                                  |
+| Date    | Date of this sync; code: baseline commit and its date; issue tracker: date of creation and resolution |
+| Domain  | What the product does and for whom; infer if not given                                                |
+## Feature YAML
+Name: {feature-name}.yaml
+Feature YAML should include:
+- Key [optional]. Do not invent. Use only if the source provides it.
+- Title: short description of the feature.
+- Links/headings: link(s) to sources that describe the feature (url, repo path, etc.); headings in case source is a document.
+No description, requirements or other details.

package/skills/testomatio/requirements/detect-product-mismatches/SKILL.md ADDED Viewed

@@ -0,0 +1,146 @@
+---
+name: detect-product-mismatches
+description: >-
+  Compares what different sources say the product does: code (actual behavior), issue tracker and requirements (intended behavior), user docs (documented behavior), and any other source (test cases, release notes etc.).
+  Checks every feature in every source and records mismatches: contradictions and differences, not implemented, unspecified, undocumented.
+  Use when the user asks to compare, cross-check, align, validate requirements, specs, wiki, tickets, issues, user docs, or code, codebase against each other, to find mismatches, contradictions, differences, or outdated docs or requirements, or to find what is not implemented, not documented, or not specified.
+metadata:
+  author: Testomat.io
+  version: 1.0.0
+---
+# Detect product mismatches
+Checks each feature in every source and records where the sources disagree.
+Output folder:
+  - given by calling skill or the user
+  - all paths are relative inside the output folder
+  - default: `mismatches/`
+> `wiki/mismatches/` is the output of `wiki-from-code`: mismatches inside a single source, the code. Don't use it as the output folder and don't use its results.
+## Modes
+`build` (from scratch) or `update` (for changes since the last check).
+## Sources
+Type, role, scope, and history of each source come from its catalog README (`catalog-features` › Source roles, Sources).
+| Source        | Role                  |
+| ------------- | --------------------- |
+| Code          | Actual                |
+| Requirements  | Intended              |
+| Issue tracker | Intended              |
+| User docs     | Documented            |
+| Other         | As its catalog README |
+Per feature, what each source says is rewritten as behaviors in one shape ([features.md](references/features.md) › Behaviors), so sources compare line by line:
+- Two sources say different things about the same behavior → Differs.
+- Another source has a behavior the code lacks → Not implemented. Code is the product: it must do what the other sources say.
+- Several intended sources: a feature is specified when any of them has it.
+- `History: Yes` (issue tracker by default): the newest issue wins (resolution date, else creation date); older contradicting issues are superseded, not mismatches.
+**Not a mismatch:**
+- Same behavior in other words.
+- **Silence on a detail.** A coarser source agrees with a finer one unless it contradicts it (`Customer can save a card.` agrees with `Customer can save up to 5 cards.`).
+- A behavior only the code has, inside a feature the other sources have.
+- Superseded issues; behaviors of another version; content outside a catalog Scope (open issues, drafts, deprecated pages).
+- Can't tell (vague behavior, unreadable content) → open question.
+## Likely cause
+From dates read at the source: issue resolution date (else creation date), page last version, docs "last updated" (else `git log -1 --format=%cs -- {path}`); code: `git log -1 --format=%cs -- {paths}` for the feature's code paths. The same dates decide the newest issue for `History: Yes`.
+- Code differs from the newest intended behavior, and nothing newer explains it → Bug.
+- Requirement older than the issue or code change that set the current behavior → Stale requirement.
+- User docs older than that change → Stale docs.
+- Otherwise → Decide (product owner).
+## Steps
+```
+- [ ] 1. Sources and access
+- [ ] 2. Catalogs: create missing, update stale
+- [ ] 3. Check each feature (one subagent each)
+- [ ] 4. Verify (subagents)
+- [ ] 5. Merge
+- [ ] 6. Validate
+- [ ] 7. Report
+```
+Read [references/features.md](references/features.md) and [references/layout.md](references/layout.md) before writing files.
+## Rules
+- **Read-only on sources.** Never edit issues, pages, or code.
+- Catalogs and `features/` change only by running their skills.
+- **Report, don't decide.** A mismatch page shows what each source says; its Solution only suggests a fix.
+- Compare behaviors, not wording: different values, conditions, roles, labels, or flows differ.
+- Write only paths, keys, and URLs that exist in the catalogs, the sources, or the repo. Do not invent them.
+## 1. Sources and access
+1. List the sources to compare: given by the user, else ask; offer the ones already cataloged.
+2. Check access: one real read per source (MCP tool, `gh`, git, URL, file). No access → stop and ask for an MCP connection or an export. A catalog alone is not enough: behaviors are read at the source.
+## 2. Catalogs
+Every listed source needs a catalog. Create the missing ones, update the stale ones, before any check:
+Use `catalog-features` skill to build the catalogs for each source. Use `wiki-from-code` also if **code is the source**.
+## 3. Check each feature
+Features: every feature from catalogs in this order: code, requirements, user docs, issue tracker, other.
+One subagent per feature, in parallel. Each gets: the feature (its feature YAML), the compared sources (name, type, role, scope, history, access, catalog path), the version, the Domain from the catalog READMEs, the source table and rules above, [references/features.md](references/features.md), [references/layout.md](references/layout.md).
+Subagent:
+1. Per source: finds the feature in the catalog, else searches the source ([features.md](references/features.md) › Find).
+2. Reads every matching feature at its links and states its behaviors ([features.md](references/features.md) › Read, Behaviors).
+3. Aligns the same behavior across sources.
+4. Returns one mismatch per disagreement: its kind (Differs or Not implemented) and every section of a mismatch page ([layout.md](references/layout.md) › Page), with code evidence as `path:lines`.
+Subagent writes nothing. Returns: matched catalog features per source (or `not found` + where searched), mismatches, sources silent on the whole feature, open questions, catalog errors.
+## 4. Verify
+One fresh subagent per batch of mismatches, with the same inputs as step 3. It re-reads each mismatch at its Links and returns it as confirmed, corrected, or dropped (with why). Can't confirm → open question.
+## 5. Merge
+1. Write the confirmed mismatch pages ([layout.md](references/layout.md) › Page). Same disagreement from several features → one mismatch page, every disagreeing source on it.
+2. `update`: remove resolved mismatches.
+3. In `mismatches/README.md`, write the mismatches list ([layout.md](references/layout.md) › README).
+4. New `sources/` or `mismatches/` → add a link and purpose for it to the root `README.md`.
+## 6. Validate
+```markdown
+Structure
+- [ ] Every feature of the compared catalogs was checked, or listed as an open question
+- [ ] Mismatches list states compared sources (catalog Date or baseline), version, check date; indexes every page and missing feature
+Content
+- [ ] Each page has every section of [layout.md](references/layout.md) › Page and one row per compared source; silent sources marked silent with where searched
+- [ ] Difference opens with a one-sentence summary; each bullet is clear alone: sources, condition, what the user gets; the title doesn't say which side is right
+- [ ] Every page was confirmed in Verify; nothing from Not a mismatch is a page
+- [ ] Every behavior on the pages passes the check in [references/features.md](references/features.md)
+- [ ] update: resolved pages removed
+```
+## 7. Report
+Where to start. Mismatches by highest user impact first. Missing features per source. Catalog errors (→ `catalog-features`; code catalog with `features/` → `wiki-from-code`). Open questions.
+## Next actions
+- Update a catalog → `catalog-features`; feature pages from code → `wiki-from-code`
+- User stories for not-implemented behavior → `write-user-story`
+- Review contradicting requirements → `qa-requirement-reviewer`
+- Test cases for differing behavior → `qa-write-test-cases`

package/skills/testomatio/requirements/detect-product-mismatches/references/features.md ADDED Viewed

@@ -0,0 +1,84 @@
+# Features
+A feature is something the product does for its users that they would name: "Pay with saved card", "Export report to CSV". In a catalog, one feature YAML is one feature of its source, in the area where the source puts it. Another source may name it differently or split it differently: e.g. one epic covers three code features, one docs page covers two.
+A feature is made of behaviors: what someone who uses it (end user, admin, API client, integrated system) can do, see, or get, and when. Sources are compared behavior by behavior, so every source's behaviors are written the same way.
+Behavior is similar to requirement or acceptance criteria, but those terms describe intended behavior; code gives actual behavior, user docs documented behavior (`catalog-features` › Source roles). "Behavior" fits every role: implemented, planned, or documented.
+## Find
+Per source:
+1. Catalog: key, title, the area it sits in. Links in the feature YAML to other sources help.
+2. Not in the catalog → search the source, within the catalog's Scope:
+| Source        | Search                                                                                 |
+| ------------- | -------------------------------------------------------------------------------------- |
+| Code          | Domain terms, UI labels, messages, routes; start next to related features' code        |
+| Issue tracker | Text search inside the catalog's Scope query (JQL `text ~ "term"`, `gh search issues`) |
+| Requirements  | Search under the root page or space (CQL `text ~ "term"`); headings of long documents  |
+| User docs     | Docs site search or nav; `grep` in the docs repo                                       |
+| Other         | The source's own search                                                                |
+- Found at the source, missing from the catalog → use it and report a catalog error.
+- Found, but outside the catalog's Scope (open issue, draft, deprecated page or copy, other version) → not a behavior. Mention it on the mismatch page when it explains one.
+- Not found → the source is silent on the feature. Record where you searched.
+## Read
+Read every matching feature at its links (documents: under its headings). Behaviors come from:
+| Source        | Behaviors from                                                                                                                                              | Not behaviors                                                                                                                                     |
+| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Code          | The code at the feature's `code` paths (else its links); Behaviors on its feature page in `features/`, when present, as a start                             | Claims (comments, docstrings, developer docs, API specs, configs, tests); stubs, routes users cannot reach; internal steps with no visible effect |
+| Issue tracker | Stories and feature issues: acceptance criteria, then the description. Epics: their scope. Bugs: the expected result                                        | A bug's reported actual result; tasks, spikes, chores, tech debt                                                                                  |
+| Requirements  | Functional requirements, business rules, acceptance criteria, flows; one behavior per table row and per meaningful matrix cell; exclusions as negative ones | Future phases, nice-to-have, MoSCoW Could and Won't; goals, rationale, personas, metrics, open questions                                          |
+| User docs     | Guides, how-tos, limits, notes and warnings; badges (plan, edition, role, platform) as conditions; navigation steps                                         | Screenshots and videos                                                                                                                            |
+| Test cases    | Expected results                                                                                                                                            | Steps, test data                                                                                                                                  |
+- Code behind a flag or setting that can be turned on → a behavior with that condition (as `wiki-from-code`).
+- Comments and later edits may change the body ("dropped", "moved to PROJ-456", "decided: 3 retries, not 5"): state the final behavior, never the comment.
+- Acceptance criteria may sit in a custom field, a description heading, a checklist, or sub-tasks: find the convention in the first issues.
+## Behaviors
+### Shape
+- One behavior per line, one sentence, present tense.
+- No `should`, `shall`, `must`, `will`: state it as a fact. The source's role says whether it is actual, intended, or documented.
+- Name who acts or what changes, in domain terms. Never "the system", "it", or "we".
+- Outcome is what the actor can observe (screen, response, file, email, notification), not how the product gets there.
+- Conditions stay in the behavior: role, platform, setting, state.
+- Source key, when the behavior has one, goes first.
+- Negative behaviors count: `Viewer cannot delete a project.`
+- Split on "and" when each part can be checked on its own.
+### Values and words
+- Values as the source states them, with units. No value in the source → none in the behavior. Never round, convert, or fill one in; a vague behavior stays vague (open question).
+- Code: exact values from the code that runs; a value read from config or environment: its default, marked `(configurable)` (as `wiki-from-code`).
+- UI labels and messages verbatim, in quotes; navigation paths with `›`.
+- Domain terms (prefer the user docs' terms), one per concept across sources and `features/`.
+- No class, function, table, file, flag, or library names. Protocol details (endpoints, status codes, fields) only when the API is what users use.
+- Keep the source's level of detail: a coarse behavior stays coarse. Never merge behaviors and drop values or conditions.
+- Restate, never paste. Never people, comments, or customer data.
+## Examples
+| Source says                                                           | Behavior                                                            |
+| --------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| The system shall allow users to store payment methods (max 5).        | `Customer can save up to 5 cards.`                                  |
+| Users can save cards to pay faster.                                   | `Customer can save a card.` (benefit dropped)                       |
+| AC: if the card is declined, show "Payment failed. Try another card." | `Declined card: Customer sees "Payment failed. Try another card."`  |
+| Enterprise customers get SSO; Pro is coming soon.                     | `Enterprise plan: SSO sign-in is available.` (Pro: future, dropped) |
+| Session times out after a while.                                      | `Session expires after inactivity.` (no value invented)             |
+| Bug: saving the same card twice creates a duplicate; expected: one.   | `Saving the same card again keeps one saved card.`                  |
+## Check
+- [ ] Every source either has the feature or records where it was searched
+- [ ] One observable behavior per line, present tense, who or what named
+- [ ] Values, labels, and conditions exactly as in the source; none added
+- [ ] Domain terms, the same term for the same thing
+- [ ] No implementation, plans, rationale, work items, people, or copied text

package/skills/testomatio/requirements/detect-product-mismatches/references/layout.md ADDED Viewed

@@ -0,0 +1,93 @@
+# Mismatches layout
+Reads catalogs (layout owned by `catalog-features`) and feature pages (owned by `wiki-from-code`); changes them only through those skills (SKILL.md › 2. Catalogs). Writes mismatch pages into `mismatches/`
+```
+mismatches/                  # output folder
+  README.md                  # sitemap; one line each
+  sources/
+    README.md                # every catalog here: name, type, role, link, Date
+    {name}/                  # source name
+      features/              # feature pages (wiki-from-code), when present
+        .catalog/            # internal: `catalog-features` skill output
+  mismatches/
+    README.md                # index
+    {mismatch}.md            # one mismatch per disagreement, every compared source
+```
+## Formatting
+Every page: `# Title`, then a breadcrumb that matches folders (links to the parent pages only), then the body. Mismatch pages: no breadcrumb. Relative links to pages in the output folder and to repo paths; source features as key + URL.
+## Kinds
+| Kind                | Meaning                                                                      | Where       |
+| ------------------- | ---------------------------------------------------------------------------- | ----------- |
+| Differs             | Sources disagree on one behavior: values, conditions, roles, labels, flow    | Page        |
+| Not implemented     | Behavior from another source that the code lacks                             | Page        |
+| Missing in {source} | Feature a source is silent on, within its catalog Scope (SKILL.md › Sources) | README list |
+## README
+`mismatches/README.md` missing → create it: `# Mismatches`, breadcrumb. Write the mismatches list.
+1. Compared: one row per source: name, role, scope, history, catalog link, Date (code: baseline commit). Product version. Check date.
+2. Differs, Not implemented: one list per kind, highest impact first: page link + impact level + sources + likely cause.
+3. Missing features: one list per silent source (Not implemented, Unspecified, Undocumented, Missing in {source}): feature + where found (catalog feature links) + where searched.
+4. Open questions: vague behaviors, unread content, or unclear Scope that blocks a comparison.
+## Page
+A reader learns what disagrees from the first lines, without opening the sources.
+File name: follow existing file name pattern or kebab-case of the title by default.
+- `# Title`: the behavior in question, as the user meets it.
+- `Feature:` the feature area › title; link to its feature page in `features/`, when present.
+- `## Difference`: first a one-sentence summary of how they differ, then one bullet per side, code first when compared; sources that agree grouped on one bullet. Each bullet: the sources (key or name), then their behavior. Write each side so it is clear alone: the condition, then what the user gets. Not implemented: the code bullet says what is missing and where it was searched.
+- `## Impact`: level first: **High** (users blocked, data or money wrong), **Medium** (a workaround exists), **Low** (wording, cosmetic). Then who meets it, when, and what they see or cannot do.
+- `## Likely cause`: SKILL.md › Likely cause, with the dates that decide it.
+- `## Solution`: suggested fix, from the likely cause: Bug → change the code; Stale requirement → update the requirement; Stale docs → update the docs; Decide → the options for the product owner.
+- `## Sources`: evidence, one row per compared source; Code row always, first, when code is compared.
+- Other info required to explain the mismatch.
+### Example
+```markdown
+# Expired cards at checkout
+Feature: [Checkout › Pay with saved card](../sources/code/features/checkout/pay-with-saved-card.md)
+## Difference
+The code lists expired saved cards at checkout, greyed out; Confluence says they are not listed.
+- **Code, PAY-112:** Expired saved cards are listed at checkout, greyed out and not selectable.
+- **Confluence "Saved cards":** Expired saved cards are not listed at checkout.
+## Impact
+Low. A customer with an expired card sees it greyed out at checkout. Support answers based on Confluence say it should not appear.
+## Likely cause
+Stale requirement: PAY-112 (2026-08-28) changed the behavior after the Confluence page (2026-01-10).
+## Solution
+Update the Confluence page "Saved cards": expired saved cards are listed at checkout, greyed out and not selectable.
+## Sources
+| Source                 | Says                                                  | Link                                             | Updated    |
+| ---------------------- | ----------------------------------------------------- | ------------------------------------------------ | ---------- |
+| Code (actual)          | Expired saved cards are listed, greyed out            | `src/checkout/cards.ts:48-61`                    | 2026-08-30 |
+| Jira (intended)        | PAY-112: Expired saved cards are listed, not selectable | [PAY-112](https://example.atlassian.net/...)   | 2026-08-28 |
+| Confluence (intended)  | Expired saved cards are not listed                    | [Saved cards](https://example.atlassian.net/...) | 2026-01-10 |
+| User docs (documented) | silent                                                | Searched: docs/payments/, site search "expired"  |            |
+```
+- `Says`: the source's behavior, as [features.md](features.md) › Behaviors describes; `silent` when it has none.
+- `Link`: repo file: `path:lines`; issue: key + URL; page: title + URL, with the heading when the page is long; silent: where searched.
+- `Updated`: the date read at the source (SKILL.md › Likely cause).
+- Superseded issues of a source with history: omit, or mark `superseded by {key}` when it explains the mismatch.

package/skills/testomatio/requirements/wiki-from-code/SKILL.md CHANGED Viewed

@@ -1,124 +1,111 @@
 ---
 name: wiki-from-code
 description: >-
-  Builds and refreshes a product wiki from the application source code (implicit requirements).
-  Optionally attaches issue-tracker task/issue/story links.
-  Use when the user asks to build or refresh the wiki/requirements/specification/docs from code, or to catalog existing functionality.
+  Builds a product wiki from the application source code or updates it after large code changes (release, refactor, many merged PRs).
+  Records mismatches between code and claims about it (comments, docstrings, developer docs, API specs, configs).
+  Use when the user asks to build or update the wiki/requirements/specification/docs from code.
 metadata:
   author: Testomat.io
-  version: 1.0.0
+  version: 2.0.0
 ---
 # Wiki from code
-Wiki of **how the product works now**. Bootstrap from code. Refresh when the code changes.
+Wiki of **how the product works now**: one page per feature, listing its behaviors, and mismatches between the code and other repo claims.
-We call this "wiki" as the closest term to what we are building. But user may ask for "requirements" or "specification" or "docs" or something similar.
+Output folder:
+  - default: `wiki/` (in the repo root)
+  - or given by calling skill or the user
+  - all paths are relative inside the output folder
+  - if there is `features-catalog/` dir → move it to `features/.catalog/`
-**Implicit** requirements means inferred from code. **Explicit** requirements means from issues/tasks/docs etc.
-Decide audience once:
-| Audience | Human wiki |
-| --- | --- |
-| End users (default, preferred) | Behavior and acceptance only. No file paths, types, stack, or protocol internals. |
-| Callers who are not end users (API, job, contract etc.) | Technical entry could be treated as requirements. |
+**Mismatch** is a disagreement between code and a claim about it (comment, docstring, developer docs, API spec, config, infra, test). They could differ, be not implemented, not used, etc.
 ## Modes
-Pick one. If unclear, **bootstrap** when `wiki/` is missing, else **refresh**.
-| Mode | When |
-| --- | --- |
-| `bootstrap` | First wiki from this repo |
-| `refresh` | Code moved; update implicit pages + catalog |
-Default root: `wiki/` (or the user’s path).
-Move from **overview** to **details**. Do not write feature pages before the tree exists.
+| Mode     | When                                                                                    |
+| -------- | --------------------------------------------------------------------------------------- |
+| `build`  | No `features/` or baseline in the root `README.md`, no git, or the user asks to rebuild |
+| `update` | `features/` and baseline exist: change only what the code changed since the baseline    |
 ## Steps
 ```
-- [ ] 1. Catalog (shallow)
-- [ ] 2. Tracker links? (ask; optional)
-- [ ] 3. Overview tree (indexes)
-- [ ] 4. Dive each area (one subagent each)
+- [ ] 1. Catalog
+- [ ] 2. Indexes
+- [ ] 3. Feature pages (one subagent per area)
+- [ ] 4. Merge
 - [ ] 5. Validate
 - [ ] 6. Report
 ```
-Read [references/layout.md](references/layout.md) before writing files.
+Read [references/behaviors.md](references/behaviors.md) and [references/layout.md](references/layout.md) before writing files.
 ## Rules
-- Current-state code wins any other source (e.g. docs, tests, config, infra, comments, issues etc). Intended, but not implemented (or implemented differently) behavior goes in `mismatches/` only — never a SHOULD heading on a feature page.
-- Name areas and features from the **product** and user perspective, not the stack or code.
-- Capabilities describe *what the product does*. Catalog records *where that lives in the repo*.
-- Pair capabilities and catalog items (use relative path) (`capabilities/{area}/{feature}.md` ↔ `catalog/{area}/{feature}.yaml`). Feature page: after breadcrumb, relative link to the YAML.
-- Tracker links (tasks, issues, stories, etc.) are optional. **Ask** before adding any. Put them in catalog YAML (`issues`), not on feature pages. Do not invent keys or URLs.
-## 1. Catalog (shallow)
-The **catalog** is what exists in the product: first a shallow area → feature list, then YAML facts in `catalog/`. Code, test, doc, and issue tracker links live here (`sources`, `tests`, `wiki_path`, `issues`).
-From **code** map the product into **areas**, each with a **feature list**. That list *is* the catalog of what exists in the product at this step. Do not draft Requirement/Acceptance or YAML yet.
+- Source is the repository only.
+- **Current-state code wins** over claims (comments, docstrings, developer docs, API specs, configs, tests, etc.). What they claim that the code lacks or does differently goes in `mismatches/` only, never as a "should" on a feature page.
+- Write only paths that exist in the repo. Never guess or build them.
+- Name areas and features from the product and user's perspective, NOT from the code/stack/files/classes/etc.
+- Domain terms (prefer the docs' terms), one term per concept across the wiki.
+- Update catalog file names and content as you get more info about the features.
+- Treat and describe features as end-to-end flows or use cases, not just "actions" from code.
-If an area is large, group features into sub-folders at this step. Catalog YAML uses the same relative path as the feature page.
+## 1. Catalog
-## 2. Tracker links (optional)
+Run `catalog-features` skill on the repo, same mode, output folder `features/.catalog/`.
-**Ask the user** whether to attach issue-tracker links (tasks, issues, stories, etc.) to catalog YAML.
+`update`: get the baseline commit > `git diff --name-status -M {baseline}..HEAD` > process updated/removed files accordingly.
-If none of MCP / user-supplied links work: skip with reason. Do not write placeholder tickets.
+## 2. Indexes
-Write only into catalog YAML (`issues`). Omit the `issues` key when a feature has no match.
+Write the `features/` indexes before any feature page.
-## 3. Overview tree
+[layout.md](references/layout.md)
-Write only the indexes first ([references/layout.md](references/layout.md)). Give the tree hierarchy when the product is complex enough. If names are ambiguous, **stop and show the list** before diving.
+## 3. Feature pages
-Shared rules live on one page; others link.
+One subagent per area, in parallel (`update`: affected areas only). Each subagent gets: the area, its subareas and catalog features (feature YAMLs), allowed code paths, the Domain from `features/.catalog/README.md`, the rules above, [references/behaviors.md](references/behaviors.md), [references/layout.md](references/layout.md). `update` also: the area's existing pages and mismatches, and its changed features.
-## 4. Dive each area
+Subagent, per feature, starting from its catalog links:
-For each feature: catalog YAML first (`catalog/{area}/{feature}.yaml`), then the feature page (Requirement / Acceptance). Stubs, unused wiring, and doc-vs-code gaps go in `mismatches/` with all required source links (layout).
+1. In its catalog feature YAML: adds implementation files to `code`, and adds `tests`.
+2. Writes the feature page ([layout.md](references/layout.md) › Feature page): Description, then Behaviors ([behaviors.md](references/behaviors.md)).
+3. Returns one mismatch per disagreement: its kind and every section of a mismatch page ([layout.md](references/layout.md) › Mismatches).
-Use `subagent` per area/feature to keep the main agent focused on the helicopter view, subagents focused on the details of one area/feature.
+Subagent writes only inside its area, in `features/` and `features/.catalog/`. Catalog features found missing, misnamed, or misplaced → fix them in the area's catalog files. Anything outside the area (mismatch pages, catalog README, other areas) → return it.
-Each subagent gets: area/feature name, allowed paths, audience, [references/layout.md](references/layout.md), "code wins", and whether tracker `issues` are in scope (matched links to write, or omit). Feature pages are Requirement / Acceptance only. Do not rewrite sibling areas except to add the one index line the parent asked for.
+Subagent returns: files added, changed, and removed; mismatches (`update`: also resolved ones); changes outside its area; open questions; catalog errors; terms the Domain lacks.
-Subagent returns: files written, mismatches, open questions. Parent merges links and sitemap; then validates.
+## 4. Merge
-Exception: a one-line fix on an existing page already in context — no subagent spawn.
+1. Apply the changes subagents returned outside their areas, including links to renamed or moved pages. Terms the Domain lacks → add to the Domain in `features/.catalog/README.md`.
+2. Update every `README.md` in `features/` to list the feature pages that now exist. Write the root `README.md`: a link and purpose for each folder (not `.catalog/`), plus the baseline commit.
+3. Write the mismatch pages subagents returned. Same disagreement from several areas → one mismatch page.
+4. Two terms for one concept → keep one, fix the pages that use the other.
+5. `update`: remove resolved mismatches.
+6. In `mismatches/README.md`, write the mismatches list ([layout.md](references/layout.md) › Mismatches).
 ## 5. Validate
 ```markdown
 Structure
-- [ ] wiki/README.md is a sitemap; every listed link exists
-- [ ] catalog YAML exists for every feature; every wiki_path exists
-- [ ] catalog/README.md indexes every area; each area catalog README lists its YAML
-- [ ] Area (and group) folders named from the product, not from stack/code
-- [ ] Feature pages use the layout heading order (Requirement, Acceptance); breadcrumbs match folder depth; links are relative
-- [ ] Feature pages link to the paired catalog YAML (relative path)
-- [ ] Feature pages are not mega-dumps (one cluster per page)
-- [ ] Feature pages not overloaded with meta info (it is located in catalog YAML)
-- [ ] Tracker links are in catalog YAML (`issues`); omitted when declined or none matched; no invented keys/URLs
+- [ ] README.md is a sitemap with the baseline commit
+- [ ] Every catalog feature has a feature page, and its feature YAML lists the rest of its implementation files in `code` and its tests in `tests`; `features/` mirrors the catalog's areas and subareas
+- [ ] Every `links`, `code`, and `tests` path exists in the repo
 Content
-- [ ] Features described from the user perspective, not the stack/code
-- [ ] Catalog is YAML facts, not a second spec
-- [ ] Current-state Requirement matches code
-- [ ] mismatches/ covers disagreements (between code and other sources)
+- [ ] Every feature page has a Description and at least one behavior under Behaviors; every behavior passes the check in [references/behaviors.md](references/behaviors.md)
+- [ ] Every disagreement between code and claims has a mismatch page
+- [ ] update: resolved mismatches removed; nothing left for deleted code
 ```
 ## 6. Report
-Where to start from. Results. Mismatches. Huge projects: those three only.
+Where to start. Results (`update`: features added, changed, removed). Mismatches by kind, highest user impact first. Catalog errors. Open questions.
 ## Next actions
-- Explain a capability in QA language → `qa-explain-behavior`
-- Risk scenarios for a capability → `qa-thinking`
-- Test cases for capability/feature → `qa-write-test-cases`
+- Compare with issues, requirements, user docs → `detect-product-mismatches`
+- Explain a feature in QA language → `qa-explain-behavior`
+- Test cases for a feature → `qa-write-test-cases`

package/skills/testomatio/requirements/wiki-from-code/references/behaviors.md ADDED Viewed

@@ -0,0 +1,42 @@
+# Behaviors
+A behavior is one observable statement about how the product works now: what someone who uses it (end user, admin, API client, integrated system) can do, see, or get, and when. Feature pages list them under Behaviors.
+## From code
+- Code that runs now and users can reach. Behind a flag or setting that can be turned on → a behavior with that condition.
+- Comments, docstrings, developer docs, API specs, configs, and tests are claims, not behaviors. Where they disagree with the code → `mismatches/`.
+- Never a behavior: internal steps with no visible effect (caching, logging, internal retries), refactoring, helpers.
+## Shape
+- One behavior per bullet, one sentence, present tense.
+- No `should`, `shall`, `must`, `will`: state it as a fact, present tense.
+- Name who acts or what changes, in domain terms. Never "the system", "it", or "we".
+- Outcome is what the actor can observe (screen, response, file, email, notification), not how the code gets there.
+- Conditions stay in the behavior: role, platform, setting, state.
+- Negative behaviors count: `Viewer cannot delete a project.`
+- Split on "and" when each part can be checked on its own.
+## Values and words
+- Exact values from the code that runs: limits, defaults, timeouts, sizes, formats.
+- A value read from config or environment: its default, marked `(configurable)`.
+- UI labels and messages verbatim, in quotes; navigation paths with `›`.
+- No class, function, table, file, flag, or library names. Protocol details (endpoints, status codes, fields) only when the API is what users use.
+## Examples
+| Code                                                | Behavior                                                     |
+| --------------------------------------------------- | ------------------------------------------------------------ |
+| `if (cards.length >= 5) throw new CardLimitError()` | `Customer can save up to 5 cards.`                           |
+| `IDLE_TIMEOUT = env.IDLE_TIMEOUT ?? 1800` (seconds) | `Session expires after 30 min of inactivity (configurable).` |
+| `cache.set(user_id, cards)`                         | Not a behavior: no visible effect                            |
+## Check
+- [ ] Every reachable behavior in the feature's code is listed
+- [ ] One observable behavior per bullet, present tense, who or what named
+- [ ] Exact values from the code; config values marked `(configurable)`
+- [ ] Domain terms; no stack names unless the API is what users use
+- [ ] No internal steps; nothing taken from comments, docs, or tests

package/skills/testomatio/requirements/wiki-from-code/references/layout.md CHANGED Viewed

@@ -1,94 +1,93 @@
 # Wiki layout
-Product-agnostic. Name `{area}` / `{feature}` (and any extra group folders) from **what the product does**, not from the stack. Follow naming rules according to code/language used (kebab-case by default). Same relative path in `capabilities/` and `catalog/`.
+`features/` mirrors `features/.catalog/`: same areas and subareas, one feature page per catalog feature. Every folder has a README. Tree may be updated while the wiki is built.
-Default tree is multiple levels under `capabilities/`. Add sub-folders (with required depth) when the project is complex enough that an area needs a named group. Each with a README.
 ```
-wiki/
-  README.md                        # front door → roots
-  capabilities/                    # Wiki > Capabilities
-    README.md                      # areas index
-    {area}/                        # Wiki > Capabilities > {Area}
-      README.md                    # features index
-      {feature}.md                 # Wiki > … > {Feature}  — leaf
-      {group}/                     # optional extra nesting
-        README.md
-        {feature}.md
-  catalog/                         # Wiki > Catalog  — list of functionalities
-    README.md                      # areas index
-    {area}/
-      README.md                    # YAML index
-      {feature}.yaml
-      {group}/
-        README.md
-        {feature}.yaml
-  mismatches/                      # optional — create when a disagreement exists
-    README.md
+{output}/                    # output folder
+  README.md                  # sitemap, baseline commit
+  features/
+    README.md                # areas
+    .catalog/                # internal: code catalog (catalog-features)
+    {area}/                  # any depth, as in the catalog
+      README.md              # subareas and features
+      {feature}.md           # feature page
+      {subarea}/             # as in the catalog
+        README.md            # subareas and features
+        {feature}.md         # feature page
+  mismatches/                # code vs claims in the repo
+    README.md                # index
+    {mismatch}.md            # one behavior, every source that disagrees
 ```
-Create `mismatches/` when code disagrees with comments, infra, docs, issues etc.
+## Feature page
-## Rules
+- Breadcrumb that matches folders.
+- Feature description.
+- `## Behaviors`: [behaviors.md](behaviors.md).
-| Rule | Do |
-| --- | --- |
-| Default | `capabilities/{area}/{feature}.md` |
-| Extra depth | New group folder when the area (or group) is too crowded or a cluster needs a name. Any depth. |
-| Split | New sibling `{feature}.md`, a new group folder, or a new `{area}/`. |
-| Share | One page owns a shared rule; others link. Same behavior, two entries → one page. |
-| Growth | New behavior → new leaf + catalog entry + one new index line. Do not thicken an existing leaf into a mega-page. |
-| Overview first | Indexes exist before any leaf is written. |
+## Catalog feature YAML
-## Formatting
+- No key (cause does not exist in code).
+- `links` become `code` paths.
-Every page: `# Title`, then a breadcrumb that matches folders, then the body. Omit empty sections. Relative links only.
+```yaml
+# features/.catalog/checkout/pay-with-saved-card.yaml
+title: Pay with saved card      # catalog-feature
+code:                           # implementation files
+  - src/api/cards.ts
+tests:                          # tests that cover the feature
+  - test/checkout/cards.spec.ts
+```
-**Index** (any `README.md`): title + breadcrumb + a bullet list. No Requirement or Acceptance.
+## Mismatches
-| File | Body |
-| --- | --- |
-| `wiki/README.md` | Roots (`capabilities/`, `catalog/`, `changes/` / `mismatches/` (if present)) |
-| `capabilities/README.md` | Every area: link + purpose (markdown indexes only — not catalog YAML) |
-| `capabilities/{area}/README.md` | Every child feature (or group): link + purpose |
-| Extra group `README.md` | Every child feature (or deeper group): link + purpose |
-| `catalog/README.md` | Every area: link to that area’s catalog README |
-| `catalog/{area}/README.md` | Every child YAML: link + purpose (YAML indexes only — not feature pages) |
+`mismatches/README.md` missing → create it: `# Mismatches`, breadcrumb. Write the list of mismatches, grouped by kind (not implemented, differs, unwired/not used, etc.), highest impact first: page link + impact level.
-**Leaf** (`{feature}.md`): headings in this order only — Requirement, Acceptance. After the breadcrumb, a relative link to the paired catalog YAML. Intended-but-unwired behavior is not a feature heading — it goes in `mismatches/` only. Code and tracker references live in catalog YAML (`sources`, `tests`, `issues`), never on the feature page.
+### Mismatch page
-## Catalog YAML
+A reader learns what disagrees from the first lines, without opening the sources.
-```yaml
-wiki_path: capabilities/{area}/{feature}.md
-entry:
-  - POST /api/v1/orders
-  - UI /checkout
-  - Job SettlePayments
-sources:
-  - path/to/code
-tests:
-  - TestOrSpecFile
-issues:                    # optional; omit the key when none
-  - key: PROJ-123
-    url: https://example.com/browse/PROJ-123
-behaviors:
-  - One as-implemented fact (observable outcome).
-```
+File name: follow existing file name pattern or kebab-case of the title by default.
+- `# Title`: the behavior in question, as the user meets it.
+- `Feature:` the feature area › title, linked to its feature page.
+- `## Difference`: first a one-sentence summary of how they differ, then one bullet for the code, first, then one per claim; claims that agree grouped on one bullet. Each bullet: the source, then its behavior. Write each side so it is clear alone: the condition, then what the user gets.
+- `## Impact`: level first: **High** (users blocked, data or money wrong), **Medium** (a workaround exists), **Low** (wording, cosmetic). Then who meets it, when, and what they see or cannot do.
+- `## Solution`: suggested fix: change the code, or correct the claim.
+- `## Sources`: evidence, one row per source; Code row always, first. Code, Comment, Docstring, README, Developer docs, API spec, Config, Infra, Test, etc.
+- Other info required to explain the mismatch.
+#### Example
-`entry` is whatever a human would use to *find* the behavior. Catalog is **implicit** current state. One YAML per feature. If the feature sits in extra folders, the YAML uses the same folders.
+```markdown
+# Upload retries after a network error
-`wiki_path` is the pointer from catalog to the feature page. `sources` is the implementation (and product docs that describe it). `issues` is optional tracker links (tasks, issues, stories). `url` is required on each item; `key` when the tracker has a display key. Ask before adding. Omit `issues` when the user declined or nothing matched.
+Feature: [Reports › Upload results](../features/reports/upload-results.md)
-Repo paths (implementation, tests, docs) and tracker links are written only in catalog YAML.
+## Difference
-## Mismatch page
+The code retries a failed upload 3 times; the docstring and developer docs say 5.
-Create `mismatches/` when code disagrees with comments, infra, docs, issues/tasks. Index: `mismatches/README.md`.
+- **Code:** A failed upload is retried 3 times, then the run shows "Upload failed".
+- **Docstring, developer docs:** A failed upload is retried 5 times.
-Every mismatch must link every source that justifies it (omit none that exist):
+## Impact
+Low. On a flaky network, "Upload failed" shows after 3 attempts, sooner than a developer reading the docs expects.
+## Solution
+Correct the docstring and developer docs: 3 retries.
+## Sources
+| Source         | Says                         | Link                        | Updated    |
+| -------------- | ---------------------------- | --------------------------- | ---------- |
+| Code (actual)  | Retries 3 times, then fails  | `src/upload/client.ts:40-52` | 2026-09-02 |
+| Docstring      | "Retries up to 5 times"      | `src/upload/client.ts:31`    | 2026-03-11 |
+| Developer docs | "5 retries before giving up" | `docs/upload.md:18`          | 2026-03-11 |
+```
-| Link | What to point at |
-| --- | --- |
-| Implemented | Always — current behavior based on code |
-| Intended | Always — the non-wiki source that disagrees with those files (comment, doc, infra, issue, unused config, or stub) |
+- `Link`: repo file: `path:lines`; outside the repo: URL, with the heading when the page is long.
+- `Updated`: repo file: date the cited line last changed (`git blame --date=short -L {line},+1 -- {path}`), doc section without a line: the section's last change; URL: the page's "last updated" date, else empty.