@mrciphersmith/keryx 0.2.97 → 0.2.99

package/dist/core.js

@@ -3225,6 +3225,39 @@ function countDigits(value) {
 function containsCalendarDate(value) {
   return CALENDAR_DATE.test(value);
 }
+function enclosingToken(content, start, end) {
+  let from = start;
+  const floor = Math.max(0, start - TOKEN_SCAN_LIMIT);
+  while (from > floor && IDENTIFIER_CHAR.test(content[from - 1])) {
+    from -= 1;
+  }
+  let to = end;
+  const ceiling = Math.min(content.length, end + TOKEN_SCAN_LIMIT);
+  while (to < ceiling && IDENTIFIER_CHAR.test(content[to])) {
+    to += 1;
+  }
+  const truncated = from === floor && from > 0 && IDENTIFIER_CHAR.test(content[from - 1]) || to === ceiling && to < content.length && IDENTIFIER_CHAR.test(content[to]);
+  return { text: content.slice(from, to), truncated };
+}
+function isHexIdentifierRun(segment) {
+  return segment.length >= 8 && /^[0-9A-Fa-f]+$/.test(segment) && /[A-Fa-f]/.test(segment);
+}
+function isIdentifierFragment(content, matchStart, matchEnd) {
+  const { text: token, truncated } = enclosingToken(content, matchStart, matchEnd);
+  if (truncated) {
+    return false;
+  }
+  if (token.length === matchEnd - matchStart) {
+    return false;
+  }
+  if (UUID_TOKEN.test(token)) {
+    return true;
+  }
+  const match = content.slice(matchStart, matchEnd);
+  const before = token.slice(0, token.indexOf(match));
+  const after = token.slice(token.indexOf(match) + match.length);
+  return [...before.split(/[-_]/), ...after.split(/[-_]/)].some(isHexIdentifierRun);
+}
 function hasPhoneSeparatorShape(value) {
   if (/\s{2,}/.test(value)) {
     return false;
@@ -3262,6 +3295,9 @@ function detectPii(content) {
         if (containsCalendarDate(value)) {
           continue;
         }
+        if (isIdentifierFragment(content, m.index, m.index + m[0].length)) {
+          continue;
+        }
       }
       if (rule.validate && !rule.validate(value)) {
         continue;
@@ -3285,7 +3321,7 @@ function detectPii(content) {
   }
   return matches;
 }
-var RULES, CALENDAR_DATE;
+var RULES, CALENDAR_DATE, IDENTIFIER_CHAR, TOKEN_SCAN_LIMIT = 64, UUID_TOKEN;
 var init_pii = __esm(() => {
   RULES = [
     {
@@ -3352,6 +3388,8 @@ var init_pii = __esm(() => {
     }
   ];
   CALENDAR_DATE = /(?:19|20)\d{2}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])/;
+  IDENTIFIER_CHAR = /[0-9A-Za-z_-]/;
+  UUID_TOKEN = /^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$/;
 });
 
 // src/security/detect/secrets.ts
@@ -23978,7 +24016,7 @@ ${filesToRead}
 
 ## Verification
 
-- Current state: not verified.
+- Verification status: see \`verification.md\` (written by \`keryx skills verify\`).
 - Run: \`keryx skills verify ${moduleName}/${skillName}\`
 `;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.2.97",
+  "version": "0.2.99",
   "description": "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
   "private": false,
   "publishConfig": {

package/src/gdskills/bundled/rules/core/api-contracts.mdc

@@ -1,6 +1,7 @@
 ---
 description: "API contract rules: OpenAPI-first design, semantic versioning, no breaking changes without major version bump, contract testing. Use when designing, modifying, or consuming HTTP APIs."
 alwaysApply: false
+stack_requires: "http-server"
 ---
 
 # API Contracts

package/src/gdskills/bundled/rules/core/cli-interface-design.mdc

@@ -0,0 +1,237 @@
+---
+description: "CLI surface rules: what an exit code means (0 clean, 1 found something, 2 cannot tell), machine-readable output on stdout and diagnostics on stderr, versioned --json shapes, and renaming a flag by aliasing it with a notice rather than removing it. Use when adding, changing, or retiring a command, subcommand, flag, or --json payload that people already run."
+alwaysApply: false
+---
+
+# CLI Interface Design
+
+## Purpose
+A command-line surface is a contract the moment somebody scripts it. Once a
+script reads an exit code, pipes stdout, or parses a `--json` payload, every
+later edit is either compatible or a silent breakage in someone else's CI. This
+rule fixes what those three channels mean and how a flag leaves the surface.
+
+## When To Apply
+Apply when adding a command or subcommand, adding or renaming a flag, changing
+what a command exits with, or changing the shape of anything it prints for a
+machine. It governs keryx's own CLI (`src/cli.ts` and `src/commands/**`);
+`rules/core/api-contracts.mdc` governs HTTP surfaces, and the versioning
+discipline there is the same discipline stated for a different transport.
+
+---
+
+## Rules
+
+### 1. Three exit codes, and they mean three different things
+
+keryx already runs a three-value convention, stated where it was first needed —
+`src/commands/wiki.ts:561-570`, `keryx wiki sections resolve`:
+
+- **0** — the command ran and the answer is clean.
+- **1** — the command ran and found something the caller should act on: a
+  broken link, a failing gate, a finding, a refusal.
+- **2** — the command could not tell. The registry was unreadable; the store
+  could not be opened; the input was not parseable.
+
+The reason 2 exists is written into that code: *"a script that treats 1 as
+'gone' would otherwise read an unreadable registry as a deletion."*
+`keryx memory search` adopted it deliberately and says so
+(`src/commands/memory.ts:182-196`), calling it *"reserved for 'cannot tell',
+distinct from both a completed search and a validation error."*
+
+**Two shipped commands do not honour it, and converging them is this rule's
+reason to exist:**
+
+- `keryx health run` folds `incomplete` — *"a required check that is missing,
+  skipped, unparsed or unfinished"* — into **1**, the same code as an
+  established threshold violation (`src/commands/health.ts:120-132`, with the
+  justification at `:103-112`). "Nobody ran eslint" and "eslint found 40
+  errors" are indistinguishable to a caller reading the code.
+- `keryx review` goes the other way and exits **0** on the same class of
+  answer: `reportCrossFamilyReviewProblems` and `reportFilterStatsProblems`
+  (both in `src/commands/review.ts`; cited by name because that file moves
+  under every review change, and a line number here has already gone stale
+  once) filter `not-recorded` out before failing, on the stated grounds that an
+  absence is honest. It is honest — and it is still not a pass.
+
+Three commands, one binary, three answers to "I could not tell". A new command
+uses 0/1/2 as defined above. An existing one moves toward it only with its
+consumers named, because narrowing 1 into 1-or-2 is itself a breaking change.
+
+Two settled corollaries, both worth keeping:
+
+- **A checker that reports defects and exits 0 is a checker nothing can gate
+  on** (`src/commands/skills.ts:927-951`). That code also exits non-zero on an
+  *empty* denominator — `findings: 0` over zero skills evaluated is not a pass.
+- **A wrapper forwards its child's code unchanged.** `keryx ctx run` sets
+  `process.exitCode = result.exitCode` (`src/commands/ctx.ts:210`); a wrapper
+  that collapsed every child failure to 1 would make the wrapped command
+  unusable under `set -e`.
+
+### 2. stdout is the answer, stderr is everything else
+
+The canonical statement is `src/commands/mcp.ts:78-92`: the deprecation notice
+goes to stderr *"because a bare `keryx mcp` IS the stdio MCP server: stdout
+carries JSON-RPC frames there, and a notice written to it corrupts every client
+session rather than informing anyone."* The same file routes every consumer
+diagnostic to stderr for that reason (`:41-44`).
+
+The discipline, applied:
+
+- Structured output — `--json` payloads, rendered reports, the thing a pipe is
+  for — goes to **stdout**, alone. `keryx skills verify --bundled --json`
+  writes parseable JSON to stdout and its diagnostic to stderr, and still exits
+  1 (`src/commands/skills.ts:934-947`). Verified: stdout parses, stderr is
+  empty on the clean path.
+- Progress, warnings, deprecation notices, usage errors go to **stderr**.
+- Under `--json`, a failure is *data on stdout*, not prose on stderr:
+  `keryx memory search --json` emits `{ outcome: "store-unreadable", … }` on
+  stdout and exits 2, where the plain mode prints to stderr
+  (`src/commands/memory.ts:190-195`). A machine reader gets a discriminated
+  result either way.
+- **Where this is broken today:** an unrecognised command prints its one-line
+  diagnostic to stderr and then dumps the full help to **stdout**
+  (`src/cli.ts:147-149`, `printHelp` at `:152`). Measured: `keryx bogusverb`
+  writes 9,503 bytes of help to stdout; `keryx wiki check --bogus` writes
+  4,150. Both numbers are the help text's own size and move whenever a command
+  is added — a later reading that differs is growth, not a correction to this
+  paragraph. A caller piping stdout for JSON receives a help screen instead, and
+  only the exit code says otherwise. **Help printed because of an error belongs
+  on stderr. Help printed because `--help` was asked for belongs on stdout.**
+
+### 3. A `--json` shape is versioned, deterministic, and pinned
+
+`keryx skills export` is the worked example. Removing one boolean from its
+manifest moved the version, and the code says why
+(`src/gdskills/export.ts:167-193`): *"Removing a field is a breaking change for
+anything parsing this file, so the version moves with it: a reader that still
+expects the boolean sees `schemaVersion: 2` and knows why it is absent instead
+of reading `undefined` as `false`."* The plugin manifest is a different shape
+and stays at its own `schemaVersion: 1` (`src/gdskills/export-plugin.ts:153`) —
+versions are per-shape, not per-repo. A test pins the number
+(`src/gdskills/export-runtime-builds.test.ts:108`).
+
+`keryx modules status --json` carries the other half: a `schemaVersion`, a
+deterministic key order sorted independently of authoring order *"which is what
+makes it safe to diff and to consume from a harness"*
+(`src/commands/modules.ts:197-210`), and a test that pins the version
+(`src/commands/modules.test.ts:26`).
+
+So the standard for any new machine-readable payload is:
+
+1. A top-level **object** with a `schemaVersion`. Not an array — an array
+   cannot grow a field. `rules/core/skills-storage-workflow.mdc` has said "One
+   top-level JSON object only" since it was written.
+2. Deterministic ordering, so two runs of an unchanged tree are byte-identical.
+3. A test that asserts the version and the required keys, in the same change.
+4. Adding an optional field is compatible. **Removing or renaming one bumps the
+   version**, in the same commit as the removal.
+
+**Where this is inconsistent today:** `keryx skills` serialises internal
+TypeScript objects straight to stdout at eleven call sites
+(`src/commands/skills.ts:222`, `:288`, `:398`, `:693`, `:735`, `:785`, `:822`,
+`:883`, `:935`, `:989`, `:1101`). Three of the eleven print a type that
+declares one — `LearningProposal` (`src/gdskills/learn.ts:17`, set at `:100`)
+at `:785`, and `ProjectSkillVerificationReport` (`src/gdskills/verify.ts:25`,
+set at `:96`) at `:883` and `:989`. The other eight carry no version at all.
+
+**The gap is the envelope, and it is the worse half.** `verify --bundled
+--json` emits an unversioned object (`root`, `skills`, `documents`,
+`skillNames`, `findings`); `verify --all --json` emits a bare array — `[]` when
+the registry is empty (`:973`), a list of reports otherwise (`:989`). So
+`keryx skills verify --all --json` ships `[{ "schemaVersion": 1, … }]`: each
+element versioned, the payload a caller actually parses not. That is standard 1
+failing in the direction it warns about — an array cannot grow a field, so the
+envelope can never be versioned later without the breaking change the version
+existed to avoid, however carefully each element inside it is versioned. One
+test pins one field of one of them
+(`src/commands/skills.bundled-verify.test.ts:58` asserts `findings` is `[]`). A
+rename inside any of the eight unversioned types is a CLI breaking change that
+nothing in the repository would catch.
+
+### 4. An unknown flag is refused, never ignored
+
+`rejectUnknownFlags` (`src/commands/review.ts:307-318`) is the standard, and
+its message is the argument: *"Refused rather than ignored — a flag that is
+silently dropped writes nothing and reports success."* (`:315`) It names the
+offending flag, lists what is accepted, and refuses. Every `keryx review`
+subcommand calls it.
+
+The same rule applies to a flag's **value**, not just its name. An unknown
+`--verifier` is refused because *"an unrecognised method would silently leave
+the tier at its default"* (`src/commands/review.ts:754`), and an unknown
+`--deny-tools` name is refused with the deniable names listed, because
+*"`--deny-tools web_serch` must not leave the session with web search and a
+clear conscience"* (`src/commands/interactive-agent-tools.ts:140-156`,
+`src/commands/shell.ts:1797-1798`).
+
+**Where this is inconsistent today:** the guard is per-command, and two
+implementations exist — `rejectUnknownFlags` and `rejectUnknownOptions`
+(`src/commands/workspace.ts:296-300`). Most commands have neither. Measured on
+this tree: `keryx review scope --bogus` exits 1 with a named refusal, while
+`keryx modules status --bogus --json` and `keryx skills verify --bundled
+--bogus` both exit **0** and ignore the flag. The same binary answers the same
+typo two different ways.
+
+A new command validates its flags. A flag that takes a fixed set of values
+validates the value too.
+
+### 5. A flag is renamed by aliasing it, and removed by refusing it out loud
+
+keryx has never deleted a spelling. Three patterns, all shipped, all correct:
+
+- **Rename → alias + one notice.** `keryx mcp install|uninstall` became
+  `keryx integrate` and the old spelling still works: one module translates the
+  old argument shape and calls the new implementation, so there is *"one
+  implementation and nothing to drift"* (`src/commands/mcp.ts:1-14`). It prints
+  exactly one line, on stderr, per invocation — *"A line a reader sees three
+  times in one command is a line they learn to skip, which is how deprecation
+  notices stop working at all"* (`:78-92`). A contract test asserts the retired
+  spellings still work, still write the same files, and name the replacement
+  **once** (`src/commands/mcp-naming.test.ts:453`, `:470`, `:490`).
+- **Removal → refuse by name, with the reason.** `keryx workspace handoff
+  --from` was removed because a caller could not be allowed to state it. It is
+  refused by name rather than as a generic unknown option, *"so anyone who
+  scripted it learns why it is gone instead of reading it as a typo"*
+  (`src/commands/workspace.ts:221-231`).
+- **A wrapper's own flag is consumed, not forwarded.** `keryx ctx rg --json` is
+  keryx's flag, stripped before the child command is built, because `rg --json`
+  means something else (`src/commands/ctx.ts:213-219`). Check the namespace
+  before claiming a flag name a wrapped tool already owns.
+
+**Where this is inconsistent today:** `keryx review` accepts both `--ref` and
+`--target-ref` for the same value, `--ref` winning
+(`src/commands/review.ts:147`, `:409`). There is no notice, and `--target-ref`
+appears nowhere in `keryx review --help`. An unannounced, undocumented alias is
+indistinguishable from an accidental duplicate: nothing tells a caller to
+migrate, so nothing will ever justify retiring it.
+
+A rename therefore ships four things in one change: the new spelling, the old
+one still working through the same implementation, one stderr notice naming the
+replacement, and a test that asserts both.
+
+---
+
+## The three that are not negotiable
+
+A nonzero exit never means "I could not tell" in a command that also uses
+nonzero to mean "I found something" — pick 2 for the first. A `--json` payload
+never loses or renames a field without a `schemaVersion` bump in the same
+commit. An old flag spelling is never deleted: it is aliased with a notice, or
+refused by name with the reason.
+
+---
+
+## Red Flags — Stop and re-read this rule if you are thinking:
+
+| Rationalization | Why it's wrong |
+|---|---|
+| "Exit 1 is fine, the message explains which kind of failure it was" | Messages are for people; scripts read the code. `keryx health run` cannot distinguish "eslint was skipped" from "eslint failed" today, and that is the gap, not a style preference |
+| "Nobody parses this `--json` yet, so I can change the shape freely" | You cannot observe who parses a published CLI's output. The version field costs one line and is the only thing that lets a reader tell absence from a downgrade |
+| "I'll print the warning to stdout, it's more visible there" | stdout is the pipe. A warning there corrupts every consumer that expected data — which is why `keryx mcp` routes its notice to stderr instead |
+| "The old flag is unused, I'll just delete it" | "Unused" means "no usage you can see". Alias it with a notice, or refuse it by name with the reason — both cost less than a silent breakage in someone's CI |
+| "An unrecognised flag is harmless, the command still does the right thing" | It does less than the operator asked and reports success. That is the failure `rejectUnknownFlags` was written for |
+| "It's just a help screen on stdout, who cares" | Nine kilobytes of it, where the caller expected JSON. Error output is error output regardless of how friendly it reads |
+| "I'll add the schemaVersion when the shape actually changes" | The first change is the one that needs it, and by then the unversioned readers already exist |
+
+**IRON LAW: ONCE A COMMAND IS PUBLISHED, ITS EXIT CODE, ITS STDOUT, AND ITS `--json` SHAPE ARE A CONTRACT — CHANGE THEM THE WAY YOU WOULD CHANGE AN API, OR NOT AT ALL.**

package/src/gdskills/bundled/rules/core/code-style-patterns.mdc

@@ -1,6 +1,7 @@
 ---
 description: "Code style and architecture patterns for TypeScript, React, and MobX."
 alwaysApply: false
+stack_requires: "react,mobx"
 ---
 
 # Code Style and Architecture Patterns

package/src/gdskills/bundled/rules/core/database-patterns.mdc

@@ -1,6 +1,7 @@
 ---
 description: "Database access patterns: no N+1 queries, indexes before deploy, backward-compatible migrations, transaction discipline. Use when writing queries, migrations, or ORM models."
 alwaysApply: false
+stack_requires: "sql"
 ---
 
 # Database Patterns

package/src/gdskills/bundled/rules/core/definition-of-done.mdc

@@ -0,0 +1,116 @@
+---
+description: "The single standing bar for calling a change done: evidence per criterion, gates that actually ran after the last edit, nothing disabled to go green, the diff committed. Use when reporting a task complete, accepting a worker's result, or deciding whether remaining work may be deferred."
+alwaysApply: false
+---
+
+# Definition Of Done
+
+## Purpose
+State, once, the bar a change must clear before any agent calls it done — so
+that "done" means the same thing to the worker that reports it and the
+orchestrator that accepts it. Six rules and two skills each state a piece of
+this bar today; this rule is the join, and it names which document owns which
+piece so the pieces cannot drift apart.
+
+## When To Apply
+Apply at the moment of reporting: before a worker writes its `STATUS:` line,
+before an orchestrator accepts a worker's result, and before a flow's
+acceptance criteria are confirmed. It applies to every change that ships —
+code, rule, skill, schema or document — not only to code with tests.
+
+---
+
+## The Bar
+
+A change is done when all five hold. Each is a fact about this working tree
+that can be checked by reading output, not a judgement about how the work felt.
+
+1. **Every acceptance criterion has named evidence.** For each criterion: the
+   command that demonstrates it, and that command's actual result. A criterion
+   whose evidence is "implemented" or "verified" has no evidence.
+2. **Every gate that applies to the changed files ran to completion, after the
+   last edit, in this tree, and passed** — lint, type-check, tests. Ran *after
+   the last edit*: a green result captured before the final change is not a
+   result about the change being reported.
+3. **A gate that did not run is not a pass.** A missing binary, a filtered
+   suite, a skipped file — each is `skipped`, never `pass`. Zero tests executed
+   is not zero failures.
+4. **Nothing was disabled to get there.** No test deleted, `.skip`ped or
+   `.only`d; no assertion removed; no threshold lowered; no suppression,
+   `eslint-disable` or `@ts-expect-error` added, unless that suppression *is*
+   the change and is stated as such in the report.
+5. **The diff is committed** at the task boundary, by whoever owns commits.
+
+If any of the five fails, the status is not `DONE`. Not `DONE` with the gap in
+a note; not `DONE_WITH_CONCERNS` with the gap as a concern. Report `BLOCKED`,
+or finish the work.
+
+---
+
+## What Each Document Owns
+
+This rule does not restate these; it points at them. When one of them changes,
+this list is what says whether the bar moved.
+
+| Document | Owns |
+|---|---|
+| `rules/core/tdd-workflow.mdc` | Clause 2 for tests specifically: the red-green-refactor sequence, and the invariant that `STATUS: DONE` requires a green suite (its Iron Law 1, and Iron Law 3 forbidding deletion of tests to get there — clause 4's test case). |
+| `.metaproject/skills/gdskills/orchestration/code-verifier/SKILL.md` | Clause 3: the gate decision, and the ruling that a check which did not run reports `status: skipped`, never `pass`. It also owns the distinction between the gate's result and the skill's own `STATUS:`. |
+| `rules/core/implementation-doc-mandate.mdc` | The shape of the evidence for clauses 1 and 2 — the Verification Gate block, the Acceptance Criteria Met list, and its Iron Law 3: the numbers must come from an independent verifier, not from self-assessment. |
+| `rules/core/subagent-status-protocol.md` | How the result is reported: `STATUS:` on line one, the five statuses, and the verification block every `DONE` response carries. |
+| `rules/core/git-concurrency.mdc` | Clause 5: a task is not done until its diff is committed, whether the worker or the orchestrator commits it. |
+| `.metaproject/skills/gdskills/orchestration/task-implementer/SKILL.md` | The worker-side reading of clause 3: skipped verification is a failed verification, and partial is not done. |
+| `rules/core/gproject-contracts.mdc` | The gproject return payload only. It is silent on clauses 2-5; that silence is not an exemption, and a gproject subagent reporting `DONE` still owes the verification block from `rules/core/subagent-status-protocol.md`. |
+| `rules/core/requirements-package-standard.mdc` | Clause 2 for a documentation package, where the gates are structural (required files, versions, links, honest status) rather than lint and tests. |
+
+Two readings of `DONE_WITH_CONCERNS` are in circulation, and this rule settles
+them: it is for information the orchestrator needs about work that **cleared
+all five clauses** — an interpretation made, a workaround for something
+non-blocking, a warning worth seeing. It is not a lower bar. An unmet
+acceptance criterion, a suite that was not run, or an uncommitted diff is not a
+concern attached to a completed task; it is an incomplete task.
+
+---
+
+## The Standing Bar And A Flow's Frozen Acceptance Criteria
+
+They are conjunctive. Neither overrides the other, and the question "which
+wins" has a definite answer in each direction:
+
+- **The frozen criteria fix the scope.** They say what must be true *of this
+  change* — and only the flow can say that. The bar cannot add a criterion, and
+  satisfying the bar does not satisfy a criterion the work never touched.
+- **The bar fixes the evidence, and is not waivable by silence.** Criteria that
+  say nothing about tests, lint or committing do not thereby excuse them. A
+  flow cannot lower the standing bar by omitting it, because the criteria were
+  frozen to stop scope drifting — not to enumerate the baseline every change
+  already owes.
+
+So: **a change that meets every frozen criterion but fails a clause of the bar
+is not done**, and a change that clears the bar while a criterion is unmet is
+not done either.
+
+When a frozen criterion genuinely conflicts with the bar — it asks for
+something that cannot be delivered without failing a clause — the criterion is
+not quietly reworded to match what was built. It changes through
+`keryx flow ac update <id> --reason "<why>"`, with the conflict as the reason,
+per `.metaproject/skills/gdskills/orchestration/flow-orchestrator/SKILL.md`.
+Rewriting a criterion to describe the work is how a flow loses the only record
+of what it set out to do.
+
+---
+
+## Red Flags — Stop and re-read this rule if you are thinking:
+
+| Rationalization | Why it's wrong |
+|---|---|
+| "Everything passed, I'll just make the last small edit and report" | Clause 2 is about *this* tree after *this* edit. A result captured before the final change is evidence about a tree that no longer exists |
+| "The test command printed no failures, so it's green" | No failures and no tests are the same output. Read the count: zero executed is clause 3, not a pass |
+| "It's done except for the one flaky test / the docs / the commit" | "Done except for" is the phrase this rule exists to delete. The exception is the part that is not done, and it decides the status |
+| "I'll report DONE_WITH_CONCERNS and name the unmet criterion as a concern" | `DONE_WITH_CONCERNS` is for information about completed work. An unmet criterion is incomplete work wearing a success status |
+| "The lint binary isn't installed here, so there is nothing to fail" | A check that cannot run has told you nothing. Say it was skipped and which one; do not convert absence of a result into a result |
+| "The orchestrator will run the gates anyway, so I don't have to" | Two agents each assuming the other verified is how a change reaches review with nothing ever having run against it |
+| "The acceptance criterion doesn't mention lint, so lint isn't in scope" | The criteria bound the scope of the work, not the evidence every change owes. Silence is not an exemption |
+
+**IRON LAW: A STEP THAT WAS SKIPPED IS A STEP THAT FAILED. "DONE EXCEPT FOR X"
+IS NOT DONE — IT IS BLOCKED ON X.**

package/src/gdskills/bundled/rules/core/documentation-management.mdc

@@ -1,5 +1,5 @@
 ---
-description: "Manage project documentation in <PROJECT_DIR>/docs (default) or $GDMETAPRO_DOCS_ROOT with synchronized multilingual outputs."
+description: "Manage project documentation in <PROJECT_DIR>/docs (default) or $GDMETAPRO_DOCS_ROOT. Language variants are opt-in, not mandatory."
 alwaysApply: false
 ---
 
@@ -11,16 +11,28 @@ Define how the agent creates and updates documentation under `<DOCS_ROOT>` (`<PR
 ## When To Apply
 Apply when the user asks to create or update documentation, plans, requirements, communication notes, reports, or review artifacts.
 
+## Requirements Packages
+Anything under `docs/requirements/<name>/` (README, PRD, specification, and
+their optional companions, including `implementation-plan.md`) follows
+`requirements-package-standard.mdc`. Do not restate or diverge from that
+layout here: no date-stamped subfolders, no mandatory `ru`/`en`/`ai` variants —
+the `Version: x.y.z` field on each document is the versioning mechanism.
+
 ## Mandatory Behavior
 1. Ask for target location and folder name before writing any doc.
-2. Use date-stamped folders; never overwrite previous doc sets.
-3. Keep language variants synchronized.
+2. Do not date-stamp folders. Write into `<category>/<name>/` and update
+   documents in place, bumping their `Version` field where the category's
+   standard defines one (requirements packages always do).
+3. Default to `en` output. Add other language variants only when the user
+   explicitly asks for them, and keep any variants you do create synchronized.
 4. Update `<DOCS_ROOT>/README.md` after doc changes.
 5. Ask whether to apply changes (branch/commit/PR) after edits.
 
 ## Required Locations
 - Root: `<DOCS_ROOT>` (default: `<PROJECT_DIR>/docs`)
-- Standard pattern: `<DOCS_ROOT>/<category>/<name>-<YYYY-MM-DD>/`
+- Standard pattern: `<DOCS_ROOT>/<category>/<name>/`
+- Requirements packages: `<DOCS_ROOT>/requirements/<name>/` per
+  `requirements-package-standard.mdc` (no date folder).
 
 ## DOCS_ROOT Resolution
 
@@ -40,45 +52,27 @@ DOCS_ROOT="${GDMETAPRO_DOCS_ROOT:-$PROJECT_DIR/docs}"
 
 | Category | Path pattern | Description |
 |----------|-------------|-------------|
-| `requirements` | `docs/requirements/<name>/<YYYY-MM-DD>/` | Feature requirements (iterations grouped by name) |
-| `plans` | `docs/plans/<name>/<YYYY-MM-DD>/` | Standalone implementation plans |
-| `report` | `docs/report/<name>/<YYYY-MM-DD>/` | Standalone review/audit reports |
-| `review-testing` | `docs/review-testing/<name>/<YYYY-MM-DD>/` | QA and testing artifacts |
-| `communication` | `docs/communication/<name>/<YYYY-MM-DD>/` | Communication and context docs |
-| `analysis` | `docs/analysis/<name>/<YYYY-MM-DD>/` | Feature/branch analysis (see below) |
+| `requirements` | `docs/requirements/<name>/` | See `requirements-package-standard.mdc`. |
+| `plans` | `docs/plans/<name>/` | Standalone implementation plans not tied to a requirements package. A plan that belongs to one lives inside that package as `implementation-plan.md` instead — see `requirements-package-standard.mdc` and `implementation-plans.mdc`. |
+| `report` | `docs/report/<name>/` | Standalone review/audit reports |
+| `review-testing` | `docs/review-testing/<name>/` | QA and testing artifacts |
+| `communication` | `docs/communication/<name>/` | Communication and context docs |
+| `analysis` | `docs/analysis/<name>/` | Feature/branch analysis (see below) |
 
 ## Analysis Category Structure
 
 The `analysis` category is used by the `feature-analyzer` skill and any branch/feature analysis tasks.
 
 ```
-docs/analysis/<feature-name>/<YYYY-MM-DD>/
-  report/
-    ru/
-      report.md
-    en/
-      report.md
-    ai/
-      report.md
-  plans/
-    ru/
-      implementation-plan.md
-    en/
-      implementation-plan.md
-    ai/
-      implementation-plan.md
+docs/analysis/<feature-name>/
+  report.md
+  implementation-plan.md
 ```
 
-- `report/` — detailed analysis of changes, ticket, cross-repo findings
-- `plans/` — actionable implementation plan derived from the analysis
-- Each subfolder contains `ru/`, `en/`, `ai/` language variants (all three are mandatory)
-
-## Language Matrix
-- Requirements: `ru`, `en`, `ai`
-- Implementation plans: `ru`, `en`, `ai`
-- Communication docs: `ru`, `en`, `ai`
-- Analysis (`report/` + `plans/`): `ru`, `en`, `ai` (mandatory)
-- Other categories: follow explicit user request; default to at least `en`.
+- `report.md` — detailed analysis of changes, ticket, cross-repo findings
+- `implementation-plan.md` — actionable implementation plan derived from the analysis
+- Add `ru`/`en`/`ai` variants only if the user explicitly asks for them; the
+  default is the single `en` files shown above.
 
 ## Naming Rules
 - Ask user for `<name>` first.
@@ -100,7 +94,8 @@ Standalone skill invocations continue to use `docs/analysis/`. Only orchestrator
 See `core/jobs-documentation.mdc` for the `jobs/` system.
 
 ## Prohibited
-- Single-language output when the category requires `ru+en+ai`.
-- Partial language updates.
+- Date-stamped folders anywhere under `<DOCS_ROOT>`.
+- Language variants the user did not ask for.
+- Partial updates to language variants that do exist.
 - Writing docs outside the requested category path without confirmation.
-- Mixing `report/` and `plans/` content in the same file.
+- Mixing `report`/`implementation-plan` content in the same file.

package/src/gdskills/bundled/rules/core/error-handling.mdc

@@ -98,17 +98,7 @@ try {
 ```
 
 ### Rule 4: No Unhandled Promise Rejections
-Every `async` call chain must end with error handling. `Promise.all` rejections must be caught. Fire-and-forget patterns must use `.catch(logger.error)`.
-
-```typescript
-// BAD
-Promise.all([fetchA(), fetchB()]); // unhandled rejection if either fails
-
-// GOOD
-const results = await Promise.allSettled([fetchA(), fetchB()]);
-const failures = results.filter(r => r.status === 'rejected');
-if (failures.length > 0) { /* handle */ }
-```
+See `async-patterns.mdc` Rule 4 ("No Unhandled Promise Rejections") for the full rule, examples, and rationale — it belongs there because it is fundamentally about promise/async control flow, not error typing.
 
 ### Rule 5: Propagate, Don't Wrap Blindly
 When catching and re-throwing, preserve the original error as `cause`:

package/src/gdskills/bundled/rules/core/execution-metrics.md

@@ -38,8 +38,7 @@ gdwiki enrichment, or anything that writes files) MUST also save the report:
 - Otherwise → `.metaproject/data/<primary-module>/metrics/run-<ISO-timestamp>.md`
 
 Create the directory. Use a filesystem-safe timestamp (colons → `-`). Print the
-saved path under the table. This lets the post-commit hook and future runs find
-past reports.
+saved path under the table. This lets future runs find past reports.
 
 ## Honesty rules (do not fabricate)
 

package/src/gdskills/bundled/rules/core/frontend-assistant.mdc

@@ -4,6 +4,7 @@ alwaysApply: false
 globs:
   - "src/**/*.ts"
   - "src/**/*.tsx"
+stack_requires: "react,mobx"
 ---
 
 # Frontend Assistant Guidelines