docs(research-patches): commit 3 patches from 2026-05-16 autonomous research session by artyhoo · Pull Request #55 · artyhoo/getff

artyhoo · 2026-05-16T11:56:04Z

Summary

Commits 3 research patches produced by the 2026-05-16 autonomous-research-orchestrator session (parent Queue mode run, 4 GO + 1 deferred). All 3 patches were left untracked by the parent session; this PR brings them into version control as part of the audit trail.

#	Patch	Lines	Parent kickoff	Verdict
1	research-tooling evaluation	387	research-tooling-evaluation	GO (iter 0)
3	§13.33 wave-10 hook architecture	786	wave-10-hook-architecture	GO (iter 0)
4	§1.7 think-time gate	470	think-time-s17-gate	GO (iter 1; iter 0 caught Elicitation hook HARD-FIX — meta-recursive cycle worked)

Parent commit 828e31c (PR #54, merged) covered SSOT corrections for patch #1's findings. This PR closes the loop by committing the actual research-patch files referenced by SSOT entries #42-#48.

Scope

Files: 3 new files under docs/meta-factory/research-patches/
No code changes — pure documentation
Not a capability commit — no package.json deps, no LOC in packages/core/<new-dir>/, no new file ≥80 LOC under packages/. Each commit carries Prior-art: skipped trailer per the escape-hatch policy in CLAUDE.md.

Mechanical fixes during commit

Pre-commit hooks caught 15 bare-URL violations (patch #1) and 7 missing-language fenced-code blocks (patches #3, #4). Both fixed deterministically — bare URLs wrapped in <...> via markdownlint-cli2 --fix; fenced blocks given text language via sed. No content changes.

§1.7 — Skipped (mechanical maintenance commit)

This PR introduces no new rule, principle, or discipline-bearing change. It commits previously-untracked research-patch files (output of an already-completed R-phase). Per feedback_s17_scope_vs_path_filter and .claude/rules/phase-research-coverage.md §1.7: §1.7 forward+backward checks protect rule-introduction drift; commits without rule introduction are out of §1.7 scope.

Test plan

npm run -w @rules-as-tests/core test:principles — 10 files, 56 tests, all green (including principle 10 research-patch-annotation)
markdownlint-cli2 — 0 errors across all 3 patches
Pre-push hook — passed (annotations, scope, principles tests, link check skipped — lychee not installed)
git log --oneline main..docs/research-patches-2026-05-16 — 3 atomic commits, conventional format, Prior-art: skipped trailer on each

Empirical comparison of DeepWiki vs context7 for SSOT-evaluation, coverage-check, freshness, and negative-existence claim verification. Produced by parent autonomous-research-orchestrator session (kickoff #1, iter 0, GO). Includes 7-row decision matrix, proposed SSOT #42 DeepWiki MCP ADOPT-CONDITIONAL, and Q2 verdict-relevant gap on SSOT #38 item b. Prior-art: skipped — research patch, not a capability commit (no package.json dep, no LOC in packages/core/<new-dir>/, no new file ≥80 LOC under packages/).

Wave 10 hook architecture R-phase patch — analyzes bash→TypeScript migration of .husky/pre-push runtime. Produced by parent autonomous-research-orchestrator session (kickoff #3, iter 0, GO). Recommends D6 = option (a) own-build TS hook runner via tsx (zero new deps, full Stryker coverage). D7 = Wave 11 Danger adoption deferred. Proposes SSOT #47 (Lefthook DEFER) and #48 (simple-git-hooks REJECT) with T16 problem-class mismatch evidence for both. Prior-art: skipped — research patch, not a capability commit.

§1.7 think-time gate R-phase patch — analyzes temporal scope gap (think-time vs write-time) in §1.7 forward+backward discipline. Produced by parent autonomous-research-orchestrator session (kickoff #4, iter 1 GO; iter 0 caught 1 HARD-FIX on Elicitation hook mischaracterization — meta-recursive cycle). Recommends H1+H10+W1 bundle: H1 hook now, H10 Wave 10 verdict-as-tool-call MCP, W1 immediate session-bootstrap reinforcement. §5.2 Elicitation hook correctly characterized as MCP-elicitation-dialog (INAPPLICABLE for general output interception) per iter-1 fix. Prior-art: skipped — research patch, not a capability commit.

Picks up EXEMPT_DIRS for research-patches/ from PR #57 (d189814) to unblock CI overweight check on 786-line patch #3. No file conflicts expected — PR #57 only touched .github/workflows/ while PR #55 only adds files under docs/meta-factory/research-patches/.

…ommit B) (#112) Ships the executable test for principle 15 per its design sketch (Commit A, #105). Each in-scope SKILL.md not in the EXEMPT_SKILLS allowlist must carry a body-section paired-negative block (`## Without this skill` + `## With this skill`, both non-trivial and differing — anti-tautology, mirroring principle 02). Grandfather = explicit EXEMPT_SKILLS allowlist (mirrors principle 09's EXEMPT_PATTERNS mechanism, NOT a date — the design's "date cutoff" wording is corrected to "allowlist" in §3/§5/§6/§7/§10). Self-test: positive + mutation 1a (no Without) + 1b (no With) + 2 (tautology) + 3 (exemption load-bearing). All 5 current skills grandfathered → CI stays green. ADAPT of Superpowers' «NO SKILL WITHOUT A FAILING TEST» (idea, no dependency; substrate-pure). SSOT #55 registered in this commit (#54 taken by Aider run_cmd via #110). §1.7 forward-check: principle 15 complies with build-first-reuse-default (ADAPT verdict, SSOT #55, zero Superpowers dep — substrate-pure per DECISION=C); no-paid-llm-in-ci (pure structural parse, no LLM); doc-authority-hierarchy (companion design.md carries header at packages/core/principles/15-skill-paired-negative.design.md:4); reviewer-discipline (marker form was maintainer-decided, not executor-picked). Mirrors principle 02's anti-tautology at packages/core/principles/02-paired-negative-test.test.ts:80. §1.7 backward-check: new rule scope = in-repo SKILL.md (.claude/skills/* + skills/*). Complete sweep satisfied by grandfather — all 5 current skills in EXEMPT_SKILLS at packages/core/principles/15-skill-paired-negative.test.ts:34; the exemption itself carries the load-bearing mutation-3 self-test at packages/core/principles/15-skill-paired-negative.test.ts:197 (proves the allowlist is load-bearing — same headerless skill passes IFF its path is in EXEMPT_SKILLS). No skill forced to change. Prior-art: prior-art-evaluations.md#55 (Superpowers TDD-for-Skills, verdict ADAPT — idea re-expressed for the SKILL.md artifact as principle 15; no dependency, substrate-pure).

…s principle 15, #112) (#113) Principle 15 (skill paired-negative, #112, SSOT #55) shipped candidate mechanism A — each non-grandfathered SKILL.md carries a body-section paired-negative block. Marks §13.36 RESOLVED and corrects the now-false claim that SKILL.md files have no paired-negative enforcement. Orchestrator follow-up promised in #112. Prior-art: skipped — docs status update only, no new capability or dependency.

…nvocations + dup-detect empty-arg = --all (#266) Stage 4 of the `meta-orch-no-arg-overview` umbrella. Two coupled wire-level fixes that unblock the skill itself: P4-a closes the form-mismatch between SKILL.md `!`-block helper invocations and the maintainer-side allow-list shape, and P4-b removes the compound `||` chain that no single allow-rule pattern matched. (a) SKILL.md: rewrite 7 of 14 `!`-blocks from direct-path form `${CLAUDE_SKILL_DIR}/helpers/<file>.sh "$arg"` to bash-quoted form `bash "${CLAUDE_SKILL_DIR}/helpers/<file>.sh" "$arg"`. Scope = the 7 blocks that ARE direct-path helper invocations (lines 72, 104, 172, 180, 188, 239, 243). The other 7 blocks (`cat`/`git`/`gh`/`head`/`jq` at 56, 60, 64, 68, 162, 285, 360) are not direct-path helper invocations — the transformation rule does not apply, current form preserved. Semantics preserved: same helper, same args, same exit codes. (b) dup-detect.sh: empty arg now silently falls through to the `--all` iteration (was: emit `Usage:` and exit 1). Lets the SKILL.md §2.5 Step 2 invocation use a single allow-rule pattern instead of the compound `<arg> || --all` chain. (c) packages/core/hooks/dup-detect-empty-arg.test.ts: paired-negative contract — empty-arg-equals-all (positive), explicit-all regression, valid-umbrella-name preserves named-path, missing-umbrella preserves the original `MISSING:` error path (not the old `Usage:`), absent prompts-dir handled gracefully. Pattern mirrors packages/core/hooks/delta-write-from-state.test.ts (F.3 sibling helpers PR #261). The maintainer-side companion — the `.claude/settings.json` allow-rule diff that complements the bash-quoted form — ships in the PR body as a HEREDOC recipe per [[feedback_settings_json_agent_uncommittable]]: the agent cannot Write/Edit `.claude/settings.json` (self-protected deny entry). Maintainer applies the diff manually before the next `/meta-orchestrator` invocation can succeed. ### §1.7 Forward-check applied `build-first-reuse-default.md §3` — six-layer mechanism not required: this is a wire-level rewrite of an existing helper (no new capability, no new substrate). The paired-negative test pattern is ADAPTED from SSOT #55 (Superpowers TDD-for-Skills, prior-art-evaluations.md#55) and the helper-testing variant is established at `packages/core/hooks/delta-write-from-state.test.ts:30-99` (F.3 helper-collapse PR #261, 2026-05-28). `no-paid-llm-in-ci.md §1` — all work is session-bound; the new test is pure-bash spawnSync + vitest, no API-billed call. `doc-authority-hierarchy.md` — SKILL.md Authoritative-for header preserved; no goal-redefinition. `parallel-subwave-isolation.md §1` — work executed in worktree `/Users/art/code/rules-as-tests-aif-overview-s4/`, branch `feat/meta-orch-no-arg-overview-s4`, not primary workdir. ### §1.7 Backward-check applied No artefact silently superseded. SKILL.md frontmatter `allowed-tools: Bash(bash ${CLAUDE_SKILL_DIR}/helpers/*.sh *)` already covers the bash-quoted form — this commit makes the helper invocation sites *use* that form rather than the direct-path form. SKILL.md §0 caveat about CC issue #14956 still applies — the maintainer-side `.claude/settings.json` allow-rule is the load-bearing fallback per DN-1 Option C (PR #262 §3). The compound `|| --all` chain at SKILL.md §2.5 Step 2 line 172-174 collapses into a single invocation; the collapsed form preserves all existing helper output paths (POTENTIAL_DUPE / MISSING / OK / `(no orchestrator-prompts dir)`). The named-path branch in dup-detect.sh:74 is preserved verbatim — only the empty-arg edge behaviour changes. Reference: kickoff §5 backward-check at `.claude/orchestrator-prompts/meta-orch-no-arg-overview/kickoff.md:156`. Prior-art: prior-art-evaluations.md#55 (Superpowers TDD-for-Skills, ADAPT — extends paired-negative discipline to helper testing; helper-testing variant established at packages/core/hooks/delta-write-from-state.test.ts shipped under F.3 helper-collapse PR #261).

…rdicts for tracing-knowledge-lineages / when-stuck / preserving-productive-tensions + 5 SSOT rows (#92-#96) (#321) Single-session R-phase per .claude/orchestrator-prompts/companion-capability-survey/ kickoff.md + companion-capability-survey-meta-launch/kickoff.md. Surveys 11 Superpowers/Superset/aif-handoff capabilities not previously in SSOT against the /meta-orchestrator pipeline stages. Net additions: - docs/meta-factory/research-patches/2026-06-01-companion-capability-survey.md - prior-art-evaluations.md rows #92-#96 (4 ADOPT VOCABULARY + 1 REJECT) - #55 Last reviewed bumped to 2026-06-01 (writing-skills TDD-for-docs; verdict unchanged at ADAPT) - #86 Trigger to revisit sharpened (Superset Automations + MCP start_agent_session are a separate surface from the worktree-substrate #86 originally rejected) T-CCS-B fired: kickoff §2 claimed 'Superset cron — DeepWiki found NONE'; this survey verified Automations + RRule DO exist per docs.superset.sh/automations. Slack-agent precedent for Superset was the other §2 seed claim — NOT confirmed against source; dropped INCONCLUSIVE. No code changes. No new deps. Verdicts are recommendations per reviewer-discipline.md §2 — maintainer decides per-row adoption. Prior-art: skipped — research-patch + SSOT additive rows + Last-reviewed/Trigger sharpening on #55/#86. Not a capability commit per CLAUDE.md definition (no new explicit package.json dep; no ≥50 LOC under new packages/core/<dir>/; no ≥80 LOC under packages/). All edits are append-only or §3-step-1 in-place updates to prior-art-evaluations.md. Co-authored-by: Mastra Code (anthropic/claude-opus-4-7) <noreply@mastra.ai>

…e, manual mutation check (#1121) * docs(ai-traps): test-quality traps — change detectors, string-presence, manual mutation check Extends the shipped AI-traps catalogue with four additions, keeping the file's trap -> "Caught by" structure (the enforcement-layer column is what this doc adds over prose-style guidance elsewhere). 1. §3 Tautological tests — adds the authoring-time criterion ("which production change would make this test fail, and is it a bug or a decision?") with its three outcomes, names the change-detector failure mode, and adds a mirror-assertion example where both sides are computed by the SUT. 2. §12 (new) String-presence assertions on scripts, skills, and prompts — grepping a .md/.sh for the text it should contain proves only that the source is the source. States the observable alternative per artifact kind, and is explicit that no deterministic layer catches this: the arms are the RED->GREEN liveness fixtures and AI judgment. 3. Manual mutation check — the five mutation classes (wrong constant or argument, wrong branch, missing side effect, empty/default return, missing validation) for surfaces Stryker does not reach. Framed as authoring-time discipline, not a gate; notes the repo's own on-demand bash mutator is a local dev tool, not part of the consumer install. 4. Prior-art section citing the two convergent external sources. Both shipped copies updated: skills/ (source form, relative refs transformed at install time) and plugin/skills/ (pre-rendered absolute refs for the plugin + OpenCode channel). The two stay at their single intended line-6 delta. Install fingerprints regenerated — 8 npm-stack baselines shift by exactly one hash line (.claude/skills/getff/references/ai-traps.md); python/cargo baselines do not ship the skill and are unchanged. Prior-art: skipped — documentation edit to an existing shipped reference doc; no new dependency, no new module, no new capability. External sources are cited as REFERENCE-class convergent confirmation (obra/superpowers writing-good-tests v6.2.0 MIT, paraphrased not copied; Google Testing Blog change-detector post). Nearest existing SSOT row is #55 (obra/superpowers TDD discipline, ADAPT) — same upstream project, adjacent but distinct file, so no new SSOT entry is warranted. * docs(ai-traps): thin-wrapper the borrowed TDD material, keep the enforcement column Rewrites the §3 criterion and the mutation check so this document carries only its own niche, per the ADOPT-as-base/thin-wrapper precedent already recorded in the prior-art SSOT (#113) and the shipped companion-pointer pattern in plugin/hooks/lang/en.sh:35. - §3 authoring-time criterion: restated in this document's own words as a compact trap statement; the fuller authoring workflow now points at the `superpowers:test-driven-development` companion skill "where installed", with the trap standing on its own where it is not. - Mirror-assertion example replaced with an original one (formatBytes) — the previous example was lifted verbatim from upstream and the prose n-gram probe could not see it, because it strips code fences. - Mutation check: the five break classes reworded as the classic mutation-operator families they are, with a pointer to the companion's closing walk-through. - Prior-art entry now states the division of labour explicitly (upstream owns the authoring workflow; this document owns trap -> enforcement layer) and records the companion's opt-in status. Nothing here hard-depends on the companion: every pointer is conditional, matching the shipped-axis rule in .claude/rules/build-first-reuse-default.md §1.1 ("integrate, never hard-depend"). Acceptance: n-gram probe against the upstream file reports 0 shared sequences at n=6 over prose and n=4 over fenced code (previous run: 6 prose sequences, longest 13 words, plus an undetected verbatim example). make self-audit exit 0; snapshot compare 13 pass / 0 fail; the 8 npm-stack fingerprints shift by exactly one hash line each. Prior-art: skipped — documentation edit that REDUCES borrowed content in an existing shipped reference doc; no new dependency, no new module, no new capability. Applies the thin-wrapper shape from SSOT #113 (obra/superpowers writing-skills, ADOPT as base + project residue) to a sibling upstream file rather than introducing a new upstream relationship. * fix(audit-ai-docs): un-break D5 on the real repo and re-sync the two implementations D5 ("every file carrying the canonical goal phrase is enrolled or exempt") was red on a clean staging checkout, and the .sh and .ts implementations had drifted apart. Neither was noticed because nothing runs the probe over the real repository: pre-push (`auditAiDocsSection`) and audit-self.yml both run `vitest audit-ai-docs.test.ts`, which exercises synthetic fixtures in temp dirs only. Three defects, all pre-existing on staging: 1. `plugin/hooks/inject-session-bootstrap` carried the phrase and matched no exemption, so D5 failed. It is a generated twin — the generator copied the phrase out of `.claude/hooks/inject-session-bootstrap.sh`, which is itself enrolled. New GENERATED_TWIN exemption added to both implementations, content-gated on the generator's own header rather than on the path, because `generate-plugin-twins.sh` also supports a `manual` mode whose twins are hand-maintained and do deserve independent tracking. 2. `AGENTS.md` was enrolled in DOWNSTREAM_DOCS by #867 in the .sh probe only; the .ts port (#120) never received it, so the .ts probe reported the repo's own AGENTS.md as an orphan. 3. `packages/core/hooks/inject-session-bootstrap.test.ts` was in the .sh TEST_INFRA set but not the .ts one; `.stryker-tmp/` + `.stryker/` were in the .ts GITIGNORED set but not the .sh one. Both directions re-synced. Paired arms shipped for the new exemption: a twin carrying the generator header is exempt, a hand-written `plugin/hooks/*` file with the phrase is still flagged. Without the negative arm the exemption could silently widen to the whole directory. One existing test changed: the D1-warn case built its fixture by looping over DOWNSTREAM_DOCS and relied on AGENTS.md being absent from that list to leave the file uncreated. Enrolling AGENTS.md made that dependency explicit — the loop now skips it deliberately, with the reason recorded inline. `audit-ai-docs.sh` ships to consumers as `scripts/audit-ai-docs.sh`, so the 8 npm-stack install fingerprints shift by exactly one hash line each. Verified: bash probe 4 PASS / 0 FAIL (was 3 PASS / 1 FAIL); .ts probeD5 over the real repo returns 0 findings (was 3); audit-ai-docs.test.ts 202 passed; make self-audit exit 0; snapshot compare 13 pass / 0 fail; twin generator idempotent (no diff after re-run); shellcheck unchanged vs staging (rc=1, same two pre-existing SC2001 style hits on untouched lines). Also fixes the stale self-reference in the M2 fixture README header, which named `agents/fixtures/shipped-agent-liveness` — a path that exists nowhere else in the repo; every other reference already points at `tests/fixtures/`. Prior-art: skipped — bug fix plus test coverage for an existing probe; no new dependency, no new module, no new capability. The GENERATED_TWIN exemption encodes an existing repo mechanism (scripts/generate-plugin-twins.sh) rather than introducing one.

artyhoo added 3 commits May 16, 2026 14:55

artyhoo mentioned this pull request May 16, 2026

docs(research-patches): B+C session + parallel + errata + 2 mechanical fixes #56

Merged

4 tasks

artyhoo merged commit 4a1b5e2 into main May 16, 2026
17 checks passed

This was referenced May 21, 2026

feat(principles): principle 15 — skill paired-negative test (N2 #5, Commit B) #112

Merged

feat(principles): principle 15 — skill paired-negative test (N2 #5, Commit B) #111

Closed

This was referenced May 21, 2026

docs: §13.36 TDD-for-Skills ARMED→RESOLVED (shipped as principle 15) #113

Merged

Wave 10.2 — port §7 Prior-art trailer to TS (prior-art.ts) #114

Merged

artyhoo deleted the docs/research-patches-2026-05-16 branch May 22, 2026 18:09

artyhoo mentioned this pull request May 31, 2026

docs(meta-factory): companion-capability-survey — Superpowers / Superset / aif-handoff vs /meta-orchestrator pipeline (5 SSOT rows #92-#96 + 2 updates) #321

Merged

7 tasks

This was referenced Jun 13, 2026

feat(guard-liveness): v3 manual-rule SP-prober (reduced) — pressure-scenario schema + prober + 5 migrations #472

Closed

feat(guard-liveness): v3 manual-rule SP-prober (reduced) — pressure-scenario schema + prober + 5 migrations #473

Closed

artyhoo mentioned this pull request Jul 22, 2026

feat(rule-tests): S1 — write-half protocol + thin skill trigger (rule-tests-surface S1) #1089

Merged

artyhoo mentioned this pull request Jul 31, 2026

fix(arch-v2-s-a): S-A stage — round-1 delivery + round-2 rework from acceptance #1192

Merged

13 tasks

Navigation Menu

docs(research-patches): commit 3 patches from 2026-05-16 autonomous research session - #55

docs(research-patches): commit 3 patches from 2026-05-16 autonomous research session#55
artyhoo merged 4 commits into
mainfrom
docs/research-patches-2026-05-16

artyhoo commented May 16, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

artyhoo commented May 16, 2026

Summary

Scope

Mechanical fixes during commit

§1.7 — Skipped (mechanical maintenance commit)

Test plan

Related

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant