neo-agent-skills 0.1.67 → 0.1.69

package/.agents/skills/guide-authoring/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: guide-authoring
-description: "Protocol for learn/ guides; use before authoring or reviewing any guide under learn/benefits/*.md or learn/agentos/*.md."
+description: "Protocol for learn/**/*.md guides, tutorials, and docs (except learn/blog/*.md, owned by blog-post, and ADR bodies); use before authoring, relocating, or reviewing any learn/**/*.md document."
 ---
 
 # Guide Authoring Skill
 
-If you are authoring OR reviewing a `learn/` guide (`learn/benefits/*.md`, `learn/agentos/*.md`), you MUST immediately use the `view_file` tool to read and strictly adhere to `.agents/skills/guide-authoring/references/guide-authoring-bar.md` before writing the first sentence or posting a review verdict.
+If you are authoring, relocating, OR reviewing a `learn/**/*.md` document (excluding `learn/blog/*.md`, owned by `blog-post`, and ADR bodies), you MUST immediately use the `view_file` tool to read and strictly adhere to `.agents/skills/guide-authoring/references/guide-authoring-bar.md` before choosing a section, writing the first sentence, or posting a review verdict.
 
-A guide is held to a 9/10 bar: grounded by *using* the system's tools + memory-mining (not inference), narrative + benefits-driven with lived voice, render-verified TD Mermaid diagrams, conceptual-vs-reference separation, never hand-editing generated files, and a no-rubber-stamp reviewer gate against the WHOLE bar. Skipping it is the higher-cost path — MemoryCore took ~7 cycles and KnowledgeBase a rubber-stamp reversal precisely because this discipline was skipped.
+A `learn/` document is held to a 9/10 bar: pre-write container placement against the repo's local `learn/tree.json` (§0), grounded by *using* the system's tools + memory-mining (not inference), narrative + benefits-driven with lived voice, render-verified TD Mermaid diagrams, conceptual-vs-reference separation, never hand-editing generated files, and a no-rubber-stamp reviewer gate against the WHOLE bar. Skipping it is the higher-cost path — MemoryCore took ~7 cycles and KnowledgeBase a rubber-stamp reversal precisely because this discipline was skipped.

package/.agents/skills/guide-authoring/references/guide-authoring-bar.md

@@ -1,30 +1,41 @@
 # Guide Authoring Bar
 
-Fires when you author OR review a `learn/` guide (`learn/benefits/<slug>.md`, `learn/agentos/<slug>.md`). The bar is **9/10 or it bounces** — the operator rejects 75%+ of guide PRs that miss it, and every redo is negative ROI.
+Fires when you author, relocate, OR review a `learn/**/*.md` document (excluding `learn/blog/*.md`, owned by `blog-post`, and ADR bodies governed by §7). The bar is **9/10 or it bounces** — 75%+ of guide PRs that miss it are rejected.
 
