Gates and code placement
pipelines_hooks is the shared, repository-agnostic pre-commit package every
repository in the fleet consumes (.pre-commit-hooks.yaml; run one gate with
pipelines-hook <id>). Every gate returns 0 clean, 1 findings, 2 cannot-run.
What follows is read from the gate source and .config/kiss.toml, not
restated from policy prose, so it stays correct when a cap changes.
Complexity (cccc)
Caps, per function, including nested children: cyclomatic 10, cognitive
15 (pipelines_hooks/complexity/__init__.py). Both metrics are measured for
every function in every cccc-supported file; extraction moves complexity into
the child, so a parent that now looks clean is not the whole story.
complexity-staged compares the staged index against HEAD (never
the working tree) and fails only a function that is NEW over a cap or
WORSE than it was. An existing over-cap function left unchanged passes;
nothing is written, no count is frozen, and the real numbers print on every
run — it is diff-scoped, deliberately not a baseline.
complexity-census measures every tracked file and fails on the real
backlog above zero: no baseline, no allowlist.
- One Rust-only exemption, re-derived from source on every run, never
persisted as a list of names or files: a flat, exhaustive
match may exceed
the cyclomatic cap alone (never the cognitive cap) when its cognitive score
is within cap, it contains at least one match, no arm is irrefutable
(_, a bare binding, or an alternation containing one), and its residual
(measured cyclomatic minus arm count) is itself within the cyclomatic cap.
Decomposing an exhaustive match trades away a compiler guarantee for a
metric, so the rule accepts the residual instead.
- Fix path: split the function or replace branching with dispatch; do not
raise a threshold or add a suppression comment — the gate's own guidance
text states an inline suppression is treated as a one-line baseline.
KISS
.config/kiss.toml in the pipelines repository is its own authoritative config — per the
fleet rule that a repository's own KISS config wins over any other copy of
the numbers. Its [python] table (verified against origin/main): 35
statements/function, 15 local variables, 20 calls/function, 3 positional
args, 1 boolean parameter, 5 returns/function, 3 return values/function, 4
indentation depth, 2 nested function depth, 3 statements/try block, 5
decorators/function, 10 methods/class, 10 functions/file, 30 imported
names/file, 200 statements/file, 300 lines/file, 1 interface type/file.
branches_per_function, keyword_only_args, concrete_types_per_file,
cycle_size, dependency_depth and indirect_dependencies are deliberately
set to an effectively-off value in this file — each is owned by a different
gate instead (branching by cccc, cycles by the import-cycles hook): one
metric, one tool. The pipelines repository has no Rust source and so carries no
[rust] table; a repository that does have Rust KISS caps enforces them with
the same pinned kiss fork build, from that repository's own
.config/kiss.toml — read it there rather than assume the Python numbers
above apply, or that any one fleet-wide Rust number is current.
kiss-staged is diff-scoped the same way as complexity-staged: only
findings attributable to the staged change fail; pre-existing debt in a
touched file stays visible in the census but does not fail the commit.
kiss-census checks every tracked file and fails on any finding — "every
finding fails, there is no advisory class and no baseline" (the hook's own
docstring).
- Never invoke the
kiss binary directly without going through these hooks:
a bare kiss check with no --config writes a self-calibrating
.kissconfig, and a multi-path invocation reports a false clean.
Clone gates
Two independent tools, two different identity mechanisms — read the actual
keying code before assuming either behaves like the other:
jscpd-differential compares the base commit's tree against
git merge-tree --write-tree <base> HEAD (the tree this change would
actually produce, not the branch tip) and fails on any pair present after
that is absent before. A pair's identity
(pipelines_hooks/clones/jscpd_keys.py) is (format, sha256 digest of the matched fragment text, the pair's two file paths sorted, an ordinal).
Line numbers and symbol names are never part of the key — a line shift
elsewhere does not manufacture a new pair, and renaming a function does not
remove one: the hash is over the duplicated text itself, not an
identifier, so the same duplicated body is the same key under any name.
This gate's own failure message states it plainly: "this gate has no
suppression mechanism."
dupehound-changed flags a changed function that structurally
reimplements an existing one (detection is structural — shape of the code,
not its identifier names). It does carry one reviewed register,
.config/dupehound-distinct.toml (not present in the pipelines repository today):
a hand-written, per-entry-justified (12+ word reason required) list of
pairs a human has reviewed as genuinely distinct. Each entry pins a content
digest of both functions' normalized text, so it rots — fails again —
the moment either function's body changes, even if neither name does. The
module's own docstring draws the contrast explicitly: "a baseline is
machine-written, unexplained and grows by default. This register is
HAND-WRITTEN, carries a reason per entry, and ROTS." Renaming one side does
not dodge a real finding either: the underlying detection is structural, so
the clone still gets reported under the new name, and a register entry
keyed in part by the old name no longer matches it — it simply reports as
a fresh, unregistered finding.
Privacy and secret history
tracked-privacy fails on any finding at all: "the absolute maximum is
zero findings; there is no count-based allowance." It requires an external
identity catalog and fails closed (exit 2) rather than scanning a silently
narrower set when the catalog is missing.
secret-history scans the patch text of every commit in the unpublished
range (so a credential a later commit deletes still fails it) and has
no allowlist file. The one exemption that exists at all is a reviewed
inline marker, # sanitizer:ignore - <reason>, which must carry a
non-empty reason after the separator — a bare marker is rejected. This is a
documented, reviewed, per-line exemption, not a blanket suppression.
Taken together: there is no baseline file, no silently-growing allowlist,
and no count-based exemption anywhere in these gates. The two mechanisms that
come closest — the dupehound distinct-pairs register and the secret-history
inline marker — are both hand-written, require a stated reason, and are
designed to force re-review when the code they cover changes, not to
permanently suppress a finding.
Code placement
One dependency direction runs through the ecosystem's core repositories:
pipelines → epistemic-graph → scion-sdk → agent-utilities →
agent-webui → arbora. Each repository's own AGENTS.md states what it
owns under a "What this repository owns" heading — that heading, not this
skill, is the authoritative answer for a specific capability, because it is
what gets kept current as boundaries shift (for example, agent-utilities is
presently contracting to an orchestration-only control plane, with durable
graph/semantics code moving to epistemic-graph and connector code to
scion-sdk rather than staying in agent-utilities).
The rule: new code goes to the repository that owns that capability, never
to whichever checkout happens to be open. Durable graph storage, query,
reasoning and semantics belong in epistemic-graph; connector transport,
manifests and certification belong in scion-sdk; the agent
orchestration plane (planning, delegation, skills/workflow runtime) belongs
in agent-utilities; the served MCP/REST/control-plane runtime belongs in
arbora; shared CI/quality/workflow machinery like this package belongs in
pipelines. When it is not obvious which repository owns a piece of new
behavior, read that repository's own AGENTS.md ownership section before
writing anything — do not infer ownership from this table alone, since it is
a pointer, not the contract.
1---2name: gates-and-code-placement3domain: development4skill_type: skill5description: >-6 What each shared pipelines quality gate actually enforces (complexity, KISS,7 clone, privacy, secret-history) as the hook source implements it, and the8 one-sentence rule for which repository new code belongs in. Use before9 writing code anywhere in the fleet, or when a gate fails and the fix isn't10 obvious from its one-line message.11license: MIT12tags: [pipelines, gates, complexity, kiss, clones, privacy, code-placement]13metadata:14 source: https://skillmd.com/skills/knuckles-team/gates-and-code-placement15 version: '1.6.0'16---1718# Gates and code placement1920`pipelines_hooks` is the shared, repository-agnostic pre-commit package every21repository in the fleet consumes (`.pre-commit-hooks.yaml`; run one gate with22`pipelines-hook <id>`). Every gate returns 0 clean, 1 findings, 2 cannot-run.23What follows is read from the gate source and `.config/kiss.toml`, not24restated from policy prose, so it stays correct when a cap changes.2526## Complexity (cccc)2728Caps, per function, including nested children: **cyclomatic 10, cognitive2915** (`pipelines_hooks/complexity/__init__.py`). Both metrics are measured for30every function in every cccc-supported file; extraction moves complexity into31the child, so a parent that now looks clean is not the whole story.3233- `complexity-staged` compares the **staged index** against **HEAD** (never34 the working tree) and fails only a function that is **NEW** over a cap or35 **WORSE** than it was. An existing over-cap function left unchanged passes;36 nothing is written, no count is frozen, and the real numbers print on every37 run — it is diff-scoped, deliberately not a baseline.38- `complexity-census` measures every tracked file and fails on the real39 backlog above zero: no baseline, no allowlist.40- One Rust-only exemption, re-derived from source on every run, never41 persisted as a list of names or files: a flat, exhaustive `match` may exceed42 the cyclomatic cap alone (never the cognitive cap) when its cognitive score43 is within cap, it contains at least one `match`, no arm is irrefutable44 (`_`, a bare binding, or an alternation containing one), and its residual45 (measured cyclomatic minus arm count) is itself within the cyclomatic cap.46 Decomposing an exhaustive match trades away a compiler guarantee for a47 metric, so the rule accepts the residual instead.48- Fix path: split the function or replace branching with dispatch; do not49 raise a threshold or add a suppression comment — the gate's own guidance50 text states an inline suppression is treated as a one-line baseline.5152## KISS5354`.config/kiss.toml` in the pipelines repository is its own authoritative config — per the55fleet rule that a repository's own KISS config wins over any other copy of56the numbers. Its `[python]` table (verified against `origin/main`): 3557statements/function, 15 local variables, 20 calls/function, 3 positional58args, 1 boolean parameter, 5 returns/function, 3 return values/function, 459indentation depth, 2 nested function depth, 3 statements/try block, 560decorators/function, 10 methods/class, 10 functions/file, 30 imported61names/file, 200 statements/file, 300 lines/file, 1 interface type/file.6263`branches_per_function`, `keyword_only_args`, `concrete_types_per_file`,64`cycle_size`, `dependency_depth` and `indirect_dependencies` are deliberately65set to an effectively-off value in this file — each is owned by a different66gate instead (branching by cccc, cycles by the import-cycles hook): one67metric, one tool. The pipelines repository has no Rust source and so carries no68`[rust]` table; a repository that does have Rust KISS caps enforces them with69the same pinned `kiss` fork build, from **that** repository's own70`.config/kiss.toml` — read it there rather than assume the Python numbers71above apply, or that any one fleet-wide Rust number is current.7273- `kiss-staged` is diff-scoped the same way as `complexity-staged`: only74 findings attributable to the staged change fail; pre-existing debt in a75 touched file stays visible in the census but does not fail the commit.76- `kiss-census` checks every tracked file and fails on any finding — "every77 finding fails, there is no advisory class and no baseline" (the hook's own78 docstring).79- Never invoke the `kiss` binary directly without going through these hooks:80 a bare `kiss check` with no `--config` writes a self-calibrating81 `.kissconfig`, and a multi-path invocation reports a false clean.8283## Clone gates8485Two independent tools, two different identity mechanisms — read the actual86keying code before assuming either behaves like the other:8788- **`jscpd-differential`** compares the base commit's tree against89 `git merge-tree --write-tree <base> HEAD` (the tree this change would90 actually produce, not the branch tip) and fails on any pair present after91 that is absent before. A pair's identity92 (`pipelines_hooks/clones/jscpd_keys.py`) is `(format, sha256 digest of the93 matched fragment text, the pair's two file paths sorted, an ordinal)`.94 **Line numbers and symbol names are never part of the key** — a line shift95 elsewhere does not manufacture a new pair, and renaming a function does not96 remove one: the hash is over the duplicated text itself, not an97 identifier, so the same duplicated body is the same key under any name.98 This gate's own failure message states it plainly: "this gate has no99 suppression mechanism."100- **`dupehound-changed`** flags a changed function that structurally101 reimplements an existing one (detection is structural — shape of the code,102 not its identifier names). It does carry one reviewed register,103 `.config/dupehound-distinct.toml` (not present in the pipelines repository today):104 a **hand-written**, per-entry-justified (12+ word reason required) list of105 pairs a human has reviewed as genuinely distinct. Each entry pins a content106 digest of both functions' normalized text, so it **rots** — fails again —107 the moment either function's body changes, even if neither name does. The108 module's own docstring draws the contrast explicitly: "a baseline is109 machine-written, unexplained and grows by default. This register is110 HAND-WRITTEN, carries a reason per entry, and ROTS." Renaming one side does111 not dodge a real finding either: the underlying detection is structural, so112 the clone still gets reported under the new name, and a register entry113 keyed in part by the old name no longer matches it — it simply reports as114 a fresh, unregistered finding.115116## Privacy and secret history117118- `tracked-privacy` fails on any finding at all: "the absolute maximum is119 zero findings; there is no count-based allowance." It requires an external120 identity catalog and fails closed (exit 2) rather than scanning a silently121 narrower set when the catalog is missing.122- `secret-history` scans the patch text of every commit in the unpublished123 range (so a credential a later commit deletes still fails it) and has124 **no allowlist file**. The one exemption that exists at all is a reviewed125 inline marker, `# sanitizer:ignore - <reason>`, which must carry a126 non-empty reason after the separator — a bare marker is rejected. This is a127 documented, reviewed, per-line exemption, not a blanket suppression.128129**Taken together:** there is no baseline file, no silently-growing allowlist,130and no count-based exemption anywhere in these gates. The two mechanisms that131come closest — the dupehound distinct-pairs register and the secret-history132inline marker — are both hand-written, require a stated reason, and are133designed to force re-review when the code they cover changes, not to134permanently suppress a finding.135136## Code placement137138One dependency direction runs through the ecosystem's core repositories:139**pipelines → epistemic-graph → scion-sdk → agent-utilities →140agent-webui → arbora**. Each repository's own `AGENTS.md` states what it141owns under a "What this repository owns" heading — that heading, not this142skill, is the authoritative answer for a specific capability, because it is143what gets kept current as boundaries shift (for example, agent-utilities is144presently contracting to an orchestration-only control plane, with durable145graph/semantics code moving to epistemic-graph and connector code to146scion-sdk rather than staying in agent-utilities).147148The rule: **new code goes to the repository that owns that capability, never149to whichever checkout happens to be open.** Durable graph storage, query,150reasoning and semantics belong in epistemic-graph; connector transport,151manifests and certification belong in scion-sdk; the agent152orchestration plane (planning, delegation, skills/workflow runtime) belongs153in agent-utilities; the served MCP/REST/control-plane runtime belongs in154arbora; shared CI/quality/workflow machinery like this package belongs in155pipelines. When it is not obvious which repository owns a piece of new156behavior, read that repository's own `AGENTS.md` ownership section before157writing anything — do not infer ownership from this table alone, since it is158a pointer, not the contract.