docs(research-patches): universal-skill stack-driven — research prep - #1048
Merged
Conversation
…for future umbrella Captures the discussion session validating the operator's idea: one (or two) universal skills driven by per-stack generated documentation, instead of rewriting skills per tool version per project. Verifies understanding (two-artifact split: thin skill = consumer, framework = generator, stack knowledge = short-lived data), documents what already exists in the repo (6-layer compiler, ConventionNode IR, ToolchainBackend<A> + RenderOutcome, firing-contract.json, the rule-research exemplar), and surfaces the one real gap: the 'tests-skill' as an invokable surface — capability exists (firing-contract, validator gates, pairedExamples.negative, mutation gate), packaging does not. Status: RESEARCH-PREP only. No kickoff, no umbrella dir, no PR, no code edit. Open questions for the next session (with a stronger model) in §8: umbrella name, scope (gap-only vs duplicate rule-research), one-vs-two skills, the 'in skill' vs 'in data' boundary for tests, and whether migrating rule-research onto the Convention IR is a precondition. Prior-art: MT-umbrella design spec (docs/superpowers/specs/2026-07-03-multi-toolchain-convention-compiler-design.md); rule-research exemplar (agents/rule-researcher.md); ConventionNode IR (packages/core/ir/types.ts). Discussion session re-derived the project thesis (README.md#why-this-exists); not a new capability.
This was referenced Jul 20, 2026
artyhoo
added a commit
that referenced
this pull request
Jul 21, 2026
…inciples + rule-index + install-sh + hooks + synth-bundle) (#1051) * fix(gates): restore green principles + rule-index on staging (3 pre-existing blockers) `staging` HEAD failed three push gates independently of any in-flight branch, blocking every `git push` in the repo: 1. principle 11 F1 — `.claude/rules/zcode-parity-doctrine.md` (#1045) landed with neither a `Prior-art:` trailer nor a verbatim-path SSOT citation. Closed with SSOT row #220 (the only reachable closure form once the adding commit merged; direct precedent #211 after PR #907). The doctrine file is left BYTE-IDENTICAL to staging — editing it would drag its pre-existing gitignored-plan link (.ai-factory/plans/, not in git) into lychee's changed-file scan. 2. `render-rule-index --check` — the doctrine's 312-char `Fires:` row pushed the index to 3357B over a 3072B ceiling that was ALREADY 99% consumed (3044/3072) before it landed, i.e. structurally unmeetable rather than violated. Raised INDEX_MAX_BYTES 3KB->4KB (3357 < 4096) with the reasoning recorded at the constant; index + AGENTS.md region regenerated, doctrine row unchanged. 3. principle 13 — `2026-07-18-universal-skill-stack-driven-prep.md` (#1048) landed with no §1.7 self-review section. Appended §10 as a self-review of the patch as merged (findings untouched). Verified: `npm --prefix packages/core run test:principles` 311/311 pass, `test:backends` 191/191 pass, `render-rule-index --check` exit 0. Prior-art: prior-art-evaluations.md#220 (REFERENCE — own-stack gate maintenance; F1 accepts only trailer-on-adding-commit or verbatim-path SSOT row, and the adding commits are already merged). * fix(gates): regenerate install-sh baselines drifted by #1043 (4th pre-existing blocker) PR #1043 (S6 2B-standardize, 2026-07-19) rewrote three hooks — inject-matching-rule.sh, inject-output-language.sh, inject-project-digest.sh (env-first REPO_ROOT standardization) — but did NOT regenerate the byte-identical install-sh baseline fingerprints. Proof: on origin/staging the source hook inject-matching-rule.sh hashes to 8edd7f… while every baseline fingerprint still records the pre-#1043 e1f96e… (baselines last updated by #1031, 2026-07-18, one day BEFORE #1043). The install-sh battery is pull_request-gated (audit-self.yml :622 if github.event_name == 'pull_request'), so pushes to staging never ran it and the drift sat latent; every PR since #1043 inherits the red. SNAPSHOT_MODE=capture regenerated all 8 npm baselines; diff is EXACTLY the 3 hook hashes (verified: no other file changed, new hashes match the real hook files). `SNAPSHOT_MODE=compare` → 11/11 byte-identical. Prior-art: skipped — test-fixture baseline regen after an upstream hook edit (#1043), no new capability. * fix(gates): make inject-subagent-context.test.ts hermetic (5th pre-existing blocker) inject-subagent-context.test.ts shipped RED by #1047 and never passed on staging (merged past — Principles job is non-blocking). Its 5 zcode-branch tests called the hook with ZCODE_PROJECT_DIR set (for the _is_zcode gate) but relied on the REAL repo's .claude/session-bootstrap.md carrying a `<!-- digest:start/end -->` block — which it does not, by design: the framework's main-session digest is emitted dynamically by inject-session-bootstrap.sh's heredoc, never cached as a static block (a static copy would drift from the heredoc's dynamic AIF_HOOK_LANG line). So the hook correctly no-ops (empty stdout) → JSON.parse throws. Fix mirrors the sibling inject-project-digest.test.ts (which is hermetic): build a temp fixture repo whose session-bootstrap.md carries a digest block seeded with inject-session-bootstrap.sh's own output, and point the hook at it via CLAUDE_PROJECT_DIR (the root the hook reads at :44). The SSOT/no-drift assertion stays meaningful (verifies the hook reads + appends the block verbatim). Test-only change; the hook and the maintainer-owned session-bootstrap.md are untouched. Verified: test:hooks 825/826 pass (the remaining 1 = harness-config-drift, a distinct zcode-parity SSOT-drift bug from #1036/#1046 filed as #1053 — needs a domain decision, not a blind regen). Prior-art: skipped — test hermeticity fix for an existing hook, no new capability. * fix(gates): register plugin twins in PLUGIN_INTERNAL_HOOKS SSOT (6th pre-existing blocker) harness-config-drift.test.ts failed on staging (render --check exit 1) — the LAST pre-existing Principles-job red. Root cause: #1036 (inject-project-digest, inject-output-language) and #1046 (warn-subagent-report-zcode) hand-added their plugin-channel entries directly to the GENERATED plugin/hooks/hooks.json but never registered them in PLUGIN_INTERNAL_HOOKS — the renderer's SSOT for plugin-only hooks that have no framework-model counterpart. So `render --write` removed them (43-line drift) and `--check` reported it. These three are genuinely plugin-only: absent from .claude/settings.json AND from harness-model.json, each with a real plugin/hooks/ sibling script, reaching ZCode consumers ONLY via the plugin channel. Regenerating them away would revert shipped #1036/#1046 functionality; the SubagentStart arm is also inexpressible from the model (event ∉ ZCODE_EVENTS). PLUGIN_INTERNAL_HOOKS is exactly their intended home. Changes: - render-harness-config.mjs: register the 4 twin entries in PLUGIN_INTERNAL_HOOKS (UserPromptSubmit ×2, SubagentStart, PostToolUse, Stop). PLUGIN_INTERNAL_HOOKS / PLUGIN_INCOMPATIBLE stay module-private (no export) — the drift test no longer imports them (see below). - harness-config-drift.test.ts: rewrite the N6 plugin-coverage assertion from count-equality (which only held before the twins landed, and would have required importing the registries from the untyped .mjs — breaking `tsc --noEmit` with TS7016, no declaration file) to coverage-BY-NAME: for every zcode-supported event, each model-derived hook — except the maintainer-only PLUGIN_INCOMPATIBLE set (link-coordination) — must appear by dispatch name in the plugin output. Extra plugin-internal twins are allowed; the drift gate (test above) already asserts their presence + byte-reproducibility. - plugin/hooks/hooks.json: regenerated (twins preserved; same-event ordering now internal-first — cosmetic for independent context/advisory hooks). settings.json / .mcp.json / zcode.json UNTOUCHED (model unchanged). Closes #1053. Verified: tsc --noEmit clean, test:hooks 826/826, test:principles 311/311, render-harness-config --check exit 0. Prior-art: skipped — SSOT-registration fix for existing shipped hooks, no new capability. * fix(gates): regenerate stale synth-bundle for semver 7.8.5 (7th pre-existing blocker) The committed packages/core/install/synth-and-wire.bundle.mjs was built with an older semver (pre-7.8.x — lacks functions/truncate.js + the isPrereleaseIdentifier helper). CI's synth-bundle drift gate (#755) rebuilds with the semver that root `npm install` pins per the ROOT package-lock (packages/core/node_modules/semver = 7.8.5): audit-self.yml runs the root `npm install` step ("hoists tsx to root for the hooks-suite gate") BEFORE the synth-bundle gate, so the gate builds against 7.8.5 — not the 7.8.1 that the earlier `npm ci --prefix packages/core` installs. A fresh 7.8.5 build differs from the stale committed bundle → DRIFT. Why this was masked until now: the Principles job runs principles-meta-tests FIRST, and that step has been red on staging since 2026-07-18 (the principle-11/13 blockers this PR's 4e1f6d4 fixes), which short-circuits the job before the synth-bundle step ever runs. Once the earlier blockers go green the job reaches the synth-bundle gate and the pre-existing staleness surfaces — a hidden-behind-a-red-gate regression, not introduced by any commit in this PR. Fix: rebuild with CI-parity node_modules — replicated audit-self's install sequence (`npm ci --prefix packages/core` then root `npm install` → packages/core semver 7.8.5), then committed the result. The build-synth-bundle.sh:50 path-normalization is untouched; only the bundled semver library content differs (+72/-8). Verified: `NODE_ENV=development bash scripts/build-synth-bundle.sh --check` exit 0; test:hooks 826/826; test:principles 311/311 — all green in the same node_modules state. Prior-art: skipped — snapshot regeneration of a generated artifact, no new capability. --------- Co-authored-by: t <t@t.co>
3 tasks
artyhoo
added a commit
that referenced
this pull request
Jul 21, 2026
…ion prompt (#1068) Continuation of the 2026-07-18 universal-skill prep (#1048): the Fable discussion session ran the anticipated 'stronger model' pass — a 12-agent adversarial panel (6 subsystem maps, 4 design perspectives, 2 skeptics) over the live tree. - research-patches/2026-07-21-universal-skill-panel-synthesis.md: decisions D1 (skill ships to consumers; chain detect -> research -> rules -> tests -> skill), D2 (static universal skill x regenerated dossier; never per-stack generated), D3 (staleness v0 = offer-on-consent; auto only behind consumer opt-in — delegated default, operator-overridable); prep §8 questions resolved (gap-only scope, IR not a precondition + 3 prohibitions vs ir-unfreeze); the three panel strikes incl. the honesty trilemma; three-bin seam doctrine; open questions O1-O6 for the design session. - 2026-07-21-universal-skill-design-session-prompt.md: self-contained session-start prompt for the design session (placement per deps-hash prompt precedent, #1049). No kickoff, no umbrella dir, no code changes, no SSOT row (lands with the umbrella's first capability commit). Co-authored-by: t <t@t.co>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Research-prep doc for a future
universal-skill-stack-drivenumbrella. Captures a discussion session validating the operator's idea: one (or two) universal skills driven by per-stack generated documentation, instead of rewriting skills per tool version per project.Status: RESEARCH-PREP only. No kickoff, no umbrella dir, no code edit, no design decision. The purpose of landing this on
stagingis to make it visible from any CC session so the idea can be discussed, examined, and revised with a stronger model before any umbrella is started.What the doc covers
rule-researchskill,packages/core/ir/+composition/+backends/(4 live: npm/cargo/astgrep/ruff), MT-umbrella spec,.ai-factory/data formats.ConventionNodeIR,ToolchainBackend<A>+RenderOutcome, universalfiring-contract.json, therule-researchexemplar of a thin skill.pairedExamples.negative, mutation gate), packaging does not.Why this lands on staging without a kickoff
Per
kickoff-staging-placement.mdthe rule about staging-visibility applies to dispatch-input kickoffs. This is NOT a kickoff — it is a research-prep doc that lives underdocs/meta-factory/research-patches/perphase-research-coverage.md§3 (research-patches accumulator format). The reason to merge it to staging (rather than leave on a feature branch) is operator convenience: any new CC session opened onstagingwill see the file without needing to checkout a specific branch first.Verification
b96cc2056).<!-- scope:... -->line 1, blockquote Scope/Status/Method/Date header, sections perresearch-patches/README.md.[via Explore]markers on file:line refs that came from subagent readings — explicit signal to re-verify before load-bearing use.What this PR does NOT do
.claude/orchestrator-prompts/<umbrella>/directory created.prior-art-evaluations.mdrow appended (premature — the tests-skill is not yet a committed build-vs-reuse decision).§1.7 Forward-check / Backward-check
Forward-check (what this enables):
stagingand have the prep file immediately visible.phase-research-coverage.md§3 (research-patches accumulator format).Backward-check (what this codifies / supersedes):