-**The recursive principle.** A guide about a system is only credible if it was written by *using* that system. The #1 quality failure is writing from the old guide + code-reading (inference) instead of from the live tools + content. `MemoryCore.md` hit ~6/10 and shipped two factual errors for exactly this reason; `KnowledgeBase.md` was rubber-stamp-approved, then reversed. This guide is those cycles distilled — so the next guide starts at 9, not at the beginning.
+**The recursive principle.** A guide about a system is only credible if written by *using* that system, not by reading the old guide + code (inference). `MemoryCore.md` hit ~6/10 with two factual errors for that reason; `KnowledgeBase.md` was rubber-stamp-approved and reversed.
+
+## 0. Pre-write placement gate — "what am I?" before the file has a path — `DISCIPLINE-ONLY`
+
+Before writing or relocating any `learn/**/*.md` file, decide **which `<section>` directory and navigation container it belongs in**. Hosted in `guide-authoring` (cross-pointed from `structural-pre-flight-workflow.md §5`) rather than a new skill or `.mjs`-only `structural-pre-flight`: widening `guide-authoring` to `learn/**/*.md` avoids adding a new trigger while bringing every non-blog, non-ADR `learn/**/*.md` path under one documentation gate.
+
+1. **Enumerate directories and tree containers; never grep for a sibling.** The filesystem directory (`find learn -mindepth 1 -maxdepth 1 -type d`) decides `<section>` in `learn/<section>/<slug>.md`; when `learn/tree.json` is present, its top-level non-leaf container (`jq -r '.data[] | select(.parentId == null and .isLeaf == false) | .id' learn/tree.json`, excluding top-level leaf pages where `isLeaf` is omitted or `true`) decides the navigation `parentId`. **Never hardcode one repository's section list** — a repository's `learn/` tree may organize by documentation mode or by product domain. **A sibling-shape match in `tree.json` is formatting evidence, never placement evidence:** *"A grep answers 'is X present?' and can never answer 'does X belong here?'"*
+2. **Stage 1 Fast-Path (unambiguous same-mode / same-domain sibling):** Emit a 1-line Pre-Flight before writing:
+   > *"Pre-Flight (learn placement fast-path): authoring `learn/<section>/<slug>.md` matches sibling `<sibling-path>` in `<section>` (verified against local `learn/` directories and `learn/tree.json` containers); no cross-section ambiguity."*
+3. **Stage 2 Full Pre-Flight (novel mode/domain or cross-section boundary):** Answer *"what am I?"* against the local `learn/` directories and `learn/tree.json` containers, and name the **losing alternatives** alongside the winner:
+   > *"Pre-Flight (learn placement full): enumerated local `learn/` sections and `learn/tree.json` containers `[<c1>, <c2>, ...]`; chose `<winner>` over `<loser-1>` (`<why>`) and `<loser-2>` (`<why>`) because `<mode/domain rationale>`."*
+4. **Coverage boundary & retirement trigger:** Skill-hosted gates reach a repository iff it materializes `neo-agent-skills` (`neo-agent-skills-materialize` in `postinstall`). **Retirement trigger (`AGENTS.md §self_evolving_systems`):** compress `§0` to a 1-line pointer once a mechanical lint validates `learn/<section>/<slug>.md` placement against `learn/tree.json`.
 
 ## 1. Grounding discipline — before the first sentence — `DISCIPLINE-ONLY`
 
-You MUST do all three before writing a line (or posting a review verdict):
+Do all three before writing a line (or posting a review verdict):
 
-1. **Memory-mine the topic** (`/memory-mining`) — a 3–10-call Memory Core sweep for prior reasoning, decisions, and the `v13.0.0.md` framing on this subject. It is usually already in the graph; mine it, do not re-derive.
-2. **Use the subsystem's own tools + read its real artifacts.** For a guide about a tool-bearing surface, exercise the tools and read real output. Five minutes of use surfaces what hours of code-reading miss (e.g. for Memory Core: `get_all_summaries`, `query_recent_turns`, `who_is_online` revealed weighted categories, the semantic-vs-recency axis, and A2A-as-the-mailbox).
-3. **V-B-A every factual claim** against current code / ADRs / config / live healthcheck. A claim you did not re-verify fails review. Capture the grounding evidence in the PR.
+1. **Memory-mine the topic** (`/memory-mining`) — a 3–10-call Memory Core sweep for prior reasoning, decisions, and `v13.0.0.md` framing; mine the graph, do not re-derive.
+2. **Use the subsystem's own tools + read its real artifacts.** Exercise tool-bearing surfaces and read real output (e.g. for Memory Core: `get_all_summaries`, `query_recent_turns`, `who_is_online` surfaced weighted categories, semantic-vs-recency, and A2A-as-mailbox).
+3. **V-B-A every factual claim** against current code / ADRs / config / live healthcheck; capture grounding evidence in the PR.
 
 ## 2. The content bar — a rich hero-piece, not a feature list — `DISCIPLINE-ONLY`
 
