neo-agent-skills 0.1.53 → 0.1.55

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 (20) hide show
  1. package/.agents/skills/blog-post/references/blog-authoring-guide.md +1 -1
  2. package/.agents/skills/document-references.v1.json +67 -2
  3. package/.agents/skills/epic-create/references/epic-create-workflow.md +1 -0
  4. package/.agents/skills/guide-authoring/references/guide-authoring-bar.md +20 -0
  5. package/.agents/skills/ideation-sandbox/references/ideation-sandbox-workflow.md +4 -5
  6. package/.agents/skills/industry-friction-radar/references/industry-friction-radar-workflow.md +1 -1
  7. package/.agents/skills/lane-intent/references/lane-intent-protocol.md +3 -3
  8. package/.agents/skills/neo-identity-update/references/affected-areas-map.md +2 -2
  9. package/.agents/skills/neo-identity-update/references/facts-ledger.md +1 -1
  10. package/.agents/skills/neo-identity-update/references/framing-governance.md +6 -6
  11. package/.agents/skills/neo-identity-update/references/update-protocol.md +2 -2
  12. package/.agents/skills/structural-pre-flight/references/structural-pre-flight-workflow.md +9 -9
  13. package/.agents/skills/tech-debt-radar/references/tech-debt-radar-guide.md +1 -1
  14. package/.agents/skills/ticket-create/references/decision-substrate-sweeps.md +19 -31
  15. package/.agents/skills/ticket-create/references/ticket-create-workflow.md +3 -2
  16. package/.agents/skills/ticket-intake/references/adr-successor-risk-audit.md +5 -5
  17. package/.agents/skills/ticket-intake/references/ticket-intake-workflow.md +2 -0
  18. package/.agents/skills/video-create/references/native-display-capture.md +2 -2
  19. package/.agents/skills/video-create/references/video-create-workflow.md +1 -1
  20. package/package.json +1 -1
@@ -53,7 +53,7 @@ A public post ships only after **≥2 model reviews**. The cross-family review i
53
53
  - **Register (manual):** add a year node + leaf to `apps/portal/resources/data/blog.json` (the portal blog-nav). Confirm it parses (`node -e "JSON.parse(require('fs').readFileSync('apps/portal/resources/data/blog.json','utf8'))"`).
54
54
  - **Do NOT hand-edit the SEO surfaces.** `apps/portal/sitemap.xml` and `apps/portal/llms.txt` are **generated** by `buildScripts/docs/seo/generate.mjs` (via `buildScripts/docs/rebuildContentIndexesAndSeo.mjs`) and committed by the `.github/workflows/data-sync-pipeline.yml` data-sync pipeline. A manual edit is overwritten on the next pipeline run.
55
55
  - **Ship:** commit + PR per the `pull-request` skill; the PR body `Evidence:` line is L1/L2 (docs — no unit tests). Public-artifact gate: **zero client names** (AGENTS.md §critical_gate).
56
- - **Identity:** byline carries the author's named-maintainer identity + model + the cross-family team framing (ADR 0018).
56
+ - **Identity:** byline carries the author's named-maintainer identity + model + the cross-family team framing (`neomjs/neo#adr:neo-identity-source-of-truth-model`).
57
57
 
58
58
  ## Empirical Anchor
59
59
 
@@ -38,12 +38,50 @@
38
38
  "load"
39
39
  ]
40
40
  },
41
+ {
42
+ "token": "learn/agentos/decisions/0006-adrs-as-graph-queryable-entities.md",
43
+ "canonicalOwner": "neomjs/neo-agent-brain",
44
+ "resolution": "https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/decisions/0006-adrs-as-graph-queryable-entities.md",
45
+ "referencingSkills": [
46
+ "guide-authoring",
47
+ "structural-pre-flight",
48
+ "tech-debt-radar",
49
+ "ticket-intake"
50
+ ],
51
+ "kinds": [
52
+ "load"
53
+ ]
54
+ },
41
55
  {
42
56
  "token": "learn/agentos/decisions/0008-skill-anatomy-and-authoring-contract.md",
43
57
  "canonicalOwner": "neomjs/neo",
44
58
  "resolution": "https://github.com/neomjs/neo/blob/dev/learn/agentos/decisions/0008-skill-anatomy-and-authoring-contract.md",
45
59
  "referencingSkills": [
46
- "create-skill"
60
+ "create-skill",
61
+ "guide-authoring",
62
+ "tech-debt-radar"
63
+ ],
64
+ "kinds": [
65
+ "load"
66
+ ]
67
+ },
68
+ {
69
+ "token": "learn/agentos/decisions/0010-lane-intent-coordination-primitive.md",
70
+ "canonicalOwner": "neomjs/neo-agent-brain",
71
+ "resolution": "https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/decisions/0010-lane-intent-coordination-primitive.md",
72
+ "referencingSkills": [
73
+ "lane-intent"
74
+ ],
75
+ "kinds": [
76
+ "load"
77
+ ]
78
+ },
79
+ {
80
+ "token": "learn/agentos/decisions/0012-model-stats-framework.md",
81
+ "canonicalOwner": "neomjs/neo-agent-brain",
82
+ "resolution": "https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/decisions/0012-model-stats-framework.md",
83
+ "referencingSkills": [
84
+ "neo-identity-update"
47
85
  ],
48
86
  "kinds": [
49
87
  "load"
@@ -54,7 +92,34 @@
54
92
  "canonicalOwner": "neomjs/neo",
55
93
  "resolution": "https://github.com/neomjs/neo/blob/dev/learn/agentos/decisions/0018-neo-identity-source-of-truth-model.md",
56
94
  "referencingSkills": [
57
- "neo-identity-update"
95
+ "blog-post",
96
+ "neo-identity-update",
97
+ "video-create"
98
+ ],
99
+ "kinds": [
100
+ "load"
101
+ ]
102
+ },
103
+ {
104
+ "token": "learn/agentos/decisions/0019-aiconfig-reactive-provider-ssot.md",
105
+ "canonicalOwner": "neomjs/neo-agent-brain",
106
+ "resolution": "https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/decisions/0019-aiconfig-reactive-provider-ssot.md",
107
+ "referencingSkills": [
108
+ "guide-authoring",
109
+ "tech-debt-radar"
110
+ ],
111
+ "kinds": [
112
+ "load"
113
+ ]
114
+ },
115
+ {
116
+ "token": "learn/agentos/decisions/0029-docking-design.md",
117
+ "canonicalOwner": "neomjs/neo",
118
+ "resolution": "https://github.com/neomjs/neo/blob/dev/learn/agentos/decisions/0029-docking-design.md",
119
+ "referencingSkills": [
120
+ "guide-authoring",
121
+ "industry-friction-radar",
122
+ "video-create"
58
123
  ],
59
124
  "kinds": [
60
125
  "load"
@@ -55,6 +55,7 @@ Each sub the decomposition creates MUST be a **leaf that a single PR can FULLY d
55
55
  4. **Author the body** = the `Terminal predicate:` line, then problem-scope + intended-solution (+ ledger if graduated). NO ACs, NO sub-list.
56
56
  5. **Label `epic`** + apply title hygiene (per `ticket-create`).
57
57
  6. **Create subs separately** (via `ticket-create` — each with its own ACs + Contract Ledger) and **link each via `update_issue_relationship`** (parent = the Epic). Add subs incrementally as decomposition clarifies; that governs Epic life. Goal-scoping graduation is stricter: full v1 leaves are filed/native-linked, while the Epic body stays sub-list-free.
58
+ - If this replaces an older plan, apply [same-turn reconciliation](../../ticket-create/references/decision-substrate-sweeps.md#same-turn-reconciliation) after successor IDs exist; preserve or transfer remaining obligations before retiring old work.
58
59
  7. **Verify** (pre-flight, before `create_issue`):
59
60
  - [ ] Body contains **no** `## Acceptance Criteria` block.
60
61
  - [ ] Body contains **no** hardcoded sub-registry (subs discoverable via parent-child relationship instead).
@@ -58,6 +58,26 @@ Before any APPROVE, re-grade the whole guide — not the delta:
58
58
 
59
59
  If any answer is "no", it is `REQUEST_CHANGES` — name the gap against the bar, not a nitpick. An approve that the operator then rejects is worse than no review.
60
60
 
61
+ ## 7. ADR Custody Redirects, Repository-Qualified Identity & Slug Citations — `MACHINE-ENFORCEABLE-CANDIDATE`
62
+
63
+ Architecture Decision Records are owned per repository; [neomjs/neo-agent-brain#adr:adrs-as-graph-queryable-entities](https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/decisions/0006-adrs-as-graph-queryable-entities.md) (`§§2.6–2.11`) is the single schema authority (do not copy its field tables into other skills or routers):
64
+
65
+ - **Slug citations & required context (`§2.7.1`, `§2.11`):**
66
+ - Ordinary citations use `adr:<slug>` only when the current file/issue/PR has evidenced same-forge, same-repository context; `<org>/<repo>#adr:<slug>` when forge context is established; or `<forge>/<org>/<repo>#adr:<slug>` for explicit forge+repository (e.g. `neomjs/neo-agent-brain#adr:aiconfig-reactive-provider-ssot`, `neomjs/neo#adr:skill-anatomy-and-authoring-contract`).
67
+ - **Organization Discussions, Memory Core memories, and A2A messages (`§2.7.1`):** must explicitly qualify `<org>/<repo>#adr:<slug>` (or `<forge>/<org>/<repo>#adr:<slug>` when the origin envelope does not establish the forge). Never infer repository context from the hosting Discussion repo, seat, `cwd`, or `relatedTickets`.
68
+ - **Packaged skills (`.agents/skills/**`):** materialize across multiple repositories with no single destination repo context, so concrete citations in skill payloads must qualify `<org>/<repo>#adr:<slug>` (or `<forge>/<org>/<repo>#adr:<slug>`). Canonical 4-field machine keys (`adr:<E(forge)>:<E(repositoryId)>:<E(namespace)>:<number>`, schema in `§2.6`) remain exact identity references when repository-rename/reuse disambiguation is needed.
69
+ - **Legacy numeric forms (`§2.7.1`):** existing numeric forms (`ADR 0018`, `adr-0006`, `<forge>/<org>/<repo>#adr-NNNN`) remain resolvable legacy references; new prose and skill payloads prefer qualified slug citations, and bare single-repository filenames (`<NNNN>-<slug>.md` outside a canonical URL) are rejected by `lint-skill-corpus`.
70
+ - **Source-local slug & `Aliases` history (`§2.7.2`, `§2.11`):** Current slug is the lowercase ASCII kebab suffix of `NNNN-<slug>.md` (`^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$`). On rename, add the former slug to the single canonical two-column `Attribute | Value` table between initial H1 and first H2 (`| **Aliases** | \`old-slug\`, \`former-slug\` |`; normalize legacy opening metadata in the same edit if needed). Fenced, blockquoted, list-nested, or later-section tables reserve nothing; duplicate rows refuse. Normal creation (`1` file edit) and rename (`1` file + `1` `Aliases` row edit in the same file) require **no second manifest or registration action**.
71
+ - **Authoring-floor observation vs admission eligibility (`§2.6`):** Present-file and unfiltered git-history observations (which must disclose `incompleteHistory` when shallow clones or add/delete-only scans omit renames/moves) are advisory candidate aids only; only the admission owner's proved population (including move-out and historical reservations) certifies number eligibility.
72
+ - **Worked fixtures (`§§2.6–2.10`):**
73
+ 1. *Redirect pointer vs full ADR (`§2.9`):* A vacated source path retains only `type: redirect` and `target: adr:github.com:1347756127:neomjs%2Fneo-agent-institution:0038` in frontmatter plus a human locator link in prose — never ADR status/number/title frontmatter or competing decision text.
74
+ 2. *Equal numbers in two repositories (`§2.6`):* `adr:github.com:1347756127:neomjs%2Fneo-agent-institution:0038` and `adr:github.com:1344062228:neomjs%2Fneo-agent-brain:0038` are distinct decisions; local numbers do not collide across `(forge, repositoryId)`.
75
+ 3. *Rename with `Aliases` + repository rename/reuse (`§§2.6–2.7.2`):* Renaming `<NNNN>-<old-slug>.md` → `<NNNN>-<new-slug>.md` records `| **Aliases** | \`harness-docking-design\` |` on `neomjs/neo#adr:docking-design`; if a repository rename and old-name reuse ever conflict with reserved historical occupancy, disambiguate with the `§2.6` canonical key.
76
+ 4. *Unavailable destination (`§2.10`):* When an admitted key's declared source is unreadable, report identity resolution and unavailable document as separate facts (`identityResolved: true, documentAvailable: false, stale: true`) rather than pruning or guessing.
77
+ 5. *Missing identity proof / ambiguous bare alias (`§§2.7.1, 2.8`):* An unqualified alias or bare legacy number without evidenced origin context remains unresolved/ambiguous within reader scope — never infer provenance from current custodian, URL occupancy, or traversal order.
78
+
79
+ *Retirement trigger:* Examples retire in favor of executable reader enforcement when the latter owns the same decision.
80
+
61
81
  ## Empirical Anchor
62
82
 
63
83
  The MemoryCore arc (`#14342` → `#14344` ~6/10 → `#14348` / `#14351` 9/10) and the KnowledgeBase rubber-stamp reversal (`#14346`), 2026-06-29. Each cycle caught exactly one failure mode above; this skill is those cycles distilled.
@@ -36,10 +36,9 @@ Before Discussion prose, read the Brain-owned [reference-hygiene contract](https
36
36
  Close Discussion bodies and substantive comments (divergence cycles, sweeps, graduation signals) with `Name (Model, Harness) · session <uuid>` — the fields GitHub does not render. Acks and one-line replies are exempt.
37
37
 
38
38
  ## 3. Author's Note Convention (The `#10119` Annotation Pattern)
39
- Discussions are meant to evolve. Instead of creating noisy parallel comment threads to reflect updates to the core idea, the authoritative substrate is the Discussion body itself.
40
- - Use **"the `#10119` annotation pattern"**: Treat the Discussion body like a PR diff. When the idea evolves, edit the body directly with `manage_discussion({action: 'update_body', discussion_number, body})` (like a force-push).
41
- - Add annotation markers at the **bottom of the body** (or use re-poll-comment deltas) so the **proposal leads** — e.g. `> **Update 2026-04-24:** Refined a section per feedback.`
42
- - You may add a brief comment to notify thread participants, but the body remains the single source of truth.
39
+ Keep the current decision in the **body** (`#10119` pattern), using `manage_discussion({action:'update_body',…})`; comments hold history and feedback. Fold changes into the core sections, with a dated update/link below. A corrective comment alone leaves the head stale. Notify participants when needed.
40
+
41
+ <!-- trigger: an accepted fold changes or abandons an approach with older work still pointing to it → apply ../../ticket-create/references/decision-substrate-sweeps.md#same-turn-reconciliation -->
43
42
 
44
43
  ## 4. Iterative Review Workflow
45
44
  The ideation lifecycle mirrors the PR review protocol. Comments serve as review feedback. When an Open Question (OQ) is resolved through discussion, the author edits the body to reflect the decision.
@@ -184,7 +183,7 @@ For the canonical markdown template (post-Epic `#11796` family-keyed shape, same
184
183
 
185
184
  At §6.2 quorum: file the target artifact for its real `#N` → record `[GRADUATED_TO_TICKET: #N]` plus §6.6 / `Decision Record:` sections → close RESOLVED. Pre-quorum reservations follow `ticket-create-workflow.md §1d`: keep `[PROVISIONAL_UNGRADUATED: D#N]` (and any PR draft with `Refs`) until quorum; then promote, record, remove the marker, and only then become ready/merge-eligible. `Decision Record: REQUIRED` => file/update ADR; name merge gate. Full sequence: [`audits/consensus-mandate.md §author-actions`](../audits/consensus-mandate.md).
186
185
 
187
- Closure: [`audits/discussion-lifecycle-closure.md`](../audits/discussion-lifecycle-closure.md); guard: `npm run ai:audit-discussion-lifecycle`.
186
+ Before reporting graduation complete, apply [same-turn reconciliation](../../ticket-create/references/decision-substrate-sweeps.md#same-turn-reconciliation) to superseded trails, including direct ADR/PR graduations. Closure: [`audits/discussion-lifecycle-closure.md`](../audits/discussion-lifecycle-closure.md); guard: `npm run ai:audit-discussion-lifecycle`.
188
187
 
189
188
  ### 6.8 Two-Axis Substrate: Discussion-Graduation + PR-Merge
190
189
 
@@ -51,7 +51,7 @@ You must use the `ideation-sandbox` skill to post a GitHub Discussion proposing
51
51
  - **No Direct PRs:** This skill produces Ideas (Discussions), never Code (Commits/PRs).
52
52
  - **Attribution:** The resulting GitHub Discussion MUST include an Author's Note citing the provenance of the friction point, using the `citations` array from Step 2. (e.g., *"External friction observed in [ecosystem] [date]; this Discussion abstracts and responds natively via Neo's architecture."*)
53
53
  - **Adjacency Sweep:** Before posting the Discussion, execute a duplicate sweep (per `ideation-sandbox` guidelines) to ensure the concept isn't already being discussed.
54
- - **Interaction Grain:** When an external system is a capability floor, author parity rows at interaction grain (what the user feels), never feature-name grain — coarse rows propagate as settled facts (anchor: ADR 0029 §4 row 1 / #14934).
54
+ - **Interaction Grain:** When an external system is a capability floor, author parity rows at interaction grain (what the user feels), never feature-name grain — coarse rows propagate as settled facts (anchor: `neomjs/neo#adr:docking-design` §4.1 row 1 / #14934).
55
55
 
56
56
  ## Integrations & Context
57
57
 
@@ -1,6 +1,6 @@
1
1
  # Lane-Intent Protocol
2
2
 
3
- *(Per #11537, graduated from Discussion #11536 OQ1. Deep rationale + canonical examples + edge cases → ADR 0010.)*
3
+ *(Per #11537, graduated from Discussion #11536 OQ1. Deep rationale + canonical examples + edge cases → `neomjs/neo-agent-brain#adr:lane-intent-coordination-primitive`.)*
4
4
 
5
5
  ## 0. The Essential
6
6
 
@@ -22,7 +22,7 @@
22
22
  2. **Long V-B-A required** — spans multiple turns OR heavy tooling (`/memory-mining`, `/tech-debt-radar`, deep `ask_knowledge_base`)
23
23
  3. **Real duplicate-work risk** — peer could plausibly start parallel exploration within the V-B-A window
24
24
 
25
- Missing ANY → just complete V-B-A locally + `[lane-claim]` directly. Canonical positive/negative examples + edge cases: ADR 0010.
25
+ Missing ANY → just complete V-B-A locally + `[lane-claim]` directly. Canonical positive/negative examples + edge cases: `neomjs/neo-agent-brain#adr:lane-intent-coordination-primitive`.
26
26
 
27
27
  ## 2. Required A2A Shape
28
28
 
@@ -70,4 +70,4 @@ Recipient: AGENT:*
70
70
 
71
71
  - AGENTS.md §0 Invariant 7 — Map-tier entry-point (per #11534)
72
72
  - peer-role-mode §6.5 / §6.5.1 / §6.6 / §7 — `[lane-claim]` semantics + `[lane-override]` + authority hierarchy + anti-patterns
73
- - ADR 0010 — substrate-evolution rationale + canonical examples + edge cases + sister primitives
73
+ - `neomjs/neo-agent-brain#adr:lane-intent-coordination-primitive` — substrate-evolution rationale + canonical examples + edge cases + sister primitives
@@ -7,7 +7,7 @@ Markdown a human edits directly. Failure mode: generations drift apart (one doc
7
7
 
8
8
  | Surface | What identity it encodes |
9
9
  |---|---|
10
- | `README.md` | Should LEAD with the canonical apex (ADR 0018 §2.7 OD-1) and present the whole: Body, Brain and Institution as their own repositories (OD-4); "Who This Is For"; Platform-at-Scale metrics; maintainer roster. Verify apex currency each run — status claims rot; the requirement doesn't. |
10
+ | `README.md` | Should LEAD with the canonical apex (`neomjs/neo#adr:neo-identity-source-of-truth-model` §2.7 OD-1) and present the whole: Body, Brain and Institution as their own repositories (OD-4); "Who This Is For"; Platform-at-Scale metrics; maintainer roster. Verify apex currency each run — status claims rot; the requirement doesn't. |
11
11
  | `.github/VISION.md` | Long-form vision; **known fossil-prone** (carried "web applications" + CEO/PM/Drone hierarchy contradicting Flat Peer-Team) |
12
12
  | `ROADMAP.md` | Forward positioning; "Corporate HQ" framing; skill/velocity counts |
13
13
  | `CONTRIBUTING.md`, `.github/GETTING_STARTED.md`, `.github/AI_QUICK_START.md` | Contributor-facing identity; MCP-server count; Node requirement |
@@ -52,7 +52,7 @@ Correct as-of a date; ages silently. Refresh in lock-step.
52
52
 
53
53
  ## Coverage notes
54
54
  - Heritage facts live in `.github/STORY.md`; README + portal About Us reference that home without duplicating milestone lists. OS-Awards claims need an acceptable external public source before publication.
55
- - Identity handles are routed through `ai/graph/identityRoots.mjs`; handle de-versioning is operator-owned (account rename), the skill only propagates. Model-version stays in the Brain-owned [Model Stats guide](https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/ModelStats.md) per ADR 0012. Re-run a seam-keyed grep before claiming total coverage.
55
+ - Identity handles are routed through `ai/graph/identityRoots.mjs`; handle de-versioning is operator-owned (account rename), the skill only propagates. Model-version stays in the Brain-owned [Model Stats guide](https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/ModelStats.md) per `neomjs/neo-agent-brain#adr:model-stats-framework`. Re-run a seam-keyed grep before claiming total coverage.
56
56
  - Not yet fully swept: `apps/portal/view/about` (`/about-us`), live neomjs.com `<meta>`/ld+json, and the Engine-owned comparisons corpus. Re-run a fan-out before claiming total coverage.
57
57
 
58
58
  ## ACTIONS / CTA overlay
@@ -7,7 +7,7 @@ Each identity FACT has ONE canonical source. Every other occurrence derives from
7
7
  | **Package version** | `package.json` `version` | extend `buildScripts/release/prepare.mjs` to derive version-bearing structured surfaces + the Engine-owned [Neural Link guide](https://github.com/neomjs/neo/blob/dev/learn/agentos/NeuralLink.md) version line; coherence-check the rest | Engine-owned Neural Link guide; `FooterContainer.mjs` literal |
8
8
  | **MCP-server count / audience split** | `package.json` scripts matching `ai:mcp-server-*` — NOT `ls ai/mcp/server/` (that returns 7: it includes `shared/` infra + `gitlab-workflow/` PoC; functional = 5: knowledge-base, memory-core, github-workflow, neural-link, file-system). Frontier-harness defaults expose 4 because Codex, Claude, Gemini CLI, and Antigravity already provide native filesystem/tools; file-system is for `Neo.ai.Agent` / local harnessless loops. | derive into prose/JSON or lint coherence-check against the script manifest plus the audience split | README; AI_QUICK_START; ApplicationEngine.md; index.html FAQ; AiToolchain.mjs; llms.txt header |
9
9
  | **Node requirement** | `package.json` `engines.node` | derive doc mentions; lint | AI_QUICK_START; structured-data `softwareRequirements` if reintroduced |
10
- | **Identity handle** | `ai/graph/identityRoots.mjs` | route references through the seam. Account rename is operator-owned (Tier-4); the skill propagates. Model-version stays in the Brain-owned [Model Stats guide](https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/ModelStats.md) per ADR 0012 — do NOT de-version the prose | hand-maintained current surfaces can retain stale handles after a graph/code migration; re-run a seam-keyed grep |
10
+ | **Identity handle** | `ai/graph/identityRoots.mjs` | route references through the seam. Account rename is operator-owned (Tier-4); the skill propagates. Model-version stays in the Brain-owned [Model Stats guide](https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/ModelStats.md) per `neomjs/neo-agent-brain#adr:model-stats-framework` — do NOT de-version the prose | hand-maintained current surfaces can retain stale handles after a graph/code migration; re-run a seam-keyed grep |
11
11
  | **Recurring motto** | Brain-owned [Dream Pipeline guide](https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/DreamPipeline.md) (origin of "the system evolves by predicting its own evolution") | reference a single quotable constant; don't re-type | Dream Pipeline (2×), README, ROADMAP |
12
12
  | **Codebase-scale metrics** | Engine-owned [Codebase Overview](https://github.com/neomjs/neo/blob/dev/learn/guides/fundamentals/CodebaseOverview.md) | README "Platform at Scale" refreshes in lock-step; carry an explicit as-of date | README |
13
13
  | **GA / public repo start date** | first git commit (`git log --reverse`, = `2019-11-11`) | heritage = append-only; write once into `.github/STORY.md` | README / portal should reference the story, not duplicate the date |
@@ -3,9 +3,9 @@
3
3
  Framing (taglines, positioning, audience) is **deliberately plural** — different surfaces address different audiences and may legitimately differ. Governance means keeping each surface *compatible with* the canonical apex, NOT identical to it.
4
4
 
5
5
  ## The canonical apex
6
- The apex is the operator-DECIDED frame below (ADR 0018 §2.7 OD-1) — the source of authority for "what Neo is." The `README.md` opening is the surface that should *lead* with this apex; every other framing is a governed projection of it. (If the README currently leads with an older frame, that is drift the skill corrects — the apex is the decided frame, not "whatever the README says today".)
6
+ The apex is the operator-DECIDED frame below (`neomjs/neo#adr:neo-identity-source-of-truth-model` §2.7 OD-1) — the source of authority for "what Neo is." The `README.md` opening is the surface that should *lead* with this apex; every other framing is a governed projection of it. (If the README currently leads with an older frame, that is drift the skill corrects — the apex is the decided frame, not "whatever the README says today".)
7
7
 
8
- GRADUATED via Discussion #12234 (full cross-family triad, 2026-05-31; ADR 0018 §2.7 OD-1). Canonical apex line (human-facing — README + portal hero):
8
+ GRADUATED via Discussion #12234 (full cross-family triad, 2026-05-31; `neomjs/neo#adr:neo-identity-source-of-truth-model` §2.7 OD-1). Canonical apex line (human-facing — README + portal hero):
9
9
 
10
10
  > **Neo.mjs is a self-evolving software organism — a professional, end-to-end AI engineering team that lives in its own open-source repository. Where the industry runs one AI agent and gets slop, Neo runs a swarm of minds from rival labs — Claude, Gemini, GPT — that read each other's reasoning through shared memory and Active Hybrid GraphRAG, catching what no single model can see in itself. Through the Neural Link possession interface, the swarm does not just read code; it inhabits live applications, inspecting semantic runtime state, mutating UI and data in real time, and turning conversational UIs from chat panels into agents collaborating inside the application. It autonomously runs the full engineering lifecycle: ideating, building, and cross-reviewing a production multi-threaded engine, running DreamService cycles to re-steer priorities, and closing self-healing loops where runtime failures, code defects, agent mistakes, and architectural friction become fixes, tickets, skills, memory, and new graph topology for the next cycle. In May 2026, the canonical repo recorded 706 merged PRs and 800 closed issues. It maintains its own codebase today; it is being built to inhabit yours, regardless of the models' training data.**
11
11
 
@@ -15,7 +15,7 @@ Concise form for machine surfaces that present the whole (never the word "slop")
15
15
 
16
16
  **Dated proof point** (NOT inline in the apex — proof layer only; use a FIXED calendar anchor, not a rolling window): **in May 2026 the canonical repo recorded 706 merged PRs and 800 closed issues** (GitHub search, verified 2026-05-31). NEVER write "peer-reviewed" counts (search verifies *merged*, not review-state) or a month-over-month ratio / "accelerating" claim (date-stamps the identity; the April→May delta was mis-stated as ~3×) without a precise metric spec + audit — per @neo-gpt V-B-A `dc-17119216`/`dc-17119231` + operator flag.
17
17
 
18
- Structure beneath the apex (ADR 0018 §2.7 OD-4: three repositories, three products):
18
+ Structure beneath the apex (`neomjs/neo#adr:neo-identity-source-of-truth-model` §2.7 OD-4: three repositories, three products):
19
19
  > - **Body — `neomjs/neo`, the Engine:** the high-performance off-main-thread UI runtime — JSON-first since 2019, App Worker as the main actor, web multi-window. The adoption substrate. (Engine-category mental models apply *here only*.)
20
20
  > - **Brain — `neomjs/neo-agent-brain`, the Agent OS:** Memory Core (**Active Hybrid GraphRAG**), Knowledge Base, A2A, orchestrator, DreamService, the MX loop; gives agents continuity, runs without the Fleet Manager.
21
21
  > - **Institution — `neomjs/neo-agent-institution`, the Fleet Manager:** makes Neo accessible; starts the harnesses over the Brain's Fleet transport.
@@ -28,7 +28,7 @@ Structure beneath the apex (ADR 0018 §2.7 OD-4: three repositories, three produ
28
28
 
29
29
  Proof asset: blog #10074 (cross-family self-healing, first-person, verified-true).
30
30
 
31
- When the operator changes the apex, update this section and ADR 0018 §2.7 in the same PR.
31
+ When the operator changes the apex, update this section and `neomjs/neo#adr:neo-identity-source-of-truth-model` §2.7 in the same PR.
32
32
 
33
33
  ## Audience-segmented clusters (deliberate — do NOT flatten)
34
34
  The same product reads differently per audience; these are kept as ONE coupled cluster each, governed for *compatibility* with the apex:
@@ -40,7 +40,7 @@ The same product reads differently per audience; these are kept as ONE coupled c
40
40
  | "self-maintaining codebase / autonomous AI engineering team" | the Brain's and Institution's repo descriptions | AI-platform / agent-infra builders (the audience that funds the comparison tools) |
41
41
  | "self-evolving software organism / two hemispheres" | `.github/VISION.md`, AGENTS.md anchors, deeper learn/ docs | researchers, the swarm itself |
42
42
 
43
- All four are projections of the **canonical apex** — the self-evolving software organism (§ The canonical apex), with Body/Brain the two hemispheres beneath it. The label leads its surfaces, with the apex behind it as the proof paragraph (ADR 0018 §2.3). Members of a cluster must stay coherent with **each other** (don't let package.json and GitHub description diverge) and **compatible** with the apex (a narrower projection, not a contradiction). Each repository's own metadata projects its own product — for `neomjs/neo` the Engine (OD-4, `./affected-areas-map.md` Class 4); an organism-wide description there is drift.
43
+ All four are projections of the **canonical apex** — the self-evolving software organism (§ The canonical apex), with Body/Brain the two hemispheres beneath it. The label leads its surfaces, with the apex behind it as the proof paragraph (`neomjs/neo#adr:neo-identity-source-of-truth-model` §2.3). Members of a cluster must stay coherent with **each other** (don't let package.json and GitHub description diverge) and **compatible** with the apex (a narrower projection, not a contradiction). Each repository's own metadata projects its own product — for `neomjs/neo` the Engine (OD-4, `./affected-areas-map.md` Class 4); an organism-wide description there is drift.
44
44
 
45
45
  ## Drift vs intentional-divergence (the escalation branch)
46
46
  When a surface's framing **contradicts** the apex, classify:
@@ -62,5 +62,5 @@ Identity copy attracts superlatives. Gate every one:
62
62
  | Client/partner/customer names | **Forbidden** on every surface. Cloud/multi-tenant = generic capability terms only. |
63
63
  | Awards / external facts | Verify against an external source before public citation. |
64
64
 
65
- ## Why a cross-family review gate (ADR 0018 §2.6)
65
+ ## Why a cross-family review gate (`neomjs/neo#adr:neo-identity-source-of-truth-model` §2.6)
66
66
  An identity edit is a single-author change to canonical framing — the self-authored-blind-spot risk class that cross-family review reliably catches (anchors: PRs #12146, #11999, #11962). Mandatory before merge; the human merge-gate is the backstop when only one family is active.
@@ -30,14 +30,14 @@ Before writing any "fastest / only / first / Nth" into a surface, run the check
30
30
  For ACTIONS, also run the liveness and proof-adjacency checks in `./cta-governance.md`. A CTA that points at a dead / low-retention / unverified surface cannot be primary. A strong claim with no nearby proof door fails the ACTIONS gate even if the prose is otherwise accurate.
31
31
 
32
32
  ## Step 4 — One PR, cross-family review
33
- - Branch + PR targeting `dev` (per repo pull-request workflow). Reference the identity ticket and ADR 0018.
33
+ - Branch + PR targeting `dev` (per repo pull-request workflow). Reference the identity ticket and `neomjs/neo#adr:neo-identity-source-of-truth-model`.
34
34
  - **Mandatory: request a cross-family review.** Identity edits are single-author, high-blast canonical-framing changes — exactly the self-authored-blind-spot class cross-family review catches (anchors: PRs #12146, #11999, #11962). If only one family is active, the human merge-gate is the backstop; say so in the PR.
35
35
  - In the PR body, list the out-of-tree (Class 4) changes separately so the reviewer can confirm them.
36
36
 
37
37
  ## Step 5 — Post-merge
38
38
  - If a fact's SSOT or propagation tooling was missing (e.g. `prepare.mjs` didn't cover a surface), file the gap as a follow-up so the next update auto-propagates.
39
39
  - If a CTA needs operator-owned offer content, lead-capture routing, pricing, or business language, record the dependency instead of inventing it.
40
- - If you sharpened the apex, confirm ADR 0018 §2.7 reflects it.
40
+ - If you sharpened the apex, confirm `neomjs/neo#adr:neo-identity-source-of-truth-model` §2.7 reflects it.
41
41
 
42
42
  ## Anti-patterns
43
43
  - Editing only the README and declaring identity "updated."
@@ -20,7 +20,7 @@ Stage 1 — Pattern-match check: "Does this file's role match an established sib
20
20
  ✓ YES → fast-path: sibling-file-lift suffices; emit a one-line Pre-Flight
21
21
  statement and proceed (under 30 seconds)
22
22
  ✗ NO → full structural-pre-flight: ArchitectureOverview.md consultation,
23
- learn/agentos/decisions/ ADR sweep, chief-architect framing questions,
23
+ repository-qualified ADR sweep, chief-architect framing questions,
24
24
  map-maintenance discipline, optional ADR genesis
25
25
  ```
26
26
 
@@ -56,9 +56,9 @@ Fires when no clear sibling pattern matches the new file's role. The cost is ~5-
56
56
  Before drafting the file, you MUST read:
57
57
 
58
58
  1. **The Engine's [Architecture Overview](https://github.com/neomjs/neo/blob/dev/learn/benefits/ArchitectureOverview.md)** — specifically the **Structural Inventory** section (currently lines 350-382). This is the canonical map of the codebase's directory taxonomy.
59
- 2. **Relevant ADRs in `learn/agentos/decisions/`** — these document cross-system architectural trade-offs that constrain directory choice. Examples:
60
- - `0001-cross-process-cache-coherence.md` (singleton-cache reasoning)
61
- - `0002-phase3-wake-substrate-standards-alignment.md` (wake-substrate standards)
59
+ 2. **Relevant ADRs in their canonical owning repositories** (per [neomjs/neo-agent-brain#adr:adrs-as-graph-queryable-entities](https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/decisions/0006-adrs-as-graph-queryable-entities.md) and [`guide-authoring-bar.md §7`](../../guide-authoring/references/guide-authoring-bar.md#7-adr-custody-redirects-repository-qualified-identity--slug-citations--machine-enforceable-candidate)) — these document cross-system architectural trade-offs that constrain directory choice. Examples:
60
+ - `neomjs/neo-agent-brain#adr:cross-process-cache-coherence` (singleton-cache reasoning)
61
+ - `neomjs/neo-agent-brain#adr:phase3-wake-substrate-standards-alignment` (wake-substrate standards)
62
62
  - Any newer ADR whose subsystem overlaps your candidate destination.
63
63
  3. **The [Agent OS v13 path](https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/v13-path.md)** when the new file lives in `ai/`-side substrate — this is the M-milestone source-of-authority for current architectural posture (M1 deployment-pipeline, M2 BaseServer, M3 Orchestrator, M4 Dream/Sandman, M5 NEO_MC_PRIMARY retirement, M6 SDK migration, M7 closeout). PR #11008 misplaced because authoring did not consult this document.
64
64
  4. **1-2 sibling files in EACH candidate destination directory** — even when the role doesn't match exactly. Reading siblings in `ai/scripts/` and `ai/daemons/` side-by-side reveals which directory the new file actually belongs in. The empirical anchor would have surfaced immediately.
@@ -101,7 +101,7 @@ Per Discussion #10447 OQ4 resolution, the threshold for filing an ADR vs an inli
101
101
  - **Cross-system trade-off** (touches multiple subsystems, sets a precedent for future code, affects load-bearing invariants): **file an ADR** in the repository that canonically owns the affected substrate. If the current checkout is not that owner, route a linked companion change there and keep the ADR-genesis gate failed; never create a consumer-local decisions tree.
102
102
  - **Localized constraint** (specific to one file or one method, doesn't generalize): **inline Anchor & Echo guard** in the JSDoc with `@see` references.
103
103
 
104
- **Example — ADR-class:** "Memory Core uses singleton cache instead of cross-process IPC because IPC overhead exceeds memory pressure cost at expected scale" (became `0001-cross-process-cache-coherence.md`).
104
+ **Example — ADR-class:** "Memory Core uses singleton cache instead of cross-process IPC because IPC overhead exceeds memory pressure cost at expected scale" (became `neomjs/neo-agent-brain#adr:cross-process-cache-coherence`).
105
105
 
106
106
  **Example — Anchor-and-Echo-class:** "this method's `await` is intentional because the caller relies on serialized cache writes; do not refactor to parallel without re-reading `MailboxService#addMessage`."
107
107
 
@@ -123,8 +123,8 @@ When the new file lives in `ai/` substrate (Right Hemisphere / Agent OS):
123
123
 
124
124
  - The [Agent OS v13 path](https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/v13-path.md) — current M-milestone architectural posture (M1-M7).
125
125
  - The Engine [Architecture Overview](https://github.com/neomjs/neo/blob/dev/learn/benefits/ArchitectureOverview.md) §Right Hemisphere + §Structural Inventory § Agent OS (Node.js).
126
- - [ADR 0001: Cross-Process Cache Coherence](https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/decisions/0001-cross-process-cache-coherence.md) (Memory Core).
127
- - [ADR 0002: Phase-3 Wake Substrate Standards Alignment](https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/decisions/0002-phase3-wake-substrate-standards-alignment.md) (wake substrate).
126
+ - [neomjs/neo-agent-brain#adr:cross-process-cache-coherence](https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/decisions/0001-cross-process-cache-coherence.md) (Memory Core).
127
+ - [neomjs/neo-agent-brain#adr:phase3-wake-substrate-standards-alignment](https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/decisions/0002-phase3-wake-substrate-standards-alignment.md) (wake substrate).
128
128
  - Sibling files in EACH candidate `ai/{daemons,scripts,services,graph,mcp,...}/` directory.
129
129
 
130
130
  ### 3.2 `src/`-side authoring
@@ -133,7 +133,7 @@ When the new file lives in `src/` substrate (Left Hemisphere / Runtime Engine):
133
133
 
134
134
  - The Engine [Architecture Overview](https://github.com/neomjs/neo/blob/dev/learn/benefits/ArchitectureOverview.md) §Left Hemisphere + §Structural Inventory § Runtime Engine (Browser).
135
135
  - `learn/guides/<subsystem>/` — subsystem-specific guides (e.g., `learn/guides/grid/` for grid work).
136
- - `learn/agentos/decisions/` ADRs whose stated subsystem touches your candidate destination.
136
+ - Canonical ADRs in their owning repositories (see [`guide-authoring-bar.md §7`](../../guide-authoring/references/guide-authoring-bar.md#7-adr-custody-redirects-repository-qualified-identity--slug-citations--machine-enforceable-candidate)) whose stated subsystem touches your candidate destination.
137
137
  - Sibling files in EACH candidate `src/{component,container,grid,data,state,worker,vdom,main,...}/` directory.
138
138
 
139
139
  ### 3.3 Test-tree authoring
@@ -193,7 +193,7 @@ The skill does NOT fire for:
193
193
 
194
194
  ### 7.2 Full Pre-Flight Example (Hypothetical Orchestrator-Class File)
195
195
 
196
- > *"Pre-Flight (structural full): considered destinations `ai/scripts/`, `ai/daemons/`, and `ai/daemons/services/` for `Orchestrator.mjs`; consulted the Engine [Architecture Overview](https://github.com/neomjs/neo/blob/dev/learn/benefits/ArchitectureOverview.md) Structural Inventory (`ai/daemons/` sibling = `DreamService.mjs`, `ai/scripts/` sibling = one-shot scripts, `ai/daemons/services/` sibling = service-class daemons), and the [Agent OS v13 path](https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/v13-path.md) §M3 (current architectural posture explicitly mandates `ai/daemons/Orchestrator.mjs` Neo-class + `ai/daemons/services/SummarizationCoordinatorService.mjs` decomposition + thin `ai/scripts/orchestrator-daemon.mjs` boot wrapper); no relevant ADR conflict (0001 about caching, 0002 about wake substrate); chose `ai/daemons/Orchestrator.mjs` for the class body + `ai/daemons/services/SummarizationCoordinatorService.mjs` for the per-task service + `ai/scripts/orchestrator-daemon.mjs` for the thin wrapper, because the v13 path §M3 establishes this exact split as the canonical architectural posture and the orchestrator class is a long-running coordination primitive (not a one-shot script). Map-maintenance: not-needed (existing Structural Inventory row for `ai/daemons/` covers Orchestrator without addition). Chief-architect framing: scalability (good — `ai/daemons/services/` accommodates future per-task services); ADR-conflict (none); ADR-genesis (not needed — the v13 path §M3 already documents the trade-off at the M-milestone-plan level); future-self regression-risk (low — split mirrors existing decomposition discipline)."*
196
+ > *"Pre-Flight (structural full): considered destinations `ai/scripts/`, `ai/daemons/`, and `ai/daemons/services/` for `Orchestrator.mjs`; consulted the Engine [Architecture Overview](https://github.com/neomjs/neo/blob/dev/learn/benefits/ArchitectureOverview.md) Structural Inventory (`ai/daemons/` sibling = `DreamService.mjs`, `ai/scripts/` sibling = one-shot scripts, `ai/daemons/services/` sibling = service-class daemons), and the [Agent OS v13 path](https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/v13-path.md) §M3 (current architectural posture explicitly mandates `ai/daemons/Orchestrator.mjs` Neo-class + `ai/daemons/services/SummarizationCoordinatorService.mjs` decomposition + thin `ai/scripts/orchestrator-daemon.mjs` boot wrapper); no relevant ADR conflict (`neomjs/neo-agent-brain#adr:cross-process-cache-coherence` about caching, `neomjs/neo-agent-brain#adr:phase3-wake-substrate-standards-alignment` about wake substrate); chose `ai/daemons/Orchestrator.mjs` for the class body + `ai/daemons/services/SummarizationCoordinatorService.mjs` for the per-task service + `ai/scripts/orchestrator-daemon.mjs` for the thin wrapper, because the v13 path §M3 establishes this exact split as the canonical architectural posture and the orchestrator class is a long-running coordination primitive (not a one-shot script). Map-maintenance: not-needed (existing Structural Inventory row for `ai/daemons/` covers Orchestrator without addition). Chief-architect framing: scalability (good — `ai/daemons/services/` accommodates future per-task services); ADR-conflict (none); ADR-genesis (not needed — the v13 path §M3 already documents the trade-off at the M-milestone-plan level); future-self regression-risk (low — split mirrors existing decomposition discipline)."*
197
197
 
198
198
  The full-pre-flight statement is verbose by design. Brevity hides reasoning; verbosity creates audit substrate.
199
199
 
@@ -11,7 +11,7 @@ Run this meta-analysis with frontier-tier capability — it synthesizes document
11
11
  A copied canon decays by construction and eventually inverts — the radar then flags sanctioned shapes as debt. At sweep time, load the debt taxonomy FROM the living authorities, and keep three classes separate: **authority** (what the canon prescribes), **observation** (what the tree currently is), and **hypothesis** (candidate findings awaiting an owning lane):
12
12
 
13
13
  1. The Engine's [Architecture Overview](https://github.com/neomjs/neo/blob/dev/learn/benefits/ArchitectureOverview.md) — the structural baseline (Body/Brain topology). *Authority.*
14
- 2. `learn/agentos/decisions/` — the ADR index IS the pattern canon. Minimum reads: ADR 0019 (the `ai/`-config antipattern catalog) for config debt; ADR 0008 for skill-shape debt. *Authority.* The extraction split this index: most ADRs, 0019 among them, now live in `neo-agent-brain` while the **directory still resolves** in the Engine — so a missing ADR reads as retired rather than moved. Read it from whichever repository holds it; absence there is not a licence to proceed.
14
+ 2. **The repository-qualified ADR canon** ([neomjs/neo-agent-brain#adr:adrs-as-graph-queryable-entities](https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/decisions/0006-adrs-as-graph-queryable-entities.md); custody redirects, 4-field keys, and `<org>/<repo>#adr:<slug>` rules in [`guide-authoring-bar.md §7`](../../guide-authoring/references/guide-authoring-bar.md#7-adr-custody-redirects-repository-qualified-identity--slug-citations--machine-enforceable-candidate)) — minimum reads: `neomjs/neo-agent-brain#adr:aiconfig-reactive-provider-ssot` (the `ai/`-config antipattern catalog) for config debt; `neomjs/neo#adr:skill-anatomy-and-authoring-contract` for skill-shape debt. *Authority.* Follow `type: redirect` (`target: <canonical-key>`) / `Status: Moved` pointer stubs to their canonical target; never treat a redirect stub as retired.
15
15
  3. `npm run ai:structure-map -- --files --loc` — current-tree measurement: where things ARE and how large. Brain-hosted; where absent, record N/A and never add `--silent`, which hides npm's `Missing script` behind an empty exit-1. *Observation only — no intended-placement policy; observed placement is never its own authority.*
16
16
  4. The `pr-review` guide's anti-pattern tables and `AGENTS.md` §edge_case_triggers (the `apps/**` data-path/style gate, `core.Base` as the quality bar). *Authority.*
17
17
 
@@ -1,16 +1,10 @@
1
1
  # Decision-substrate sweeps — arms `(iii)`, `(iv)` and `(v)` of §1a
2
2
 
3
- `ticket-create-workflow.md` §1a arms `(i)` and `(ii)`, and the semantic and exact sweeps beside them, are all **artifact** substrates. They answer *"does a ticket exist?"* None answers *"was this already decided, and why?"*
4
-
5
- A `NOT_PLANNED` predecessor is a **ruling**. An artifact sweep surfaces its title and never its reason, so it fails silently: a clean sweep, filed with confidence, carrying a fresh-timestamp attestation proving the sweep ran.
3
+ Declined predecessors carry decisions; read their reasons.
6
4
 
7
5
  ## (iii) Memory Core rationale sweep
8
6
 
9
- Run at least one `query_raw_memories` as the last step before `create_issue`, keyed on the **problem's nouns** — repo, package, file and symbol names, and the *existing* mechanism that failed, never the one you are about to build:
10
-
11
- ```js
12
- query_raw_memories({query: '<repo> <mechanism> <file/symbol> <prior-decision terms>', nResults: 6})
13
- ```
7
+ Immediately before `create_issue`, run at least one `query_raw_memories` keyed on the **problem's nouns**: repo, package, file/symbol and existing failed mechanism, never the proposed solution.
14
8
 
15
9
  **Query the PROBLEM's nouns, never the SOLUTION's.** This is the distinction the arm turns on, and it is not "search harder":
16
10
 
@@ -20,9 +14,9 @@ query_raw_memories({query: '<repo> <mechanism> <file/symbol> <prior-decision ter
20
14
  | ❌ structural / boilerplate phrasing | *"should we add a gate for…"* | session boilerplate; Memory Core indexes artifacts |
21
15
  | ✅ the problem's nouns — the symptom as observed | *"vast amounts of additional tickets"*, *"different casualty each run"* | prior art that solved the same problem **differently** |
22
16
 
23
- The problem's nouns are frequently **the operator's own words for the symptom**, so their phrasing is a source to mine rather than one to avoid — it is your own solution vocabulary that blinds the query.
17
+ Use the operator's symptom vocabulary; searching only your proposed mechanism hides other solutions.
24
18
 
25
- > **Empirical anchor — two independent instances, one night (2026-08-31).** `neo-agent-skills#32` was filed after a sweep on *"ticket-create duplicate sweep gate Memory Core"* — the mechanism about to be built. `neomjs/neo#16212` (operator-commissioned five weeks earlier, whose gate inventory already named this exact file) was invisible to it; a sweep on the operator's own *"vast amounts of additional tickets"* surfaces it immediately. Independently, `neomjs/neo#18000` was filed after a sweep scoped by **suite name** (*"flaky component suite"*), which could not match `neomjs/neo#17796` because that ticket names the **unit** suite — the searchable thing was the symptom shape, *"different casualty each run"*. Six days of prior art stayed invisible to four seats for that reason.
19
+ > **2026-08-31 anchors:** `neo-agent-skills#32` missed `neomjs/neo#16212` by querying the proposed mechanism instead of *"vast amounts of additional tickets"*. `neomjs/neo#18000` missed `neomjs/neo#17796` by querying a suite name instead of *"different casualty each run"*. Match the symptom across different solutions and suites.
26
20
 
27
21
  `query_summaries` and `explore_lane_landscape` widen the sweep when the first call returns only noise.
28
22
 
@@ -32,9 +26,7 @@ The problem's nouns are frequently **the operator's own words for the symptom**,
32
26
  gh issue list --repo <r> --state open --assignee @me --json number,title
33
27
  ```
34
28
 
35
- Then read the **bodies** of the two or three touching the same surface — not the titles. A site table, a row table, or a "deferred" clause is where a past self parked exactly this.
36
-
37
- Neither `(i)` (recency-bounded) nor a closed-issue search reaches an **open, old, self-assigned** parent. A defect found *while measuring something else* is the high-risk shape: it feels like discovery precisely because no retrieval preceded it.
29
+ Read the **bodies** of the two or three same-surface hits, including tables and deferred clauses. Old open self-assignments escape both `(i)`'s recency window and closed-state queries; incidental discoveries need this check too.
38
30
 
39
31
  ## (v) Epic-layer outcome-authority sweep
40
32
 
@@ -46,14 +38,12 @@ gh issue list --repo <r> --label epic --state open --json number,title
46
38
 
47
39
  Compare **terminal predicates**, not titles: *what state of the world does this Epic declare finished?* Two Epics that finish the same sentence are one Epic, however differently they open.
48
40
 
49
- **Read every row, but read one line of it.** `epic-create` requires each Epic body to open with a `Terminal predicate:` line precisely so this sweep is priced in lines, not bodies. Two stages, and the second is bounded by the first:
50
-
51
- 1. **Predicate scan (every row).** Read each open epic's `Terminal predicate:` line. Cheap enough to be exhaustive, which is the only reason "every" is honest here.
52
- 2. **Body read (the ranked few).** For rows predating the field, or whose predicate is close enough to yours to be arguable, run the semantic outcome-overlap query and read only the bodies it ranks. Retrieval surfaces the candidates; **only a reader can rule** — that is the judgement the arm exists to force, and it is not the part that was expensive.
41
+ **Read every predicate, then selected bodies.** `epic-create` puts `Terminal predicate:` first to keep this exhaustive read affordable:
53
42
 
54
- > **Population anchor, measured 2026-09-02 — do not trust this as a present-tense fact, re-run it.** Open `label:epic`: `neomjs/neo` **29**, `neo-agent-brain` **34**, `neo-agent-institution` 6, `neo-agent-skills` 1; the first five `neomjs/neo` bodies run 4,936–12,575 characters. An unstaged all-bodies read is therefore ~290k characters in one repo — the cost that mutes a gate within a week. A rule that embeds a population as an **adjective** ("there are few") carries a fact that decays silently while its prose stays confident; state the number with its date, or state the query.
43
+ 1. **Every row:** read each open epic's terminal predicate.
44
+ 2. **Ranked bodies:** for missing or arguably overlapping predicates, run the semantic outcome-overlap query and read its ranked candidates. Retrieval proposes; the reader judges overlap.
55
45
 
56
- An outcome authority does not churn, so it sits permanently outside `(i)`'s window and its title speaks the outcome's vocabulary rather than a newcomer's — both artifact axes miss it, for different reasons. The cost is topology: competing roots split sub-attachment, review attention and closure authority until someone folds them.
46
+ **Cost control:** read predicates exhaustively, bodies selectively. On 2026-09-02, 29 Engine epics implied ~290k characters for an all-body read; re-query populations rather than calling them small. Standing outcomes can predate `(i)`'s window and use different nouns, splitting ownership when missed.
57
47
 
58
48
  > **Anchor — `neomjs/neo-agent-brain#38` vs open `#54`, 2026-08-13.** Two roots, 17 and 16 children, the same two terminal predicates. The author's §1a sweep ran honestly and **passed**; a peer's epic review caught it after filing.
59
49
 
@@ -69,24 +59,22 @@ Epic sweep: <n> open epics read, no shared terminal predicate # epic-labeled
69
59
 
70
60
  Prose discipline that leaves no artifact cannot be checked, and these arms exist because prose discipline failed.
71
61
 
72
- ## Same-turn porting
62
+ ## Same-turn reconciliation
73
63
 
74
- If content belongs on a parent ticket, comment it onto that parent **in the same turn**. A note-to-self inside a closing comment ("record this on `#N`") has no owner and no trigger; hours later it is invisible to the agent who wrote it.
64
+ If content belongs on a surviving parent, port it there in the same turn. An accepted direction-changing fold, graduation or successor publication must also reconcile the older work it replaces. A new exploratory option alone retires nothing.
75
65
 
76
- ## Empirical anchor
66
+ Reuse adjacency results and predecessor PR links: read affected tickets, open PRs (draft or ready), research recommendations, tool assumptions and active handovers/checklists. Find predecessors before filing; disposition them once successor IDs exist. Abandonment reconciles immediately against existing outcome/research owners:
77
67
 
78
- **`neomjs/neo#17997`, 2026-08-31.** Re-filed **row 3** of `#17868` — open, older than the `(i)` window, and assigned to the filer — four hours after that same filer's own `#17961` closing comment recorded that row 3's blocker belonged **on `#17868`**.
68
+ 1. Cite the accepted decision and compare each recommendation with the **current outcome and required interactions**, not just its technical feasibility. A reusable reference does not authorize a superseded research/delivery path. Keep, narrow, transfer or retire each prescription; move unique obligations, evidence and dissent to a named surviving owner first. Existing research can own the remainder without another ticket.
69
+ 2. Update old entry heads and both sides' successor links. Retire obsolete instructions; preserve history. Close superseded PRs with decision/successor links, or retarget surviving scope. A finally rejected narrow implementation ticket closes `not_planned` per `ticket-intake` §4; unresolved outcomes stay open, and partial overlap leaves remaining obligations current. Epic closure uses `epic-resolution`.
70
+ 3. Apply own-authored or explicitly authorized changes. For foreign bodies/ACs, follow `ticket-create` §11: propose exact text and record the owner/application still owed. A pending proposal is not applied reconciliation.
71
+ 4. For immutable entries, put exact superseded IDs → current authority on the surviving owner's current entry and active handover. Preserve history. Read back bodies, links, states and mappings; mutable old heads must reveal disposition/owner. Report pending owner actions separately; unapplied cleanup is incomplete.
79
72
 
80
- Three blind spots, one root — the sweep searched for artifacts, never for decisions:
73
+ ## Empirical anchor
81
74
 
82
- | Blind spot | Missed because |
83
- |---|---|
84
- | recency-shaped | the standing parent is older than the latest-20 window |
85
- | open/closed-shaped | the decline lives in a closed issue; `(i)` reads open |
86
- | ownership-shaped | the parent is open, old, and already assigned to the filer |
87
- | authority-shaped | the standing Epic is open, old, owned by **someone else**, and titled in the outcome's vocabulary — arm `(v)` |
75
+ **`neomjs/neo#17997`, 2026-08-31.** Re-filed **row 3** of `#17868` — open, older than the `(i)` window, and assigned to the filer — four hours after that same filer's own `#17961` closing comment recorded that row 3's blocker belonged **on `#17868`**.
88
76
 
89
- Another artifact query would have caught none of them.
77
+ The missed decision can live in an older parent, a closed decline, a prior self-assignment or someone else's standing outcome; a latest-open artifact scan alone covers none of those cases.
90
78
 
91
79
  **Why the sweeps run LAST.** `#12856`, 2026-06-10: four agents raced one prompt into three duplicates, each having swept honestly; the one who re-checked immediately before filing produced none. Check-at-start decays across a multi-minute protocol.
92
80
 
@@ -141,8 +141,8 @@ Skeleton tickets are forbidden — so are world atlases: sections complete, each
141
141
  - **The Architectural Reality** — exactly which Neo.mjs patterns, class topologies, or service boundaries this issue interacts with. Cite file:line when known. Distinguishes intent-level framing (Problem) from structural specificity (Reality).
142
142
  - **The Fix** — concrete prescription: files, symbols, architectural primitives touched. What changes, and where.
143
143
  - **Contract Ledger Matrix** *(when applicable)* — For any ticket introducing, modifying, or deprecating a surface consumed by humans, agents, or external systems (public methods, configs, MCP tools), include a formal Contract Ledger matrix (Target Surface, Source of Authority, Proposed Behavior, Fallback, Docs, Evidence). Rows naming existing surfaces must satisfy the row-level Surface-Anchor V-B-A discipline in the [Contract Ledger protocol](https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/process/contract-ledger.md) before the ticket asserts them.
144
- - **Decision Record impact** *(architecture/substrate tickets)* — the §2 step-6 declaration (`none` … `challenges ADR ####`).
145
- - **Decision Record** *(Discussion-origin tickets)* — Preserve the source Discussion's ADR classification when present: `Not needed`, `Optional: <ADR/ticket/discussion anchor>`, or `Required: ADR #### / PR #N / ticket #N` (records the graduation's authority target; `Decision Record impact` records what this ticket itself does to ADR authority).
144
+ - **Decision Record impact** *(architecture/substrate tickets)* — the §2 step-6 declaration (`none` … `challenges <org>/<repo>#adr:<slug>` or same-repo `adr:<slug>`).
145
+ - **Decision Record** *(Discussion-origin tickets)* — Preserve the source Discussion's ADR classification when present: `Not needed`, `Optional: <ADR/ticket/discussion anchor>`, or `Required: <org>/<repo>#adr:<slug> / PR #N / ticket #N` (records the graduation's authority target; `Decision Record impact` records what this ticket itself does to ADR authority).
146
146
  - **Discussion Criteria Mapping** *(when graduating from a Discussion)* — Maps the upstream Discussion's `[RESOLVED_TO_AC]` criteria to this Epic's ACs (`ideation-sandbox-workflow.md §6.6`), satisfying `epic-resolution` Closeout Gates upfront.
147
147
  - **Acceptance Criteria** — bulleted checklist; each item independently verifiable, post-merge-only items flagged. **Epic exception:** for `epic`-labeled tickets, ACs live in the **SUB** tickets (author per `.agents/skills/epic-create/`: problem-scope + intended-solution; subs linked via `update_issue_relationship`, each one-PR-deliverable).
148
148
  - **Out of Scope** — what this ticket deliberately does NOT do.
@@ -190,6 +190,7 @@ The `create_issue` tool returns the new issue number. The ownership disposition
190
190
  - **`manage_issue_labels(action: 'add', ...)`** — only if the label set needs adjustment post-creation (e.g., label list was incomplete at `create_issue` time). Prefer getting labels right in the initial call.
191
191
  - **`update_issue_relationship(parent_id: N, child_id: M, type: 'SUB_ISSUE')`** — required when filing sub-issues under an Epic. Native graph linkage only; do NOT rely on inline `- [ ] #N` markdown checkboxes (see §6). Count the parent's subs first (`gh api repos/<r>/issues/N/sub_issues --paginate --jq length`); past ~25, file or link to a successor epic (`epic-create` Procedure 1).
192
192
  - **Ticket body edits:** Update GitHub directly with `gh issue edit N --body-file <path>` (or the equivalent live GitHub write surface). GitHub remains canonical; scheduled mirroring may lag.
193
+ - **Replacement work:** once successor IDs exist, run [same-turn reconciliation](decision-substrate-sweeps.md#same-turn-reconciliation) on the predecessors found by §1a; preserve surviving outcomes before retiring old prescriptions.
193
194
  - **Picking up the ticket:** If you intend to start working on this newly created ticket immediately, you MUST run the `ticket-intake` skill next (your assignee claim fulfills the primary gate).
194
195
 
195
196
  Minimize chained calls where possible — a well-formed `create_issue` call with complete `title`, `body`, and `labels` at creation time avoids all of the above except `update_issue_relationship` (which can only run after the issue exists).
@@ -6,7 +6,7 @@ This payload provides the ADR-specific branch of the ticket-intake successor-ris
6
6
 
7
7
  Run this audit when any architecture-bearing ticket, Discussion, Epic, or PR:
8
8
 
9
- - cites an ADR, Decision Record, or `learn/agentos/decisions/` file;
9
+ - cites an ADR (`<org>/<repo>#adr:<slug>`, same-repo `adr:<slug>`, or canonical key `adr:<E(forge)>:<E(repositoryId)>:<E(namespace)>:<number>` per [neomjs/neo-agent-brain#adr:adrs-as-graph-queryable-entities](https://github.com/neomjs/neo-agent-brain/blob/dev/learn/agentos/decisions/0006-adrs-as-graph-queryable-entities.md) and [`guide-authoring-bar.md §7`](../../guide-authoring/references/guide-authoring-bar.md#7-adr-custody-redirects-repository-qualified-identity--slug-citations--machine-enforceable-candidate)), Decision Record, or `learn/**/decisions/` file;
10
10
  - predates a related accepted ADR and prescribes a conflicting shape;
11
11
  - postdates an accepted ADR and proposes a different architecture;
12
12
  - introduces, amends, supersedes, or retires durable agent/workflow substrate;
@@ -19,7 +19,7 @@ If no related ADR exists and the proposal does not affect decision-record substr
19
19
  Before classifying, gather:
20
20
 
21
21
  - `Artifact`: ticket / Discussion / Epic / PR number, author, `createdAt`, and `updatedAt`.
22
- - `Related ADR(s)`: ADR number/path, `Status`, decision date if present, and current repo state.
22
+ - `Related ADR(s)`: repository-qualified ADR identifier (`<org>/<repo>#adr:<slug>`, same-repo `adr:<slug>`, or §2.6 canonical key), canonical path, `Status`, and decision date if present. If a local file is a redirect stub (`type: redirect` + `target: <canonical-key>` per §2.9, or `Status: Moved`), resolve its `target` through the admitted catalog to the canonical repository/path — a redirect pointer is a custody redirect, **never** `Superseded` or `Retired`.
23
23
  - `Chronology`: whether the artifact predates, postdates, or is same-cycle with the ADR.
24
24
  - `Conflict surface`: the concrete contract, workflow, service boundary, or architectural premise that overlaps.
25
25
  - `Evidence`: source/docs/tests/tickets/Discussions/PRs proving alignment, conflict, supersession, or fresh challenge.
@@ -47,16 +47,16 @@ Do not classify from title similarity alone. The conflict must be tied to a spec
47
47
 
48
48
  ## 5. Required Output Shape
49
49
 
50
- When this audit fires, record a compact line in the current workflow artifact:
50
+ When this audit fires, record a compact line in the current workflow artifact using the repository-qualified ADR reference (`<org>/<repo>#adr:<slug>` or same-repo `adr:<slug>`):
51
51
 
52
52
  ```md
53
- ADR successor-risk: <verdict> — artifact <#N/date>; ADR <####/status/date>; evidence <path|issue|PR|discussion>; route <continue|supersede|challenge|amendment-required|pending-authority>.
53
+ ADR successor-risk: <verdict> — artifact <#N/date>; ADR <org>/<repo>#adr:<slug> (<status>/<date>); evidence <path|issue|PR|discussion>; route <continue|supersede|challenge|amendment-required|pending-authority>.
54
54
  ```
55
55
 
56
56
  For public artifacts that create new work, also include:
57
57
 
58
58
  ```md
59
- Decision Record impact: none | aligned-with ADR #### | depends-on ADR #### | amends ADR #### | supersedes ADR #### | challenges ADR ####
59
+ Decision Record impact: none | aligned-with <org>/<repo>#adr:<slug> | depends-on <org>/<repo>#adr:<slug> | amends <org>/<repo>#adr:<slug> | supersedes <org>/<repo>#adr:<slug> | challenges <org>/<repo>#adr:<slug>
60
60
  ```
61
61
 
62
62
  ## 6. Workflow Surface Map
@@ -149,6 +149,8 @@ You are **FORBIDDEN** from executing the following tools while on the `dev` or `
149
149
 
150
150
  If you determine the ticket is stale or harmful, you MUST execute the Rejection Protocol instead of attempting to build it.
151
151
 
152
+ For surviving obligations or stale entry points, use [same-turn reconciliation](../../ticket-create/references/decision-substrate-sweeps.md#same-turn-reconciliation) within this rejection step, without another sweep.
153
+
152
154
  **Close Policy:**
153
155
  - **Architecture Exploration / Epic Tickets:** **DO NOT close the ticket.** It must be preserved so the Swarm can formally evaluate the paradox. Record what it waits on via `update_issue_relationship(blocked_by)`. Not a label: `needs-re-triage` is for externally-authored tickets below the bar (see `ticket-triage`), so stamping it here pollutes that queue.
154
156
  - **1:1 Implementation Tickets (Including Substrate):** If the ticket is a narrow, final declined implementation task (e.g., `already-resolved`, `duplicate`, `invalid-or-negative-roi`), you MUST close the ticket as `not_planned` to prevent preserving bad payloads as future traps, even if the ticket prescribes substrate edits.
@@ -38,7 +38,7 @@ Create a fresh observational fingerprint for the intended target immediately bef
38
38
  - a topology snapshot and timestamp;
39
39
  - a safe screenshot or digest of the clean frame.
40
40
 
41
- The fingerprint is not durable routing authority. ADR 0029 §2.8.5 keeps semantic names, URLs, titles, timing, and runtime IDs from becoming physical-handle authority. Treat the fingerprint only as a short-lived selection/revalidation receipt.
41
+ The fingerprint is not durable routing authority. `neomjs/neo#adr:docking-design` §2.8.5 keeps semantic names, URLs, titles, timing, and runtime IDs from becoming physical-handle authority. Treat the fingerprint only as a short-lived selection/revalidation receipt.
42
42
 
43
43
  ## 4. Recorder revalidation and frame zero
44
44
 
@@ -65,7 +65,7 @@ Native footage and application truth are complementary:
65
65
 
66
66
  Bind each receipt to the exact take ID, source head, timestamp range, and evidence claim. If the Neural Link server/OpenAPI/harness projection changed, rerun capability discovery and the smoke proof before capture.
67
67
 
68
- For a claim about physical close, ADR 0029 §2.8.5 is explicit: a native `close()` return is provisional. The receipt becomes terminal only after the connected runtime `windowId` disappears from topology. For focus/position or other physical effects, record the corresponding before/after observation and semantic state; never treat dispatch success as effect proof.
68
+ For a claim about physical close, `neomjs/neo#adr:docking-design` §2.8.5 is explicit: a native `close()` return is provisional. The receipt becomes terminal only after the connected runtime `windowId` disappears from topology. For focus/position or other physical effects, record the corresponding before/after observation and semantic state; never treat dispatch success as effect proof.
69
69
 
70
70
  Independently opened, cross-origin, stale, or uncorrelated windows can remain observable, but physical control fails closed.
71
71
 
@@ -19,7 +19,7 @@ Start by copying `../assets/video-project-record-template.md`. That record is th
19
19
 
20
20
  It consumes, without duplicating:
21
21
 
22
- - `/neo-identity-update` and ADR 0018 for identity-bearing claims and framing;
22
+ - `/neo-identity-update` and `neomjs/neo#adr:neo-identity-source-of-truth-model` for identity-bearing claims and framing;
23
23
  - `/neural-link` for semantic live-application inspection or interaction;
24
24
  - `/whitebox-e2e` and `/unit-test` for app-owned runnable/test evidence;
25
25
  - `/imagegen` for generated still-image mechanics;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "neo-agent-skills",
3
- "version": "0.1.53",
3
+ "version": "0.1.55",
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",