neo-agent-skills 0.1.68 → 0.1.69

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.
@@ -0,0 +1,36 @@
1
+ # Deliberate-Duplication Audit (boundary- or cycle-forced parity twins)
2
+
3
+ Load-on-demand payload behind the guide's §7.5.5 trigger and `pull-request` §1.
4
+
5
+ > **Duplicate only when importing is structurally impossible. When you do, pin the copies by test, never by comment.**
6
+
7
+ ## 1. The restraining clause (lead discriminator)
8
+
9
+ Do not reach for parity-twin duplication when a runtime import is structurally and architecturally legal. A convention that teaches only how to pin copies reads as licence to duplicate.
10
+
11
+ - **Qualifying cases (import is structurally impossible):**
12
+ - **Architectural / repository boundary (`neomjs/neo#17239`):** `neomjs/neo-agent-institution`'s `apps/**` must not import `neomjs/neo-agent-brain`'s `ai/**` at runtime across the app→Brain boundary.
13
+ - **Cycle-forced separation:** the would-be importer is itself imported by the module holding the constant or predicate, so importing back closes a module cycle.
14
+ - **Inverse case — delegate when import is possible (`neomjs/neo#17325`):**
15
+ In `neomjs/neo-agent-brain`'s `ai/services/graph/providerReadinessHelper.mjs`, `satisfiesRequiredModelIdOnOpenAiCompatibleLane` is shared by `DeploymentStateBridgeService.mjs` and `TextEmbeddingService.mjs`. Because all three modules live inside `neomjs/neo-agent-brain`'s `ai/` layer and can import the helper without crossing a forbidden boundary or closing a cycle, delegating to `satisfiesRequiredModelId` was mandatory:
16
+ > *"Delegating rather than restating the predicate is deliberate. The sibling `redactCredentials` module exists because five private copies of one rule drifted; a second copy of the implicit-tag rule would start that story here, and the copy that drifts is always the one nobody is looking at."*
17
+
18
+ ## 2. The pinning clause (when duplication is forced)
19
+
20
+ When a boundary or cycle forces a small predicate, table, or constant to exist in two places, a JSDoc `"parity-twin"` note or cross-reference comment on both sides is prose that expires the first time either copy is edited.
21
+
22
+ - **Pin with one shared-fixture test, never a comment or a spec-per-side (`neomjs/neo#17348`):**
23
+ In `neomjs/neo#17348`, `describeOperatorSeatConflation` (`neomjs/neo-agent-brain/ai/services/fleet/operatorSeatConflation.mjs`) and `FleetCockpitController#deriveOperatorIdentityPosture` (`neomjs/neo-agent-institution/apps/agentos/view/fleet/cockpit/Controller.mjs`) duplicate a three-line conflation check across the app→Brain boundary. Two separate unit specs — one per twin, at different assertion depths — left one side's canonicalization deletable with its own spec still green. The repair (`neomjs/neo-agent-institution/test/playwright/unit/apps/agentos/view/fleet/mailbox/operatorSeatConflationParity.spec.mjs`) reaches the Brain twin via `loadAgentOsModule` with a bound Brain runtime (`NEO_AGENTOS_RUNTIME_ROOT`) and drives both twins from one shared truth table:
24
+ > *"A duplication defended by a comment decays the first time someone edits one side; THIS table is what converts the architectural bet into an enforced one. A cross-boundary import in a TEST is not a runtime coupling — it is the standard pin for a deliberate twin.*
25
+ > *One shared fixture drives BOTH implementations; a divergence fails here instead of surviving until an incident notices."*
26
+ - **Cross-boundary import in a test is not a runtime coupling:**
27
+ An Institution `apps/**` runtime module may not import from Brain `ai/**`, but a unit test importing the app twin and loading the Brain `ai/**` twin via `loadAgentOsModule` to feed both the same fixture table introduces zero runtime coupling.
28
+
29
+ ## 3. Reviewer check (`"what fails when these diverge?"`)
30
+
31
+ When a diff introduces or touches a deliberate duplication (or defends a copy with a `"parity-twin"` / `"keep in sync with"` comment), ask:
32
+
33
+ > **"What fails when these diverge?"**
34
+
35
+ 1. **Can one side import the other (or a shared leaf in the same layer) without crossing a forbidden boundary or closing a cycle?** If yes → **Required Action:** delete the duplicate and import/delegate (`#17325`).
36
+ 2. **If the import is genuinely impossible, does a single test import both twins and drive them over one shared fixture table?** If only comments or separate per-side specs exist → **Required Action:** add a shared-fixture parity spec that fails the moment either twin drifts (`#17348`). Because a cross-repo parity pin (`crossRepoBrainTestIgnore`) runs only in the CI that binds the peer runtime (`neomjs/neo-agent-institution` CI setting `NEO_AGENTOS_RUNTIME_ROOT`), when a diff edits the twin in a repo whose CI does not run that pin (such as a `neomjs/neo-agent-brain` PR editing `operatorSeatConflation.mjs`), require running the parity pin against that candidate head before approving.
@@ -255,6 +255,9 @@ Demo/product-surface diffs touching rendered motion: load `audits/demo-surface-m
255
255
 
256
256
  Before claiming/requesting visual-render, headed-harness, or native-matrix evidence: consult the Engine's [Seat Evidence Capabilities guide](https://github.com/neomjs/neo/blob/dev/learn/agentos/process/SeatEvidenceCapabilities.md) (check `observedAt`; stale = `unknown`).
257
257
 
258
+ ### 7.5.5 Deliberate-Duplication Audit
259
+ <!-- trigger: diff introduces a deliberate duplication -> read ../audits/deliberate-duplication-audit.md -->
260
+
258
261
  ### 7.6 CI / Security Checks Audit
259
262
 
260
263
  10% AC/scope sanity layer unless CI/security reveals a defect. Green CI is eligibility evidence, not an architecture verdict.
@@ -9,6 +9,7 @@ Before the final `git commit` and `gh pr create`—an irreversible handoff—ste
9
9
  **Scope Creep vs. Iteration:**
10
10
  - **Minor gaps:** repair JSDoc/Anchor & Echo, edge cases, tests, and test placement on the branch first.
11
11
  - **Major refactors:** keep the bounded solution; file a linked follow-up ticket for the superior architecture.
12
+ - **Deliberate duplication (boundary- or cycle-forced):** duplicate only when importing is structurally impossible, and pin the copies with one shared-fixture spec rather than a comment ([`deliberate-duplication-audit.md`](../../pr-review/audits/deliberate-duplication-audit.md)).
12
13
  - **Tier 2.5 foreign-authority trigger:** If a repair would change a reviewer's contract or another named peer's consumer surface, send that owner the fork, recommendation, and evidence, then continue fork-independent author work. Named authority—not uncertainty—triggers this; the reply is never a wait gate.
13
14
 
14
15
  *If and only if* you pass this reflection phase, proceed to the Git execution sequence.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "neo-agent-skills",
3
- "version": "0.1.68",
3
+ "version": "0.1.69",
4
4
  "description": "Install the workflow substrate a cross-model AI team actually runs on: ticket intake, PR review gates, lane coordination and guards, versioned as a package. The skills Neo.mjs maintainers load every session — materialized into your repo, not copied.",
5
5
  "type": "module",
6
6
  "license": "MIT",