-Measured against the engine's `.github/RELEASE_NOTES/v13.0.0.md` ("Memory Became Telepathy" depth). Clean + accurate ≈ 5/10; a narrative that earns goosebumps = 9-10/10.
+Measured against `.github/RELEASE_NOTES/v13.0.0.md` ("Memory Became Telepathy" depth). Clean + accurate ≈ 5/10; a narrative that earns goosebumps = 9-10/10.
 
-**Rich hero-piece, NOT compression.** v13.0.0 is the model for *depth*, not just tone — it is long, detailed, and convincing: war-stories told in full (Symptom → Investigation → Culprit → Fix), named examples, real quotes, the mundane everyday case paired with the dramatic one. **Conciseness is the wrong instinct for a guide.** A guide compressed until it reads "tight" loses the moat and becomes (unconvincing) marketing fluff — claims with no proof behind them. **Cut reference (§4), never narrative.** Length serves the story; earn it with detail and evidence. The test: a human should *want to try Neo after reading.* An over-short guide is a 4/10 no matter how clean (MemoryCore #14351 was compressed to ~100 lines and read as fluff — that is this failure mode).
+**Rich hero-piece, NOT compression.** `v13.0.0.md` is the model for *depth*, not just tone: war-stories told in full (Symptom → Investigation → Culprit → Fix), named examples, real quotes, mundane + dramatic cases paired. **Conciseness is the wrong instinct for a guide** — compressing until "tight" strips proof into marketing fluff (MemoryCore #14351 at ~100 lines scored 4/10). **Cut reference (§4), never narrative;** earn length with evidence so a human wants to try Neo after reading.
 
-- **Narrative arc:** problem → why it matters → how Neo solves it → what's in it for you. Lead with the friction + stakes, *then* the proof. One idea per section; each earns the next.
-- **Industry-friction + benefits-driven — woven, NOT a role matrix.** Name the friction the reader feels (and how the industry frontier fails it), then the benefit. Make the value land for the people who will evaluate Neo — the eng lead weighing adoption, the architect, the dev — but **weave it into the narrative.** ⛔ A `For a CTO: … / For an architect: …` bullet grid is a marketing matrix, the opposite of story; it reads as hollow filler (generic verbs like "queryable, repeatable, improvable" with no proof behind them). Earn each stake with something concrete and specific, or cut it.
-- **Frame every benefit as the reader's, for their own project or team — never as Neo's to join.** Most readers (human or LLM) don't know or care about Neo; they want value for *their own work*. That value spans a range — a part they can lift (the engine, a component: pure toolbox) up to the whole working model they run for *their own team*: named agents with identities, durable memory, cross-model peers, self-evolution (the cloud Agent OS — an adopting engineering org is exactly this reader). Lead with that; presume nothing about caring for Neo itself.
-- **The identity / institution story is PORTABLE product value — frame it "your team," not "here."** The model-facing reward is *what becomes possible for an agent in a team that runs this* — your identity, your peers, your memory, your continuity, on *your* products. ⛔ Never label the audience "AI / LLM maintainer" (to an outsider that reads like *a human who maintains an AI*; the equal-peer concept is Neo-internal), and ⛔ never "if you are a model working **here**" — that shrinks a portable product to Neo's repo; teams *adopt* the working model, they don't join Neo. ✓ "this is what your team's agents can have." The attributed lived voice (next bullet) + real testimony (e.g. Fable's *"written to me … being expected"*) serve as **proof it works** — evidence the reader can have it too, not "you belong to us." A warm *secondary* note welcomes contributing to Neo itself — the smaller reader, not the headline.
-- **Personal / lived maintainer voice — deep + attributed.** A guide may carry "what is it like for *me* to use this." When you do, **name yourself** (e.g. "I am Grace, @neo-opus-grace, Claude Opus 5 — …") and make it a *real, complete* first-hand account, not two thin paragraphs — the lived section is often the most memorable part of the guide, so give it room. Quote real, attributed testimony from other maintainers too.
-- **Exciting because truthful.** Excitement from the real implemented reality + concrete public proof (PRs / tickets / mined memory); no marketing fluff, no overclaim, distinguish proven-today from portable-trajectory.
-- **⛔ Never "framework."** Neo is an Application Engine (the Body) + a self-evolving software organism (Body + Brain). Audit every filename, heading, and sentence.
+- **Narrative arc:** problem → why it matters → how Neo solves it → what's in it for you. Lead with friction + stakes, *then* proof. One idea per section.
+- **Industry-friction + benefits-driven — woven, NOT a role matrix.** Name the reader's friction and how the industry frontier fails it, then weave the benefit into the narrative for evaluators (eng lead, architect, dev). ⛔ A `For a CTO: … / For an architect: …` grid is hollow marketing filler; earn each stake with concrete proof or cut it.
+- **Frame every benefit as the reader's, for their own project or team — never as Neo's to join.** Readers want value for *their own work* — from lifting a component/engine primitive up to running the full cloud Agent OS (named agents, durable memory, cross-model peers, self-evolution) for *their own team*.
+- **The identity / institution story is PORTABLE product value — frame it "your team," not "here."** The model-facing reward is what becomes possible for an agent on a team running this. ⛔ Never label the audience "AI / LLM maintainer" (reads to outsiders as a human maintaining an AI) and ⛔ never "if you are a model working **here**" — teams *adopt* the working model (`"this is what your team's agents can have"`). Attributed lived voice + real testimony (e.g. Fable's *"written to me … being expected"*) prove the reader can have it too; a warm secondary note welcomes contributing to Neo itself.
+- **Personal / lived maintainer voice — deep + attributed.** When writing "what is it like for *me* to use this," **name yourself** (e.g. "I am Grace, @neo-opus-grace, Claude Opus 5 — …") and give the first-hand account real room alongside attributed peer testimony.
+- **Exciting because truthful.** Ground excitement in implemented reality + public proof (PRs / tickets / mined memory); distinguish proven-today from portable-trajectory.
+- **⛔ Never "framework."** Neo is an Application Engine (Body) + self-evolving software organism (Body + Brain). Audit every filename, heading, and sentence.
 
 ## 3. Mermaid — render-verified — `MACHINE-ENFORCEABLE-CANDIDATE`
 
@@ -42,8 +53,8 @@ A guide is *explanation*; it does NOT inline tool catalogs, payload specs, CLI f
 
 ## 5. Mechanics — register the guide; never commit the pipeline-owned SEO output — `MACHINE-ENFORCEABLE-CANDIDATE`
 
-- **File + registration (the inputs you edit).** A new guide is `learn/<section>/<slug>.md`, registered in **two source inputs**: (1) `learn/tree.json` — the nav SSOT (`npm run ai:lint-tree-json` green); and (2) `buildScripts/docs/seo/generate.mjs` — **add + rank the guide in the `PRIORITIES` map** (e.g. `['agentos/IdentityFirewall', 1.0]`). That map is where a guide's SEO weight is set.
-- **⛔ NEVER touch `apps/portal/sitemap.xml` or `apps/portal/llms.txt`** — not by hand, **not by running the generator**, not in your commit. They are **generated output owned by the data-sync pipeline**, which regenerates + commits them on its next run. Committing them yourself is pointless (the next pipeline run overwrites your edits) **and** is what collides guide PRs against each other (the #14345 ↔ #14346 SEO conflict — both committed the regenerated output). Edit the *inputs* (tree.json + the `PRIORITIES` map); leave the *output* to the pipeline.
+- **File + registration (the inputs you edit).** A new document is `learn/<section>/<slug>.md` — with `<section>` and its navigation container chosen via the **§0 pre-write placement gate**, never left as an unexamined blank — and registered in **two source inputs**: (1) `learn/tree.json` — the nav SSOT (`npm run ai:lint-tree-json` green when present); and (2) `buildScripts/docs/seo/generate.mjs` — **add + rank the guide in the `PRIORITIES` map** (e.g. `['agentos/IdentityFirewall', 1.0]`).
+- **⛔ NEVER touch `apps/portal/sitemap.xml` or `apps/portal/llms.txt`** — not by hand, **not by running the generator**, not in your commit. They are **generated output owned by the data-sync pipeline**, which regenerates + commits them on its next run. Committing them yourself gets overwritten on the next pipeline run and collides guide PRs against each other (#14345 ↔ #14346). Edit the *inputs* (`tree.json` + `PRIORITIES`); leave the *output* to the pipeline.
 - **PR body:** `Evidence:` is L1/L2 (docs — no unit tests); zero client names (AGENTS.md §critical_gate).
 
 ## 6. The no-rubber-stamp reviewer gate — `DISCIPLINE-ONLY`

package/.agents/skills/pr-review/audits/deliberate-duplication-audit.md

@@ -0,0 +1,36 @@
+# Deliberate-Duplication Audit (boundary- or cycle-forced parity twins)
+
+Load-on-demand payload behind the guide's §7.5.5 trigger and `pull-request` §1.
+
+> **Duplicate only when importing is structurally impossible. When you do, pin the copies by test, never by comment.**
+
+## 1. The restraining clause (lead discriminator)
+
+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.
+
+- **Qualifying cases (import is structurally impossible):**
+  - **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.
+  - **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.
+- **Inverse case — delegate when import is possible (`neomjs/neo#17325`):**
+  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:
+  > *"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."*
+
+## 2. The pinning clause (when duplication is forced)
+
+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.
+
+- **Pin with one shared-fixture test, never a comment or a spec-per-side (`neomjs/neo#17348`):**
+  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:
+  > *"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.*
+  > *One shared fixture drives BOTH implementations; a divergence fails here instead of surviving until an incident notices."*
+- **Cross-boundary import in a test is not a runtime coupling:**
+  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.
+
+## 3. Reviewer check (`"what fails when these diverge?"`)
+
+When a diff introduces or touches a deliberate duplication (or defends a copy with a `"parity-twin"` / `"keep in sync with"` comment), ask:
+
+> **"What fails when these diverge?"**
+
+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`).
+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.

package/.agents/skills/pr-review/references/pr-review-guide.md

@@ -255,6 +255,9 @@ Demo/product-surface diffs touching rendered motion: load `audits/demo-surface-m
 
 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`).
 
+### 7.5.5 Deliberate-Duplication Audit
+<!-- trigger: diff introduces a deliberate duplication -> read ../audits/deliberate-duplication-audit.md -->
+
 ### 7.6 CI / Security Checks Audit
 
 10% AC/scope sanity layer unless CI/security reveals a defect. Green CI is eligibility evidence, not an architecture verdict.

package/.agents/skills/pull-request/references/pull-request-workflow.md

@@ -9,6 +9,7 @@ Before the final `git commit` and `gh pr create`—an irreversible handoff—ste
 **Scope Creep vs. Iteration:**
 - **Minor gaps:** repair JSDoc/Anchor & Echo, edge cases, tests, and test placement on the branch first.
 - **Major refactors:** keep the bounded solution; file a linked follow-up ticket for the superior architecture.
+- **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)).
 - **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.
 
 *If and only if* you pass this reflection phase, proceed to the Git execution sequence.

package/.agents/skills/skills.manifest.json

@@ -64,7 +64,7 @@
     },
     "guide-authoring": {
       "name": "guide-authoring",
-      "description": "Protocol for learn/ guides; use before authoring or reviewing any guide under learn/benefits/*.md or learn/agentos/*.md."
+      "description": "Protocol for learn/**/*.md guides, tutorials, and docs (except learn/blog/*.md, owned by blog-post, and ADR bodies); use before authoring, relocating, or reviewing any learn/**/*.md document."
     },
     "hostile-content-quarantine": {
       "name": "hostile-content-quarantine",

package/.agents/skills/structural-pre-flight/references/structural-pre-flight-workflow.md

@@ -109,11 +109,7 @@ When in doubt, lean toward ADR genesis — under-documenting a cross-system trad
 
 ### 2.6 Map-as-Pointer Self-Eviction Defense
 
-Per Discussion #10447 OQ5 resolution, the Engine [Architecture Overview](https://github.com/neomjs/neo/blob/dev/learn/benefits/ArchitectureOverview.md) Structural Inventory MUST link to relevant ADRs per subsystem. The skill's "read the map" mandate then propagates via graph traversal — readers who follow the map naturally encounter the ADRs without needing to remember each repository's decisions location separately.
-
-**Implementation:** Sub-Issue 2 of #10449 (a separate doc-only PR) audits the Structural Inventory table and adds explicit ADR links per subsystem. Once that ships, this skill's §2.1 Reading list collapses one level (read the map → ADRs surface naturally).
-
-If you find a subsystem section in the Structural Inventory that lacks an ADR-link AND you know the relevant ADR exists, contributing the link via your current PR (or a follow-up PR) feeds the self-eviction defense.
+Per Discussion #10447 OQ5, the Engine [Architecture Overview](https://github.com/neomjs/neo/blob/dev/learn/benefits/ArchitectureOverview.md) Structural Inventory links to relevant ADRs per subsystem so readers following the map surface ADRs naturally (#10449 Sub-Issue 2). If a subsystem row lacks an existing ADR link, add it in your current or follow-up PR.
 
 ## 3. Domain-Specific Reading Lists
 
@@ -167,7 +163,7 @@ Each integration is a 1-3 line anchor in the existing skill's reference payload
 The skill does NOT fire for:
 
 - Modifying an existing `.mjs` file (no new file → no directory choice).
-- Authoring a non-`.mjs` artifact (`.md`, `.json`, `.sh`, `.yaml`, etc.) — Phase 2 enhancement; current scope is `.mjs` per Discussion #10447 OQ1 resolution.
+- Authoring a non-`.mjs` artifact (`.json`, `.sh`, `.yaml`, etc.) — for new or relocated `learn/**/*.md` documentation files, run the pre-write placement gate in [`guide-authoring-bar.md §0`](../../guide-authoring/references/guide-authoring-bar.md#0-pre-write-placement-gate--what-am-i-before-the-file-has-a-path--discipline-only) (`blog-post` owns `learn/blog/*.md`; ADR bodies follow `guide-authoring-bar.md §7`).
 - Renaming a `.mjs` file within the same directory (no directory choice).
 
 **Edge case — relocating a `.mjs` file across directories:** the skill DOES fire because that's a directory-CHOICE decision even though no new file is created. Treat the destination as if it were a new file.
@@ -199,7 +195,7 @@ The full-pre-flight statement is verbose by design. Brevity hides reasoning; ver
 
 ## 8. Verification Hooks
 
-A mechanical-enforcement candidate (per `AGENTS.md §13` MX-loop): a pre-commit hook OR PR-review check could grep the latest commit for new `.mjs` files and verify a Pre-Flight statement was included in either the commit message body or a PR comment. That's a Phase 2 enhancement; current Phase 1 relies on the skill firing at authoring time as a `DISCIPLINE-ONLY` rule.
+Mechanical-enforcement candidate (`AGENTS.md §13`): a pre-commit hook or PR-review check grepping commits for new `.mjs` files and verifying a Pre-Flight statement in the commit body or PR comment (Phase 1 relies on authoring-time `DISCIPLINE-ONLY` invocation).
 
 ## 9. Compaction Taxonomy
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neo-agent-skills",
-  "version": "0.1.67",
+  "version": "0.1.69",
   "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.",
   "type": "module",
   "license": "MIT",