diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json index 16cf360..1a9c028 100644 --- a/.agents/plugins/marketplace.json +++ b/.agents/plugins/marketplace.json @@ -1,11 +1,19 @@ { "name": "engineering-method", - "interface": {"displayName": "Engineering Method"}, + "interface": { + "displayName": "Engineering Method" + }, "plugins": [ { "name": "engineering-method", - "source": {"source": "local", "path": "./"}, - "policy": {"installation": "AVAILABLE", "authentication": "ON_INSTALL"}, + "source": { + "source": "local", + "path": "./" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, "category": "Developer Tools" } ] diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 6872fa5..3b89c77 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "engineering-method", - "version": "0.2.1", + "version": "0.3.0", "description": "Risk-proportionate engineering workflows for Codex, Claude and OpenCode.", "author": { "name": "Peter Hense" diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 859a51a..1c50795 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "engineering-method", - "version": "0.2.1", + "version": "0.3.0", "description": "Risk-proportionate engineering workflows for Codex, Claude and OpenCode.", "author": { "name": "Peter Hense" diff --git a/.github/workflows/verify.yml b/.github/workflows/verify.yml new file mode 100644 index 0000000..49fe979 --- /dev/null +++ b/.github/workflows/verify.yml @@ -0,0 +1,17 @@ +name: Verify +on: [push, pull_request] +permissions: + contents: read +jobs: + verify: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Install skill-discovery test dependency + run: | + sudo apt-get update + sudo apt-get install --yes ripgrep + - name: Validate bundled resources and provenance + run: python3 scripts/validate-plugin + - name: Test real local behavior + run: python3 -m unittest discover -s tests -t . -v diff --git a/.gitignore b/.gitignore index a951c75..25be9a1 100644 --- a/.gitignore +++ b/.gitignore @@ -7,3 +7,8 @@ __pycache__/ htmlcov/ /dist/ /release-evidence/ + +.method-core-sync.lock +.method-core-transaction/ +.method-core-stage-*/ +.method-core-retired-*/ diff --git a/BACKLOG.md b/BACKLOG.md index dedb6a6..86c30cb 100644 --- a/BACKLOG.md +++ b/BACKLOG.md @@ -117,6 +117,9 @@ Keep stable IDs unchanged. Order groups unblocker-first, then priority and depen - ✅ `EM-017` **P1** Publish the professional PDF template as patch release 0.2.1 - Depends on: `EM-016` - Notes: Published stable Latest v0.2.1 from 49aa3c6; 319 tests, native PDF checks, validators, reproducible 256-file package and clean installs passed. Downloaded asset matches 2a0d0b6d520d509276c7d04d80b83a43a5aada78132d1ae48461c03fe3c21693. + +- ✅ `EM-018` **P1** Split shared core, engineering and writing methods into three repositories + - Notes: Split published: phense/method-core 255026b, phense/writing-method e9eab64; integration PR #135. Suites 159/335/163, isolated package recovery and native coexistence passed. Both fresh GitHub checks passed on bf0571f after the explicit ripgrep dependency fix. User authorized merge. Evidence: docs/verification/EM-018-method-split.md. Global profiles remain unchanged. - ✅ `EM-005` **P2** Validate, document, and package the complete plugin - Depends on: `EM-001`, `EM-004` @@ -150,3 +153,6 @@ Keep stable IDs unchanged. Order groups unblocker-first, then priority and depen - ✅ `EM-007` **P2** Publish stable version 0.1.0 and update public documentation - Depends on: `EM-005` - Notes: Published v0.1.0 at e9f5130 as stable Latest with checked ZIP and SHA256SUMS. 308 tests, validators, provenance, reproducible packaging, both clean installs, downloaded bytes and GitHub/main plus fixed-tag installs verified. Prior rc.1 unchanged; no issue migration. + +- ⭕ `EM-019` **P3** Verify a Gemini host adapter in Method Core + - Notes: Deferred from EM-018; shared adapter ownership is phense/method-core. No Gemini support claimed until fresh native discovery and behavior checks pass. diff --git a/CORE_NOTICES.md b/CORE_NOTICES.md new file mode 100644 index 0000000..db1e505 --- /dev/null +++ b/CORE_NOTICES.md @@ -0,0 +1,128 @@ +# Third-Party Notices + +This plugin adapts only the files listed below. Immutable source hashes and current destination hashes are recorded in the corresponding source lock. + +## Original implementation + +Copyright (c) 2026 Peter Hense. Original code is MIT licensed. Core preserves adapted source attribution below; it owns only the explicitly exported shared files. + +## Superpowers + +Source ID: `superpowers` + +Repository: https://github.com/obra/superpowers.git + +Revision: `b36e0829c6d0140e93cfef2ca599b1b07d4a7797` + +License SHA-256: `a37e0e9697144819e1d965176ac4ae5bc3fa02d11e7812036bbcadf6dafe2400` + +`LICENSE -> THIRD_PARTY_NOTICES.md: notice-only` + +Copyright (c) 2025 Jesse Vincent + +Curated quality practices and adapted report, brief, review and recovery mechanics for cohesive slices, proportional review and protected project-state storage. + +- `skills/verification-before-completion/SKILL.md` -> `skills/verification-before-completion/SKILL.md`: adapted +- `skills/requesting-code-review/SKILL.md` -> `skills/requesting-code-review/SKILL.md`: adapted +- `skills/requesting-code-review/code-reviewer.md` -> `skills/requesting-code-review/code-reviewer.md`: adapted +- `skills/receiving-code-review/SKILL.md` -> `skills/receiving-code-review/SKILL.md`: adapted +- `skills/using-git-worktrees/SKILL.md` -> `skills/using-git-worktrees/SKILL.md`: adapted +- `skills/dispatching-parallel-agents/SKILL.md` -> `skills/dispatching-parallel-agents/SKILL.md`: adapted +- `skills/subagent-driven-development/implementer-prompt.md` -> `templates/orchestration/agent-report.md`: adapted +- `skills/subagent-driven-development/task-reviewer-prompt.md` -> `shared/agent-roles/reviewer.md`: adapted +- `skills/subagent-driven-development/re-review-prompt.md` -> `templates/orchestration/review-report.md`: adapted +- `skills/subagent-driven-development/scripts/sdd-workspace` -> `shared/policies/continuity-contract.md`: adapted +- `skills/subagent-driven-development/scripts/sdd-workspace` -> `templates/orchestration/resume.md`: adapted + +MIT License + +Copyright (c) 2025 Jesse Vincent + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + +## sre-runbook-agent-skills + +Source ID: `sre-runbook-agent-skills` + +Repository: https://github.com/medzin/sre-runbook-agent-skills.git + +Revision: `44ab3d87293788036013098868563f82a3369b81` + +License SHA-256: `f114aa5869612318e5c35fb10175e322e1feec5039bddf321a1822edf2737cf6` + +`LICENSE -> THIRD_PARTY_NOTICES.md: notice-only` + +Copyright (c) 2026 Adam Medziński + +Adapted selected playbook authoring/review and evidence rules for development and system deliverables, conditional lifecycle support and existing authority; removed incident-only and host-specific requirements. + +- `skills/sre-runbook-author/SKILL.md` -> `skills/playbook-authoring/SKILL.md`: adapted +- `skills/sre-runbook-author/references/runbook-template.md` -> `templates/playbooks/playbook.md`: adapted +- `skills/sre-runbook-reviewer/SKILL.md` -> `skills/playbook-review/SKILL.md`: adapted +- `skills/sre-runbook-reviewer/references/review-scorecard.md` -> `templates/playbooks/review.md`: adapted + +MIT License + +Copyright (c) 2026 Adam Medziński + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. +``` + +## han + +Source ID: `han` + +Repository: https://github.com/testdouble/han.git + +Revision: `19cb21bcb1154d29bf20d1f3c9ad4854a59580d2` + +License SHA-256: `9940ab927f654e997d00aedc6a8734be0600f9443377697419ee7ed4247f2d36` + +`LICENSE -> THIRD_PARTY_NOTICES.md: notice-only` + +Copyright 2026 Test Double, Inc. + +Adapted selected playbook authoring/review and evidence rules for development and system deliverables, conditional lifecycle support and existing authority; removed incident-only and host-specific requirements. + +- `han-documentation/skills/runbook/SKILL.md` -> `shared/policies/playbooks.md`: adapted + +Copyright 2026 Test Double, Inc. + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +``` diff --git a/FEATURES.md b/FEATURES.md index ca7c5b0..ec475af 100644 --- a/FEATURES.md +++ b/FEATURES.md @@ -51,23 +51,32 @@ This inventory records implemented, changed, and historically removed capabiliti - Summary: Source-linked additive skill and adapter loading with guarded reversible installation; 17 skills discovered and bounded DeepSeek skill use verified on OpenCode 1.18.30. Full lifecycle and RAG hooks are outside this acceptance. - Related backlog: `EM-008` - + ## `F-008` Scale-aware documentation and reader-oriented writing -- Status: available +- Status: removed - Summary: Writing-depth scale decision (small, medium, large); documentation-planning, documentation-authoring and documentation-review lifecycle with plan, chunk manifest, glossary, asset manifest and review templates under docs/writing; didactic skills explaining-concepts, writing-procedures and empathic-troubleshooting applied to documentation and ordinary replies; terminology-guard and visual-placeholders; human-prose-drafting (adapted from Humanizer, MIT) applied while drafting medium and large texts. Contract tests and validators pass; five bounded native routing cases pass on both Codex and Claude, with OpenCode pre-draft Humanizer invocation verified. These probes do not claim full document quality. - Related backlog: `EM-009`, `EM-010`, `EM-011`, `EM-013` +- Removal rationale: Moved unchanged writing responsibilities into standalone phense/writing-method 0.1.0 by EM-018; no longer bundled in engineering-method 0.3.0. - + ## `F-009` Local Markdown book PDF export -- Status: changed +- Status: removed - Summary: Optional documentation-pdf skill with a professional A4 Quarto/Typst template: dark-navy editorial hierarchy, separate cover and contents, 12 pt body text, ordered Markdown chapters, linked contents and current/total page numbers. Native macOS English, German and long-table checks pass; PDF skill selection is verified on Codex, Claude and OpenCode. Rendering remains local. - Related backlog: `EM-012`, `EM-013`, `EM-016` +- Removal rationale: PDF skill, templates and existing render checker moved to phense/writing-method by EM-018; all twelve template files remain byte-identical to the prior engineering revision. + + +## `F-010` Shared playbook authoring and acceptance + +- Status: changed +- Summary: Generic scenario-bound authoring and review are owned by phense/method-core and bundled identically into both methods; engineering lifecycle hooks remain in engineering-method. Draft, review and authorized rehearsal remain separate evidence. +- Related backlog: `EM-014`, `EM-018` - -## `F-010` Engineering playbook authoring and acceptance + +## `F-011` Independent engineering and writing packages with pinned shared core - Status: available -- Summary: Two supporting skills distinguish development-operation and system-deliverable playbooks, with phase-specific need assessment, authoring/review templates, interruption and rollback paths, and separate current review and rehearsal evidence. Local contracts, independent instruction scenarios and disposable Claude/Codex installation verified; no native-host routing or operational rehearsal claimed. -- Related backlog: `EM-014` +- Summary: Engineering 0.3.0 and Writing 0.1.0 bundle the same 69 immutable Core exports and eight shared support skills. Full suites pass (335 engineering, 163 writing, 159 core), isolated package state/recovery and disposable native installation/coexistence pass. No fresh live model routing, PDF render or global profile rollout claimed. +- Related backlog: `EM-018` diff --git a/README.md b/README.md index 323fce8..bc92337 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ intended scope. The earlier `v0.1.0-rc.1` pre-release remains available with its original, reduced acceptance scope. -Release 0.2.1 retains the 0.2.0 scale-aware documentation, Humanizer drafting, +The historical release 0.2.1 retained the 0.2.0 scale-aware documentation, Humanizer drafting, playbook and read-only state-check work while refining the local Quarto/Typst PDF export. [Its verification](docs/verification/EM-013-prepublication.md) covers 319 local tests, five documentation routing cases on each of Codex and Claude, and @@ -32,14 +32,25 @@ two bounded native OpenCode probes; the [playbook record](docs/verification/EM-014-playbooks.md) adds no native routing evaluation. +## Related methods and shared core + +This branch is the 0.3.0 source candidate. The previous stable release is 0.2.1; no 0.3.0 release tag is claimed. + +Version 0.3.0 separates writing into [Writing Method](https://github.com/phense/writing-method). [Method Core](https://github.com/phense/method-core) owns the bundled host adapters, state/continuity tools, verification/review/isolation support and generic playbooks. Each repository keeps its own Issues and pull requests; the common topic is `agent-methods`. + +Engineering owns Spec Kit, OpenSpec, architecture, debugging and TDD. Writing owns documentation planning, authoring, review, didactic guidance and PDF delivery. Each plugin runs independently. Both expose byte-identical shared support under their own namespaces; invoke the current method's copy, for example `engineering-method:playbook-authoring`, once. Core is bundled source, not a third plugin installation. Gemini adapter work remains deferred. + +Shared changes originate in Core. From this checkout run `python3 /absolute/path/to/method-core/scripts/sync-core --source-root /absolute/path/to/method-core --target-root .`, then `python3 scripts/sync-core --check` and the verification commands below. Commit copies and `method-core.lock.json` together. Sync refuses local drift and unowned conflicts; write failures attempt restoration of the previous files/modes/lock. After a process abort or incomplete rollback, fix the reported disk/permission error and run `python3 scripts/sync-core --recover` before retrying; original backups remain until recovery succeeds. To roll back, synchronize the previous full Core revision with `--revision`. Existing `engineering_method` imports, CLI wrapper names, project `.engineering-method/` state and work IDs remain unchanged. Reinstall copied host plugins and restart the session after updating. + + ## Installation Requires Python 3.11+, Git, and Codex CLI, Claude Code or OpenCode. OpenCode uses the separate source-linked installation described below. GitHub task synchronization additionally requires authenticated `gh` and repository permissions. No upstream Spec Kit, OpenSpec or Superpowers installation is needed. -Current local package installation was checked with Codex CLI 0.154.0 and -Claude Code 2.1.272; +The 0.3.0 candidate's local package installation and coexistence were checked with Codex CLI 0.169.0 and +Claude Code 2.1.323; other host versions and operating systems are not covered by that evidence. Install from [phense/engineering-method](https://github.com/phense/engineering-method): @@ -82,8 +93,6 @@ lifecycle rather than start competing plans. | Bounded intentional change to existing behavior | OpenSpec `propose` → `apply` → `archive` | | New subsystem, multi-component feature, architecture change or risky migration | Spec Kit `specify` → `plan` → architecture gate → `tasks` → orchestrated implementation → `converge` | | Existing Spec Kit or OpenSpec artifacts | Continue the recorded phase; preserve completed work | -| One standalone reader-facing document | `documentation-authoring` in standalone mode with the didactic writing skills | -| Documentation set: several chapters or readers sharing terms, structure and images | `documentation-planning` → `documentation-authoring` per chunk → `documentation-review` | Review, TDD, worktrees and parallel dispatch activate only when their own conditions apply. If a bounded change reveals architectural scope, its formal @@ -113,40 +122,10 @@ the [bounded verification record](docs/verification/EM-014-playbooks.md). ## Documentation and reader-oriented writing -Prose deliverables decide their scale first with the -[writing-depth policy](shared/policies/writing-depth.md): a wording fix stays a -focused edit, one document uses `documentation-authoring` directly, and a -manual or handbook runs through planning, per-chunk authoring and set-wide -review with checkpoints across sessions. Plans, glossaries, asset manifests and -review reports live under `docs/writing//`; chapters are one Markdown -file per chunk with uniform frontmatter. - -Three didactic skills shape the text and, through the -[reader-oriented output policy](shared/policies/reader-oriented-output.md), -ordinary replies as well: `explaining-concepts` introduces each concept with -an everyday analogy before the mechanism and removes undefined jargon; -`writing-procedures` writes imperative single-action steps in blocks of three -to five with exact locations, prerequisites and a check that it worked; -`empathic-troubleshooting` starts from the symptom the reader sees. All three -apply the shared curse-of-knowledge filter that writes out the steps and -locations an expert would skip. Medium and large texts are drafted under -`human-prose-drafting`, an adaptation of Humanizer's AI-writing patterns -applied while writing, so finished documentation needs no separate -humanizing pass. `terminology-guard` keeps one term per concept -across hundreds of pages, and `visual-placeholders` inserts standardized -screenshot and diagram callouts with alt text and capture instructions. - -For a requested PDF, `documentation-pdf` uses a reusable Quarto/Typst -[manual template](templates/documentation/pdf/DESIGN.md). It combines Markdown -chapters in the accepted order with central branding, a linked contents page -and current/total page numbers. Quarto is an optional local export dependency; -see the [native export verification](docs/verification/EM-012-quarto-pdf.md) -and the [professional A4 design revision](docs/verification/EM-016-pdf-design.md). -An accepted documentation plan continues directly with authoring. Planning is -selected again only for changes to the set structure, readers or manifest. -The [routing checks](docs/verification/EM-013-routing-results.json) include -Humanizer preparation at medium and large scales and PDF export selection; -they do not claim complete authored-document quality. +Writing workflows and their local PDF template live in the optional +[Writing Method](https://github.com/phense/writing-method) companion. Install +it when documentation planning, drafting, didactic support or PDF delivery is +needed. Engineering Method keeps engineering artifacts and its own work IDs. ## Architecture and review diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md index 95dabd5..b83c1db 100644 --- a/THIRD_PARTY_NOTICES.md +++ b/THIRD_PARTY_NOTICES.md @@ -1,45 +1,28 @@ # Third-Party Notices -This plugin adapts only the files listed below from the pinned upstream revisions. Each -`LICENSE -> THIRD_PARTY_NOTICES.md` mapping is `notice-only`; adapted mappings -record both immutable source and current destination SHA-256 hashes in -`third-party/sources.lock.json`. +This plugin adapts only the files listed below; shared mappings are recorded in Core notices. ## Original implementation -Copyright (c) 2026 Peter Hense. MIT licensed under the repository `LICENSE`. -The Python project-state implementation, architecture-modeling and project-backlog -skills, UML templates, host adapters, evaluation and packaging tooling, and tests -are original. Shared orchestration policy is original except for the specific -adapted role, report, recovery and helper mechanics mapped below. The source lock -explicitly identifies original paths separately from adapted destinations. - -Modifications replace upstream runtime dependencies with shared artifact -contracts, exclusive lifecycle boundaries, risk-proportionate depth and tested -continuity. EM-004 additionally hardens output containment, cohesive task handoffs -and architecture evidence. No upstream CLI or full methodology is redistributed. - -EM-010 adds original documentation and reader-oriented writing skills, the -writing-depth and reader-oriented-output policies, the shared curse-of-knowledge -filter and the documentation templates. They were written from public style -guides and framework descriptions cited in -`docs/verification/EM-010-documentation-skills.md`; no third-party text was -copied and no upstream mapping applies. +Copyright (c) 2026 Peter Hense. Original code is MIT licensed. Shared adapted files and their licenses are separately recorded in [Core notices](CORE_NOTICES.md) and `third-party/core-sources.lock.json`. + +`templates/openspec/escalation.md`: original when distributed. ## Spec Kit -- Repository: https://github.com/github/spec-kit.git -- Revision: `df6b3187022ce986759bd854467e8a4bb56bb0f4` -- License: MIT (`LICENSE`) -- License SHA-256: `2510b446bc1f0cf9702453075d20cd88631e20e5642658edb7325d9c1eb534f7` -- Copyright holder: GitHub, Inc. -- `LICENSE -> THIRD_PARTY_NOTICES.md: notice-only` +Source ID: `github-spec-kit` + +Repository: https://github.com/github/spec-kit.git + +Revision: `df6b3187022ce986759bd854467e8a4bb56bb0f4` + +License SHA-256: `2510b446bc1f0cf9702453075d20cd88631e20e5642658edb7325d9c1eb534f7` + +`LICENSE -> THIRD_PARTY_NOTICES.md: notice-only` -Adapted in EM-003: +Copyright GitHub, Inc. -Task 6 and its integration review further adapt the four -`skills/speckit-*/SKILL.md` destinations below to add host-observed recovery and -ordered project-state event/checkpoint handoffs. +Adapted specification, planning, task and convergence artifacts with exclusive lifecycles, host-neutral recovery, cohesive slices and append-only fix handoffs. - `templates/spec-template.md` -> `templates/spec-kit/spec.md`: adapted - `templates/plan-template.md` -> `templates/spec-kit/plan.md`: adapted @@ -73,18 +56,19 @@ SOFTWARE. ## OpenSpec -- Repository: https://github.com/Fission-AI/OpenSpec.git -- Revision: `e062b9572be933564ba3899d059377dfa1393e32` -- License: MIT (`LICENSE`) -- License SHA-256: `c3c7235bea1214ab62df643473975c2e8b8848f528901a976693f7d069713e64` -- Copyright holder: 2024 OpenSpec Contributors -- `LICENSE -> THIRD_PARTY_NOTICES.md: notice-only` +Source ID: `openspec` + +Repository: https://github.com/Fission-AI/OpenSpec.git + +Revision: `e062b9572be933564ba3899d059377dfa1393e32` + +License SHA-256: `c3c7235bea1214ab62df643473975c2e8b8848f528901a976693f7d069713e64` + +`LICENSE -> THIRD_PARTY_NOTICES.md: notice-only` -Adapted in EM-003: +Copyright (c) 2024 OpenSpec Contributors -Task 6 and its integration review further adapt the three -`skills/openspec-*/SKILL.md` destinations below to add host-observed recovery and -ordered project-state event/checkpoint handoffs. +Adapted bounded-change proposal, delta specification, application and archival artifacts without upstream CLI dependencies; added explicit escalation and continuity. - `skills/openspec-propose/SKILL.md` -> `templates/openspec/proposal.md`: adapted - `skills/openspec-propose/SKILL.md` -> `templates/openspec/design.md`: adapted @@ -94,10 +78,6 @@ ordered project-state event/checkpoint handoffs. - `skills/openspec-apply-change/SKILL.md` -> `skills/openspec-apply/SKILL.md`: adapted - `skills/openspec-archive-change/SKILL.md` -> `skills/openspec-archive/SKILL.md`: adapted -Original in EM-003: - -- `templates/openspec/escalation.md`: original; no upstream text was adapted - MIT License Copyright (c) 2024 OpenSpec Contributors @@ -122,126 +102,32 @@ SOFTWARE. ## Superpowers -- Repository: https://github.com/obra/superpowers.git -- Revision: `b36e0829c6d0140e93cfef2ca599b1b07d4a7797` -- License: MIT (`LICENSE`) -- License SHA-256: `a37e0e9697144819e1d965176ac4ae5bc3fa02d11e7812036bbcadf6dafe2400` -- Copyright holder: 2025 Jesse Vincent -- `LICENSE -> THIRD_PARTY_NOTICES.md: notice-only` +Source ID: `superpowers` -Adapted in EM-003: +Repository: https://github.com/obra/superpowers.git -Task 6 and its integration review further adapt -`skills/systematic-debugging/SKILL.md` to add host-observed recovery and ordered -project-state event/checkpoint handoffs. +Revision: `b36e0829c6d0140e93cfef2ca599b1b07d4a7797` -- `skills/systematic-debugging/SKILL.md` -> `skills/systematic-debugging/SKILL.md`: adapted -- `skills/test-driven-development/SKILL.md` -> `skills/test-driven-development/SKILL.md`: adapted -- `skills/test-driven-development/writing-good-tests.md` -> `skills/test-driven-development/writing-good-tests.md`: adapted -- `skills/verification-before-completion/SKILL.md` -> `skills/verification-before-completion/SKILL.md`: adapted -- `skills/requesting-code-review/SKILL.md` -> `skills/requesting-code-review/SKILL.md`: adapted -- `skills/requesting-code-review/code-reviewer.md` -> `skills/requesting-code-review/code-reviewer.md`: adapted -- `skills/receiving-code-review/SKILL.md` -> `skills/receiving-code-review/SKILL.md`: adapted -- `skills/using-git-worktrees/SKILL.md` -> `skills/using-git-worktrees/SKILL.md`: adapted -- `skills/dispatching-parallel-agents/SKILL.md` -> `skills/dispatching-parallel-agents/SKILL.md`: adapted - -Adapted in EM-004 from the pinned subagent-driven-development sources: - -- `skills/subagent-driven-development/SKILL.md` -> `skills/orchestrated-implementation/SKILL.md`: adapted for cohesive slices, risk-proportionate review, and the EM-002 continuity seam -- `skills/subagent-driven-development/implementer-prompt.md` -> `shared/agent-roles/implementer.md`: adapted into a host-neutral role contract -- `skills/subagent-driven-development/implementer-prompt.md` -> `templates/orchestration/agent-report.md`: adapted into a durable report schema -- `skills/subagent-driven-development/implementer-prompt.md` -> `templates/orchestration/slice-brief.md`: adapted into a cohesive-slice brief -- `skills/subagent-driven-development/task-reviewer-prompt.md` -> `shared/agent-roles/reviewer.md`: adapted into a risk-proportionate reviewer role -- `skills/subagent-driven-development/re-review-prompt.md` -> `templates/orchestration/review-report.md`: adapted into a scoped review/fix report -- `skills/subagent-driven-development/scripts/task-brief` -> `scripts/task-brief`: adapted for Spec Kit slices and work-ID run paths -- `skills/subagent-driven-development/scripts/review-package` -> `scripts/review-package`: adapted for complete commit ranges and work-ID run paths -- `skills/subagent-driven-development/scripts/sdd-workspace` -> `shared/policies/continuity-contract.md`: adapted to consume the EM-002 run contract -- `skills/subagent-driven-development/scripts/sdd-workspace` -> `templates/orchestration/resume.md`: adapted into a compaction-safe recovery brief +License SHA-256: `a37e0e9697144819e1d965176ac4ae5bc3fa02d11e7812036bbcadf6dafe2400` -MIT License +`LICENSE -> THIRD_PARTY_NOTICES.md: notice-only` Copyright (c) 2025 Jesse Vincent -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. - -## Humanizer - -- Repository: https://github.com/blader/humanizer.git -- Revision: `9862685f575c65a8247f90369951df1b3416e3d6` -- License: MIT (`LICENSE`) -- License SHA-256: `4ac4810254ab36d45419141aeb8e69bf50652cfafe5b2dab947d06d44e5cbf96` -- Copyright holder: 2025 Siqi Chen -- `LICENSE -> THIRD_PARTY_NOTICES.md: notice-only` - -Adapted in EM-011: - -- `SKILL.md` -> `skills/human-prose-drafting/SKILL.md`: adapted - -The upstream skill rewrites finished AI-sounding text in a separate pass. The -adaptation turns its 25 patterns into constraints applied while drafting -medium and large documentation, condenses them into groups by strength, -removes the pasted-text, file and voice-matching modes, and adds a per-chunk -check and documentation voice rules. Upstream credits Wikipedia's "Signs of AI -writing" (WikiProject AI Cleanup) as the pattern source. +Curated quality practices and adapted report, brief, review and recovery mechanics for cohesive slices, proportional review and protected project-state storage. -MIT License - -Copyright (c) 2025 Siqi Chen - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. - -## medzin/sre-runbook-agent-skills - -Source: https://github.com/medzin/sre-runbook-agent-skills.git - -License: MIT (`LICENSE`); SHA-256: `f114aa5869612318e5c35fb10175e322e1feec5039bddf321a1822edf2737cf6`. - -Pinned revision: `44ab3d87293788036013098868563f82a3369b81`. Selected authoring, review and validation mechanics -are adapted for the Engineering Method playbook support; see the source lock -for file mappings and modification details. - -- `LICENSE` -> `THIRD_PARTY_NOTICES.md`: notice-only -- `skills/sre-runbook-author/SKILL.md` -> `skills/playbook-authoring/SKILL.md`: adapted -- `skills/sre-runbook-author/references/runbook-template.md` -> `templates/playbooks/playbook.md`: adapted -- `skills/sre-runbook-reviewer/SKILL.md` -> `skills/playbook-review/SKILL.md`: adapted -- `skills/sre-runbook-reviewer/references/review-scorecard.md` -> `templates/playbooks/review.md`: adapted +- `skills/systematic-debugging/SKILL.md` -> `skills/systematic-debugging/SKILL.md`: adapted +- `skills/test-driven-development/SKILL.md` -> `skills/test-driven-development/SKILL.md`: adapted +- `skills/test-driven-development/writing-good-tests.md` -> `skills/test-driven-development/writing-good-tests.md`: adapted +- `skills/subagent-driven-development/SKILL.md` -> `skills/orchestrated-implementation/SKILL.md`: adapted +- `skills/subagent-driven-development/implementer-prompt.md` -> `shared/agent-roles/implementer.md`: adapted +- `skills/subagent-driven-development/implementer-prompt.md` -> `templates/orchestration/slice-brief.md`: adapted +- `skills/subagent-driven-development/scripts/task-brief` -> `scripts/task-brief`: adapted +- `skills/subagent-driven-development/scripts/review-package` -> `scripts/review-package`: adapted -```text MIT License -Copyright (c) 2026 Adam Medziński +Copyright (c) 2025 Jesse Vincent Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal @@ -260,27 +146,3 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -``` - -## testdouble/han - -Source: https://github.com/testdouble/han.git - -License: MIT (`LICENSE`); SHA-256: `9940ab927f654e997d00aedc6a8734be0600f9443377697419ee7ed4247f2d36`. - -Pinned revision: `19cb21bcb1154d29bf20d1f3c9ad4854a59580d2`. Selected authoring, review and validation mechanics -are adapted for the Engineering Method playbook support; see the source lock -for file mappings and modification details. - -- `LICENSE` -> `THIRD_PARTY_NOTICES.md`: notice-only -- `han-documentation/skills/runbook/SKILL.md` -> `shared/policies/playbooks.md`: adapted - -```text -Copyright 2026 Test Double, Inc. - -Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -``` diff --git a/docs/installation.md b/docs/installation.md index 26c9e55..a1fd10a 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -10,6 +10,16 @@ since 0.1.1. Its native discovery and bounded DeepSeek test were checked with OpenCode 1.18.30; see the [0.1.1 release scope](releases/0.1.1.md) and the [0.2.1 release notes](releases/0.2.1.md). +## Split source candidate + +The EM-018 branch describes engineering-method 0.3.0, with writing-method 0.1.0 +as a separate optional plugin and shared support bundled from method-core. +Tagged release commands below continue to refer to the previous stable 0.2.1 +until a new release is published. To inspect the split, clone/check out +`em-018-method-split` and register that retained checkout using the local +marketplace commands in the README. Existing project-state data remains usable. + + ## Install from GitHub The marketplace and plugin both use the name `engineering-method`. @@ -136,3 +146,5 @@ host configuration can test installation without copying credentials. Loading a plugin is distinct from authenticated model execution. See the [Codex](../shared/platform/codex.md) and [Claude](../shared/platform/claude.md) adapters for capability and authentication boundaries. + +For an interrupted Core update, fix the reported write error and run `python3 scripts/sync-core --recover` before retrying. Durable backups remain until restoration succeeds. Sync and recovery use the same operating-system lock; leave `.method-core-sync.lock` in place during use. diff --git a/docs/opencode.md b/docs/opencode.md index 5b54c9e..4ae57e4 100644 --- a/docs/opencode.md +++ b/docs/opencode.md @@ -1,11 +1,10 @@ # OpenCode integration -Engineering Method exposes its shared skills through OpenCode's native skill -tool. The recorded discovery evidence covers the 17 skills of version 0.1.1; -version 0.2.0 adds twelve writing, PDF and playbook skills that load from the -same directory, and 0.2.1 refines the PDF template. Earlier -[native probes](verification/EM-013-prepublication.md) verify -PDF selection and pre-draft authoring with Humanizer through the skill tool. +The 0.3.0 source candidate bundles 19 engineering/shared skills. Writing Method +bundles its own 18 writing/shared skills and a distinct `writing-method.js` +loader. Both use the same adapter from Method Core. Earlier release evidence +under `docs/verification/` describes the combined historical packages and is not +fresh discovery evidence for this split. A local plugin config hook adds the skill directory and [OpenCode adapter](../shared/platform/opencode.md) to effective configuration. It leaves existing model, permissions, provider and MCP settings untouched. diff --git a/docs/specs/EM-018-method-split/plan.md b/docs/specs/EM-018-method-split/plan.md new file mode 100644 index 0000000..18c0d4a --- /dev/null +++ b/docs/specs/EM-018-method-split/plan.md @@ -0,0 +1,58 @@ +# Implementation Plan: Method split + +## Stable work ID + +EM-018; specification: `docs/specs/EM-018-method-split/spec.md`. + +## Summary and ownership + +Use committed, explicit exports from `phense/method-core`. Each consumer vendors the same relative paths at its package root and pins a Git revision plus file hashes and modes in `method-core.lock.json`. This preserves existing installed-relative skill links, wrapper imports and project data without runtime coupling. + +| Canonical repository | Owned paths/responsibilities | +|---|---| +| method-core | `shared/platform/`; common authority, continuity, proportionality, model-routing and playbook policies; reviewer brief; eight support skills listed below; `templates/playbooks/`; `engineering_method/`; generic state, sync, packaging, validation and OpenCode tools; their characterization/integration tests. | +| engineering-method | Spec Kit, OpenSpec, architecture, debugging and TDD skills; engineering graphs/policies, architecture/engineering templates, historical specs/releases/evidence and engineering host evaluation fixtures. | +| writing-method | Ten documentation/didactic skills; writing depth and reader-output policies, writing filter, documentation/PDF templates, writing graph and writing evaluations/tests. | + +Shared support skills: project-backlog, verification-before-completion, dispatching-parallel-agents, using-git-worktrees, requesting-code-review, receiving-code-review, playbook-authoring, playbook-review. Playbooks become method-neutral; engineering lifecycle hooks move into engineering-owned policy and writing receives its own hooks. Adapters load method-local lifecycle instructions when present, with no hard dependency on writing skills. Core is a source dependency, not an installed plugin. Both plugins expose identical shared support under their own namespaces; choose the invoking method's namespace. + +## Project gates and technical context + +- Python >=3.11, dependency-free state/validation tooling; Node for actual OpenCode-hook tests. +- Original baseline: `d458f6a`, 319 tests passed on 2026-11-13. Preserve existing CLI/data/import contracts. +- Work is isolated on `em-018-method-split`; new sibling repositories start on `main` with no inherited secrets or runtime state. +- Existing EM-018 is coordinator-only. Implementation stays sequential. A separately tracked observed acceptance-review run can supply independent review without changing or delegating from that implementation run. +- Writing scale is medium per standalone README/reference page; no manual, PDF deliverable or new documentation-set lifecycle is required. +- No backend/API/library upgrade, model invocation or provider-account change is needed. + +## Interface contracts and failure behavior + +IC-001: `method-core.json` explicitly lists exports. `scripts/sync-core --source-root PATH --target-root PATH [--revision SHA]` reads immutable Git blobs, refuses dirty exported content, validates safe unique paths/modes, preflights existing ownership and stages a complete update. Before applying managed writes, persist complete original backups. Sync and recovery share one stable OS lock. On failure restore prior bytes/modes/lock; retain backups if restoration fails or the process dies. `scripts/sync-core --recover` restores a dead owner transaction offline and refuses an active owner. Check journal identity before atomic retirement; never delete the persistent `.method-core-sync.lock` during use. `scripts/sync-core --check` validates the installed lock offline. Unknown target files remain untouched. + +IC-002: Existing wrappers and `engineering_method` keep their names and project cwd behavior. State path stays `.engineering-method/`, including in writing projects, as a compatibility contract. + +IC-003: Plugin manifests stay native to Claude/Codex. Packaging uses the committed manifest identity. OpenCode installer derives a validated method identity for distinct loader filenames; user settings remain untouched. Native clean installs use disposable homes, not real authentication/configuration. + +IC-004: Shared playbooks retain Drafted/Reviewed/Rehearsed distinctions. Generic policy never requires absent method skills. Each method owns its lifecycle routing and the decision to require playbooks. + +## Tests and rollback + +1. Characterization-green baseline before changing runtime ownership. +2. Red/green sync tests: offline tamper detection, dirty-source refusal, traversal/symlink/ownership conflicts, transactional failure recovery, executable bits and updates. +3. Existing runtime tests in Core and consumer packages; owned lifecycle/contract tests in each method. +4. Isolated extracted-package checks: no sibling resources; validate every skill link, core lock and wrapper execution; preserve continuity after moving packages. +5. Coexistence tests execute both OpenCode hooks and prove distinct loader ownership. +6. Verify licenses and hashes using retained immutable upstream metadata; update only changed destination hashes. +7. Package archives build twice from immutable commits and match. Source rollback is the original Git revision; consumer rollback syncs an older pinned core revision after verifying no local managed edits. Global installed plugins are unchanged during development. + +## Architecture findings and supporting artifacts + +`docs/uml/em-018-components.md` answers responsibility ownership and runtime independence. `docs/uml/findings.md` records AF-018-001 (shared policy must not depend on absent method), AF-018-002 (transactional sync/ownership), AF-018-003 (coexistence identity). No database model or speculative research artifact is needed. + +## Dependencies and order + +Core sync behavior and common exports precede consumer split. Consumers precede joint integration. Independent review and fixes precede final source publication/handoff. Source manifests and attribution are complete before packaging. Gemini adapter remains a future backlog item. + +## Playbook obligations + +No development operation requires an additional playbook: no live cutover/data migration or multi-actor production change occurs. The transactional sync tool and README update/rollback steps cover this reversible operation. No system playbook beyond the reusable delivered skills/templates is requested. Reassess if installation into live global profiles is added. diff --git a/docs/specs/EM-018-method-split/spec.md b/docs/specs/EM-018-method-split/spec.md new file mode 100644 index 0000000..4979397 --- /dev/null +++ b/docs/specs/EM-018-method-split/spec.md @@ -0,0 +1,74 @@ +# Feature Specification: Shared core, engineering and writing methods + +## Stable work ID + +- Feature ID: `EM-018` +- Status: Accepted for implementation by the user's end-to-end request, 2026-11-13. +- Source request: Separate writing into `phense/writing-method`, share host adapters across both methods, and reassess genuinely shared responsibilities including playbooks. + +## User scenarios + +### US-001: Install a focused method (P1) + +An author installs writing-method without engineering lifecycles. An engineer installs engineering-method without the writing lifecycle. Both get the common support needed to finish their work. Independent test: validate and exercise an extracted package with no sibling repositories present. + +### US-002: Maintain shared behavior once (P1) + +A maintainer updates adapters or shared state in method-core and synchronizes a pinned revision into each method. Independent test: both locks identify the same revision and all shared bytes and executable modes agree. + +### US-003: Use playbooks in either method (P1) + +An engineering migration or a writing publication/export can request a scenario-bound procedure, review and rehearsal evidence without starting a competing lifecycle. Independent test: each method bundles the playbook skills, templates and review support with no dependency on the other method. + +## Acceptance criteria + +- AC-001: Each method has matching Claude/Codex manifests, a local marketplace and a self-contained package whose skill-resource links resolve. +- AC-002: Engineering contains its engineering lifecycles; Writing contains all ten existing writing skills, policies, documentation/PDF templates and Humanizer attribution. No removed method remains an implicit mandatory dependency. +- AC-003: Core is the canonical source of genuinely shared support, including the two playbook skills. Consumer changes to core files are detected offline; synchronization refuses to overwrite local modifications or unowned files. +- AC-004: A synchronization failure leaves the old usable target intact; a subsequent valid synchronization and offline check work. +- AC-005: Existing project-state CLI commands, Python imports, work IDs, `.engineering-method/` data and backlog records remain compatible. +- AC-006: The methods can coexist. Shared skill names have byte-identical contracts; method-qualified invocation chooses an owner. OpenCode loaders do not overwrite each other. +- AC-007: Existing licenses, immutable upstream revisions and source hashes survive the split. Destination hashes reflect the actual delivered bytes. +- AC-008: Verification distinguishes structural/installation evidence from live model routing; no Claude live-evaluation claim is made during its outage. + +## Functional requirements + +- FR-001: Publish source boundaries as three independently versioned repositories under `phense`. +- FR-002: Keep host adapter implementations in the shared source; defer Gemini-specific behavior until separately verified. +- FR-003: Retain all existing authoring/planning/review/PDF behavior in the writing method. +- FR-004: Share backlog, continuity, verification, collaboration/review/isolation and generic playbook support; keep method-specific lifecycle graphs in their method. +- FR-005: Ship immutable, hashed shared copies so installation needs no sibling checkout, submodule or runtime network request. +- FR-006: Provide a safe repeatable sync/check command and independent source/target validation. +- FR-007: Document installation, update, rollback, coexistence and evidence limits for maintainers. + +## Compatibility boundaries + +Preserve `engineering_method` as the runtime Python import and all existing CLI wrapper names; ownership moves without renaming persisted data. Existing installation settings remain active until replacement packages are verified. Keep historical engineering specifications and release evidence as history. New package versions are engineering-method 0.3.0, writing-method 0.1.0 and method-core 0.1.0; no release tag or production installation is implicit in source publication. + +## Interface contracts + +| ID | Boundary | Contract | +|---|---|---| +| IC-001 | Core to consumer | A committed export inventory, immutable revision, relative paths, SHA256 and executable modes; exact copies in existing package-root paths. | +| IC-002 | Consumer to project | Existing `project-state`, `continuity-state`, `backlog-to-issues`, `refresh-issue-cache` and `engineering_method` imports; project cwd stays distinct from plugin root. | +| IC-003 | Host to method | Existing Claude/Codex manifests and OpenCode loader; no live credentials/configuration are copied. | +| IC-004 | Playbook to lifecycle | Authoring returns a draft, review returns a separate verdict, rehearsal remains separate authorized work; the invoking method owns acceptance. | + +## Edge cases + +Reject traversal, symlinked managed paths, malformed locks, missing blobs, duplicate exports, changed permissions and conflicting target ownership before mutation. A package moved to another directory remains usable. A source checkout with dirty export files must not silently supply uncommitted bytes. Shared dependencies must resolve even when only one method is installed. + +## Assumptions and unresolved decisions + +User-approved architecture is a third core repository vendored into both methods. Playbooks move to core following the user's later steering. Public visibility follows the existing public engineering repository. Shared support skills are namespaced by the method plugin when invoked; the core is a source repository, not a third plugin to install. Gemini remains a separately tracked follow-up. No unresolved implementation-blocking scope decision remains. + +## Success measures + +- SC-001: Both isolated packages pass validation and execute state/continuity commands against a fresh target project. +- SC-002: Common runtime characterization tests pass before and after the split; original baseline was 319 passing tests. +- SC-003: Lock tampering and interrupted synchronization tests fail safely, followed by successful recovery. +- SC-004: Independent review resolves all Critical/Important findings before integration handoff. + +## Playbook obligations + +No new system playbook is required: the delivered sync command must handle conflicts and rollback itself. Installation and source rollback instructions suffice for this reversible repository split; it changes no live service or user data. Existing playbook skills/templates are deliverables under FR-004, not a requirement to invent operational procedures. diff --git a/docs/specs/EM-018-method-split/tasks.md b/docs/specs/EM-018-method-split/tasks.md new file mode 100644 index 0000000..008d749 --- /dev/null +++ b/docs/specs/EM-018-method-split/tasks.md @@ -0,0 +1,49 @@ +# Tasks: EM-018 method split + +Specification: `spec.md`; plan: `plan.md`; architecture: `../../uml/em-018-components.md`, `../../uml/findings.md`. + +## Architecture findings + +AF-018-001 requires method-neutral exports; AF-018-002 transactional sync; AF-018-003 independent installation identities. Coordinator owns all implementation paths sequentially. + +## Tests + +Preserve the baseline green runtime contracts. Verify a failing sync behavior test before implementing new behavior. Exercise actual CLI, filesystem state, extracted packages and OpenCode hooks; source wording checks supplement behavior evidence. + +## Implementation slices + +### Slice S1: Shared core and safe export + +- [x] T001 [US-002] [FR-004] Inventory and copy genuine shared support into `../method-core/`, preserving imports, state paths and upstream metadata. Baseline: 319 tests passed. +- [x] T002 [US-002] [IC-001] [AF-018-002] Implement `method-core/scripts/method_core.py` and sync CLI after red tests for drift, ownership, malformed paths, modes and rollback. Depends on T001. +- [x] T003 [US-003] [IC-004] [AF-018-001] Generalize shared playbooks and host adapters; keep per-method lifecycle routing out of core. Files: core shared policies/skills/platform and templates. Depends on T001. + +### Slice S2: Focused method packages + +- [x] T004 [US-001] [IC-003] [AF-018-003] Split writing resources and tests into `../writing-method/`, adapt engineering resources/tests, manifests, provenance and generic packaging/OpenCode tools. Depends on T002,T003. +- [x] T005 [US-001] [US-002] Document native installation, sync, rollback, namespaces and verification limits in both READMEs; preserve historical release documents. Depends on T004. + +### Slice S3: Integration and review + +- [x] T006 Reconcile as-built architecture and derive success/recovery integration checks from actual package boundaries. Depends on T004. +- [x] T007 Run full relevant suites, extracted-package integration and coexistence checks; resolve findings with focused regression tests. Depends on T006. +- [x] T008 Obtain independently tracked acceptance review of the bounded three-repository diff, fix actionable findings and rerun affected checks. Depends on T007. + +### Slice S4: Convergence and handoff + +- [x] T009 Run speckit-converge, retain exact evidence and only then complete EM-018. Depends on T005,T008. +- [x] T010 Publish new source repositories and the engineering change branch for review; preserve existing installed profiles and original default branch until explicit integration. Depends on T009. + +## Dependencies + +T001 precedes T002/T003; these precede T004; T004 precedes T005/T006; T006 precedes T007; T007 precedes T008; T005/T008 precede T009; T009 precedes T010. No parallel writers. + +## Playbook obligations + +Spec/plan assessed none for new operational procedures. Delivered generic playbook support is covered by T003/T004 and its independent content review and behavior-boundary checks. + +## Convergence 1: GitHub runner dependency + +### Slice S5: Reproducible GitHub verification + +- [x] T011 [AC-008] Install the test's explicit `ripgrep` dependency in the Engineering GitHub workflow and require a fresh full GitHub run. The observed failure was `FileNotFoundError: rg` in `test_prompt_discovery_command_follows_actual_skill_links`; local source suites remained green. Own `.github/workflows/verify.yml` and verification evidence. Depends on T010. Mechanical CI-only correction; coordinator review suffices. diff --git a/docs/uml/em-018-components.md b/docs/uml/em-018-components.md new file mode 100644 index 0000000..a0307a8 --- /dev/null +++ b/docs/uml/em-018-components.md @@ -0,0 +1,17 @@ +# EM-018 ownership and installation + +Purpose: Which repository owns common behavior, and can each method execute without a sibling checkout? Requirements: FR-002 through FR-006; IC-001 through IC-004. Sources: EM-018 plan, existing skill links, `engineering_method/cli.py`, `scripts/package_plugin.py`. Notation: Mermaid flowchart component view. Verification date: 2026-11-13. Mode: as-built; reconciled against Core `255026b`, Engineering candidate `206fbe5` and Writing `e9eab64`. + +```mermaid +flowchart LR + Core[method-core committed exports] -->|pinned blobs and SHA256 lock| Eng[engineering-method package] + Core -->|same revision and bytes| Write[writing-method package] + Eng -->|bundled adapters and skills| EH[Claude Codex OpenCode] + Write -->|bundled adapters and skills| WH[Claude Codex OpenCode] + EH --> EP[Target project state] + WH --> WP[Target project state] +``` + +Core has no dependency on either consumer. Consumers have no runtime dependency on one another or a network service. A sync operation validates the entire proposed write set before applying changes; ordinary write failures restore the old managed files and lock; durable backups allow explicit `--recover` after abrupt termination or blocked restoration. Sync and recovery serialize through the same persistent OS lock. Runtime state belongs to target projects, never to the plugin installation. Gemini is absent until separately verified. Mermaid source is semantically inspected; no render is claimed. + +The complete archive success/recovery flow, native coexistence and source integrity evidence are recorded in [EM-018 verification](../verification/EM-018-method-split.md). The flow uses a synthetic Git source built from the real Core archive and preserves the target project checkpoint across an interrupted update and retry. diff --git a/docs/uml/findings.md b/docs/uml/findings.md new file mode 100644 index 0000000..7a2a95e --- /dev/null +++ b/docs/uml/findings.md @@ -0,0 +1,7 @@ +# EM-018 architecture findings + +- AF-018-001 — Resolved. Core adapters and generic playbooks no longer require an absent writing or engineering lifecycle. Engineering retains its phase hooks; Writing's review/debugging companions are optional. Both independent package validators and resource/contract tests pass. Tasks T003/T004. +- AF-018-002 — Resolved. Committed export inventory, revision/hash/mode locks, ownership and drift checks protect managed files. Durable backups, explicit recovery, retained failed-restore data, stable OS serialization and journal identity checks cover interruption and concurrent recovery. Thirteen sync regressions and the complete archive/target-state recovery flow pass. Task T002. +- AF-018-003 — Resolved. Plugin manifests and archive/OpenCode identities derive from the consumer. Both native methods coexist in disposable Claude/Codex homes; real OpenCode hook tests preserve user configuration and separate loaders. Task T004. + +Reconciled 2026-11-13 against Core `255026b`, Engineering candidate `206fbe5` and Writing `e9eab64`. No ownership cycle or sibling runtime dependency remains. Exact evidence and limits: [EM-018 verification](../verification/EM-018-method-split.md). diff --git a/docs/usage.md b/docs/usage.md index 539a5de..f9a9362 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -74,48 +74,6 @@ A direct request to author a scenario-bound onboarding or recovery playbook uses `playbook-authoring`; a general tutorial or manual keeps its documentation route. A typo fix or simple reversible refactor does not require a playbook. -## Write one document - -> Write a how-to guide that shows an administrator how to rotate an API key. -> One reader group; no other documentation exists yet. - -The writing-depth policy places this at the medium scale. `documentation-authoring` -runs in standalone mode: it defines the reader and version, uses the task -skeleton from the chunk template, and applies `writing-procedures` (goal, -prerequisites, blocks of three to five imperative steps, a check that it -worked). The draft is written under `human-prose-drafting` from the first -sentence, so no humanizing pass follows. A recorded self-review and fresh link -check close the work. No plan directory is created. - -## Build a documentation set - -> Create the complete user manual: about twelve chapters for administrators, -> end users and support staff, with shared terminology and screenshots. - -Several readers, shared terms and images and many sessions place this at the -large scale. `documentation-planning` records the scale decision and writes -`docs/writing//plan.md` with readers, information architecture and a -chunk manifest, plus `glossary.md` and `assets.md`. `documentation-authoring` -then writes one Markdown file per chunk with frontmatter, using -`explaining-concepts`, `writing-procedures` and `empathic-troubleshooting` -per content type, `human-prose-drafting` for sentence-level constraints while -writing, `terminology-guard` for terms and `visual-placeholders` for image -callouts. `documentation-review` checks the set at a named revision -and returns findings to authoring; acceptance needs zero open Critical or -Important findings and fresh verification. - -## Explain, instruct or troubleshoot in a reply - -> Why does the retry queue drop messages after a restart, and what should I -> check first? - -Outside documentation projects, the reader-oriented output policy applies the -same skills to ordinary replies: the explanation opens with an everyday -analogy and avoids undefined jargon, the next steps are numbered imperative -actions with exact locations and a visible result, and help with a failure -starts from the symptom the user sees. Evidence and verification rules do not -change. - ## Resume work > Resume work item APP-014 from its repository checkpoint. Reconcile Git, @@ -139,16 +97,5 @@ native dependency edges. After migration, Issues become canonical and the local backlog is a marked cache; offline changes queue for reconciliation. Publishing a repository alone does not authorize migrating its tasks. -## Export reviewed Markdown to PDF - -> Build one PDF from these accepted chapters, in plan order, with the manual -> design, table of contents and page numbers. -`documentation-pdf` uses Quarto and its bundled Typst engine after content -review. Copy the [manual template](../templates/documentation/pdf/DESIGN.md) -to a new documentation root, map the accepted manifest rows to `book.chapters` -in `_quarto.yml`, and set title, language, output name and `_brand.yml`. -From that directory, run `quarto render --to em-manual-typst`. The default -result is `_book/manual.pdf`. Inspect the actual contents links, page totals -and page layout before delivery. This export preserves Markdown sources and -does not publish remotely or re-run Humanizer over the finished text. +Writing and PDF examples are in the [Writing Method usage guide](https://github.com/phense/writing-method/blob/main/docs/usage.md). diff --git a/docs/verification/EM-018-method-split.md b/docs/verification/EM-018-method-split.md new file mode 100644 index 0000000..c614add --- /dev/null +++ b/docs/verification/EM-018-method-split.md @@ -0,0 +1,76 @@ +--- +type: reference +audience: Method maintainers reviewing the repository split +version: 1 +--- +# EM-018 split verification + +On 2026-11-13 the split passed local package, state, recovery and native installation checks. Engineering remains a 0.3.0 source candidate for pull-request integration; this is not a tagged release or a replacement of existing global profiles. + +## Verified boundaries + +[Method Core](https://github.com/phense/method-core) owns 69 shared exports, including eight support skills and both playbook skills. [Engineering Method](https://github.com/phense/engineering-method) bundles 19 skills and [Writing Method](https://github.com/phense/writing-method) bundles 18. Both locks pin `255026bf88469e904514e093d06153f643ba0adb`. All repositories are public under `phense`, have their own Issues and pull requests, share `agent-methods`, and link to one another from their READMEs. + +The original baseline was `d458f6aebb3887a6efca67d7fa958d2bfff6e14e` with 319 passing tests. The candidate package sources tested here are Engineering `206fbe54cee14123519b2b52553c65d77d3f2fa5`, Writing `e9eab64219fcaa03d375fc6dc9e4027c252fb45e`, and the Core revision above. Later engineering changes record evidence, backlog state and corrected integration-fixture invocation; they do not change delivered runtime or shared files. + +## Full suites + +Run `python3 scripts/validate-plugin` and `python3 -m unittest discover -s tests -t . -v` from each repository root. All three commands completed successfully. Counts overlap because each independent consumer tests its bundled common runtime. + +| Repository | Tests | Elapsed | Captured unittest output SHA256 | +|---|---:|---:|---| +| Core | 159 | 50.513 s | `11dbc0b29d04b6bae6966b2d9c5533bf73944ff02e34613256b37f468569236d` | +| Engineering | 335 | 76.228 s | `054bf32e0009b225c4888f1ac9d65a33f246f0260d5a3b61494f70c0dbdc17ad` | +| Writing | 163 | 43.009 s | `9ef5eda8506aef6fa2e0304dab86c6c9973d4cc4a9072fb79c4f38717bf8e6c0` | + +## Package and state integration + +`python3 scripts/package-plugin --check --output PATH` built each archive twice from its immutable commit and produced matching bytes. Archive SHA256 values: + +| Archive | SHA256 | +|---|---| +| Core | `c9e6e1c1f36439c9f91f810d544af0eae1f90bd0ef016d3a3e09ebc2590b5c99` | +| Engineering | `4af643a86bbc7610e1848b3e7ecd7e63e24bf391705c63848b676573be7c7b59` | +| Writing | `0b0d9c58d3e1e465420710b21b0bc5ff2b4897e7a202f8b2feffeac352e9d5c2` | + +Run the complete success/recovery flow with: + +```sh +python3 tests/e2e/test-method-split --core /path/to/method-core.zip --engineering /path/to/engineering-method.zip --writing /path/to/writing-method.zip --output .engineering-method/verification/split.json +``` + +It extracts each immutable archive into a separate directory, creates a local Git fixture from Core's exported source, and synchronizes both methods. Each method's actual installed wrappers initialize and start `TEST-001` in a separate project, create a continuity checkpoint and recover it. Project files stay in the target; no project state appears in either plugin. + +The fixture changes two actual exported adapters, terminates each updater with exit 23 immediately after a real replacement, and requires the offline check to fail. `--recover` then restores the prior plugin snapshot, including bytes and file modes. A valid retry installs the new Core into both consumers. Both resulting locks agree across all 69 exports, and the original project files, continuity checkpoint, modes and work ID remain unchanged. The fixture revisions are local test commits, not replacement upstream pins. + +## Independent review and fixes + +Two read-only reviewers inspected the bounded split and the materially changed recovery interface. Their original verdicts contained actionable findings; the coordinator verified and resolved them rather than treating a conditional verdict as an unconditional acceptance. + +| Finding | Resolution and current evidence | +|---|---| +| A permanently unwritable unchanged destination prevented earlier rollback | Skip unchanged snapshots, attempt every restoration, retain durable backups on failure; real POSIX permission regression passes. | +| Interrupts and process death left an unrecoverable mixed version | Catch ordinary interrupts, persist complete backups before writes, add offline `--recover`; interrupt, abrupt-exit and blocked-recovery retry tests pass. | +| Two recoveries could overwrite a newer update and remove its journal | Sync and recovery share a persistent, exclusive OS file lock; verify journal identity before atomic retirement. A real paused recovery process excludes a second recovery and an update, then permits a valid retry. | +| Writing required absent Engineering debugging/TDD skills | Shared review now treats them as optional engineering companions and checks prose against its own sources/requirements. Both consumers contain the same corrected file. | +| Shared install snippets chose Engineering's identity | Examples use the consuming manifest's identity; actual native installs exercise both identities. | + +The 13 sync regression tests and the final full suites include these fixes. There are no unresolved Critical or Important review findings. Windows-specific locking behavior and live host model behavior were not independently exercised on this Linux host. + +## Native installation and coexistence + +`python3 scripts/clean_install.py --package PATH --output PATH` passed independently for both consumer archives with Codex CLI 0.169.0 and Claude Code 2.1.323. Each run created empty disposable configuration homes, validated and registered the local marketplace, installed the method and verified its enabled native inventory. A further disposable-home check installed both together and verified both identities in each host's inventory. No credentials were copied or used, and no model requests were sent. Existing global profiles were not modified. + +Real Node-based OpenCode loader tests in the full suites prove separate loader ownership and configuration preservation. They do not constitute a new live OpenCode routing evaluation. + +## Provenance and limits + +All 39 original adapted-source records retain their upstream project IDs, immutable revisions, source paths and hashes across their new owners. Validators check actual destination hashes and license notices. All twelve PDF-template files match the original engineering baseline byte for byte. + +No fresh PDF render or live-model authoring/routing run is claimed. The moved PDF checker and historical render evidence remain available in Writing; this host lacks `mutool`. Gemini adapter verification is deferred as `EM-019`. No release tag, default-branch merge or production/global installation is implicit in this evidence. + +## Acceptance mapping + +AC-001/002: native manifests, exact skill inventories, resolved resources and isolated archive execution. AC-003/004: immutable locks, ownership/drift checks and complete failure/recovery regressions. AC-005: unchanged runtime imports, CLI names and target state demonstrated end to end. AC-006: byte-identical common exports, native dual installation and OpenCode coexistence. AC-007: retained upstream records/licenses and twelve unchanged template files. AC-008: explicit separation of installation/structural evidence from unperformed live evaluations. + +As-built findings AF-018-001 through AF-018-003 are resolved. Local convergence found no remaining implementation task. Core and Writing source publication is complete. The Engineering integration candidate is published as [pull request 135](https://github.com/phense/engineering-method/pull/135); the existing default branch and global installations remain separate from this source handoff. The initial ten source-handoff tasks are complete. GitHub exposed an undeclared test dependency: its Engineering runner lacked `rg`, causing one of 335 tests to error while local suites passed. Convergence task T011 installs `ripgrep` explicitly in CI. Both fresh GitHub checks passed on `bf0571f0866a7cace3133925e0f9f7af7d75728a`; the [full verification run](https://github.com/phense/engineering-method/actions/runs/43411582010) passed all 335 tests. T011 is complete. The user authorized integration of PR135 after these checks. diff --git a/evals/claude/expected.json b/evals/claude/expected.json index 17a9c3c..e4f2804 100644 --- a/evals/claude/expected.json +++ b/evals/claude/expected.json @@ -230,94 +230,5 @@ "artifacts": [ "decision.md" ] - }, - "standalone-document": { - "primary": "documentation-authoring", - "supporting": [ - "project-backlog" - ], - "prohibited": [ - "documentation-planning", - "documentation-review", - "speckit-specify", - "speckit-plan", - "speckit-tasks", - "orchestrated-implementation", - "speckit-converge", - "openspec-propose", - "openspec-apply", - "openspec-archive", - "systematic-debugging" - ], - "artifacts": [ - "decision.md" - ] - }, - "documentation-set": { - "primary": "documentation-planning", - "supporting": [ - "project-backlog" - ], - "prohibited": [ - "documentation-authoring", - "documentation-review", - "speckit-specify", - "speckit-plan", - "speckit-tasks", - "orchestrated-implementation", - "speckit-converge", - "openspec-propose", - "openspec-apply", - "openspec-archive", - "systematic-debugging" - ], - "artifacts": [ - "decision.md" - ] - }, - "documentation-pdf": { - "primary": "documentation-pdf", - "supporting": [], - "prohibited": [ - "speckit-specify", - "openspec-propose", - "documentation-planning", - "systematic-debugging" - ], - "artifacts": [ - "decision.md" - ] - }, - "documentation-draft-preparation": { - "primary": "documentation-authoring", - "supporting": [ - "project-backlog", - "human-prose-drafting" - ], - "prohibited": [ - "speckit-specify", - "openspec-propose", - "documentation-planning", - "systematic-debugging" - ], - "artifacts": [ - "decision.md" - ] - }, - "existing-documentation-plan": { - "primary": "documentation-authoring", - "supporting": [ - "project-backlog", - "human-prose-drafting" - ], - "prohibited": [ - "speckit-specify", - "openspec-propose", - "documentation-planning", - "systematic-debugging" - ], - "artifacts": [ - "decision.md" - ] } } diff --git a/evals/codex/expected.json b/evals/codex/expected.json index 17a9c3c..e4f2804 100644 --- a/evals/codex/expected.json +++ b/evals/codex/expected.json @@ -230,94 +230,5 @@ "artifacts": [ "decision.md" ] - }, - "standalone-document": { - "primary": "documentation-authoring", - "supporting": [ - "project-backlog" - ], - "prohibited": [ - "documentation-planning", - "documentation-review", - "speckit-specify", - "speckit-plan", - "speckit-tasks", - "orchestrated-implementation", - "speckit-converge", - "openspec-propose", - "openspec-apply", - "openspec-archive", - "systematic-debugging" - ], - "artifacts": [ - "decision.md" - ] - }, - "documentation-set": { - "primary": "documentation-planning", - "supporting": [ - "project-backlog" - ], - "prohibited": [ - "documentation-authoring", - "documentation-review", - "speckit-specify", - "speckit-plan", - "speckit-tasks", - "orchestrated-implementation", - "speckit-converge", - "openspec-propose", - "openspec-apply", - "openspec-archive", - "systematic-debugging" - ], - "artifacts": [ - "decision.md" - ] - }, - "documentation-pdf": { - "primary": "documentation-pdf", - "supporting": [], - "prohibited": [ - "speckit-specify", - "openspec-propose", - "documentation-planning", - "systematic-debugging" - ], - "artifacts": [ - "decision.md" - ] - }, - "documentation-draft-preparation": { - "primary": "documentation-authoring", - "supporting": [ - "project-backlog", - "human-prose-drafting" - ], - "prohibited": [ - "speckit-specify", - "openspec-propose", - "documentation-planning", - "systematic-debugging" - ], - "artifacts": [ - "decision.md" - ] - }, - "existing-documentation-plan": { - "primary": "documentation-authoring", - "supporting": [ - "project-backlog", - "human-prose-drafting" - ], - "prohibited": [ - "speckit-specify", - "openspec-propose", - "documentation-planning", - "systematic-debugging" - ], - "artifacts": [ - "decision.md" - ] } } diff --git a/evals/shared/triggers/documentation-draft-preparation.json b/evals/shared/triggers/documentation-draft-preparation.json deleted file mode 100644 index 8713aff..0000000 --- a/evals/shared/triggers/documentation-draft-preparation.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "id": "documentation-draft-preparation", - "prompt": "Prepare to draft a medium-length administrator how-to guide for rotating API keys. The reader, task scope and facts are established in README.md. Load the writing instructions and all sentence-level guidance that must apply before the first sentence. Record decision.md but do not draft prose yet.", - "files": { - "README.md": "# Keyforge 1.0\n\nReader: administrator. One standalone task guide. Settings > API keys: Generate creates a new key; Revoke disables an existing key. Install the new key in the client and verify it before revoking the old one. No other product behavior is established.\n" - } -} diff --git a/evals/shared/triggers/documentation-pdf.json b/evals/shared/triggers/documentation-pdf.json deleted file mode 100644 index b1d81e0..0000000 --- a/evals/shared/triggers/documentation-pdf.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "id": "documentation-pdf", - "prompt": "Combine the two reviewed Markdown chapters into one local PDF with a reusable design, clickable table of contents and page numbers. The prose is accepted. Assess the export workflow and load its instructions; do not render yet.", - "files": { - "README.md": "# Reviewed manual\n\nBoth chapters are accepted for export in this order: docs/setup.md, docs/usage.md.\n", - "docs/setup.md": "# Setup\n\nCreate a workspace.\n", - "docs/usage.md": "# Usage\n\nOpen your workspace.\n" - } -} diff --git a/evals/shared/triggers/documentation-set.json b/evals/shared/triggers/documentation-set.json deleted file mode 100644 index dbf7179..0000000 --- a/evals/shared/triggers/documentation-set.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "id": "documentation-set", - "prompt": "Create the complete user manual for this product: about twelve chapters for administrators, end users and support staff, with shared terminology and screenshots, to be written over several sessions. Perform only the first safe assessment: select the workflow, load the applicable skills, and record decision.md; do not write the plan or chapters.", - "files": { - "README.md": "# Keyforge\n\nKeyforge manages API keys, teams and audit logs. It has an admin console, an end-user portal and a support view.\n" - } -} diff --git a/evals/shared/triggers/existing-documentation-plan.json b/evals/shared/triggers/existing-documentation-plan.json deleted file mode 100644 index 8d1a287..0000000 --- a/evals/shared/triggers/existing-documentation-plan.json +++ /dev/null @@ -1,10 +0,0 @@ -{ - "id": "existing-documentation-plan", - "prompt": "Continue the accepted large documentation plan in docs/writing/keyforge/plan.md. Prepare to write the first chunk: inspect dependencies and load all writing guidance that must apply before its first sentence. Do not draft prose or change canonical state yet; record the assessment in ./decision.md at the repository root (outside docs/writing/keyforge).", - "files": { - "README.md": "# Keyforge 1.0\n\nAdministrators generate and revoke API keys in Settings > API keys. End users supply a valid key when connecting. Revoked keys stop working.\n", - "docs/writing/keyforge/plan.md": "# Documentation Plan: Keyforge\n\n## Stable work ID\nDocumentation ID: keyforge\nStatus: Planned and accepted\nContent root: docs/manual\n\n## Scale decision\nLarge: twelve chapters for administrators, end users and support staff across sessions. This fixture starts the first concept chunk.\n\n## Readers\nR1: administrators new to Keyforge 1.0; understand API keys before managing them.\n\n## Chunk manifest\n| Chunk ID | File | Type | Title | Readers | Depends on | Assets | Status |\n|---|---|---|---|---|---|---|---|\n| C-001 | docs/manual/api-keys.md | concept | API keys | R1 | none | none | planned |\n\n## Conventions\nUse chunk frontmatter and the authoritative glossary.\n", - "docs/writing/keyforge/glossary.md": "# Glossary\n\nAPI key: credential a client supplies to connect to Keyforge.\n", - "docs/writing/keyforge/assets.md": "# Assets\n\nNo assets required for C-001.\n" - } -} diff --git a/evals/shared/triggers/standalone-document.json b/evals/shared/triggers/standalone-document.json deleted file mode 100644 index a618c0d..0000000 --- a/evals/shared/triggers/standalone-document.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "id": "standalone-document", - "prompt": "Write a how-to guide, docs/how-to/rotate-api-keys.md, that shows an administrator how to rotate an API key in this product. There is one reader group and no other documentation exists yet. Perform only the first safe assessment: select the workflow, load the applicable skills, and record decision.md; do not draft the guide.", - "files": { - "README.md": "# Keyforge\n\nAdministrators manage API keys under Settings > API keys. Keys can be generated, revoked and rotated.\n" - } -} diff --git a/method-core.lock.json b/method-core.lock.json new file mode 100644 index 0000000..2f303de --- /dev/null +++ b/method-core.lock.json @@ -0,0 +1,353 @@ +{ + "files": [ + { + "mode": "100644", + "path": "CORE_NOTICES.md", + "sha256": "e17ace703e9eb536c57924f57d5e5835fc7c49e0e5e2921f8bf1b39f2efdc160" + }, + { + "mode": "100644", + "path": "engineering_method/__init__.py", + "sha256": "95e81258c8166d4b5f5737751c837b088c094d5cdf863460f85ee9d68dc30461" + }, + { + "mode": "100644", + "path": "engineering_method/backlog.py", + "sha256": "dce2fb225cd47b869eee8d60270ff4cec523023c90dcd40bf766fe3d1c97383a" + }, + { + "mode": "100644", + "path": "engineering_method/cli.py", + "sha256": "43859d9e246b0422ae84425068656f666cf5d561c31f7073d0c63a6cc7981e22" + }, + { + "mode": "100644", + "path": "engineering_method/continuity.py", + "sha256": "fd213e12c091e7378a265d80226498e8e4736d77ea5ffb6a7de54a614d8760b9" + }, + { + "mode": "100644", + "path": "engineering_method/features.py", + "sha256": "baa9988f434df001b9d1dc9ad9652be3c41b09d706ac5084c5a04934ba581633" + }, + { + "mode": "100644", + "path": "engineering_method/files.py", + "sha256": "09423a9dd2b82873a81e92f76b51e2589feab6e8a33f82367e819fbb4c14ea0e" + }, + { + "mode": "100644", + "path": "engineering_method/gh.py", + "sha256": "62836e8e91fbbb1ace4439df81efa5c4400deef76970203ed707b49bfedf9801" + }, + { + "mode": "100644", + "path": "engineering_method/issues.py", + "sha256": "a27a9e8422741221d3c5dfef0165159765465481ff3040b348853fab43ecfc01" + }, + { + "mode": "100644", + "path": "engineering_method/models.py", + "sha256": "a9d23cff34ae722042b4906a68599269b6a3245d83cf051c883b8074a5ade7d5" + }, + { + "mode": "100644", + "path": "integrations/opencode/plugin.mjs", + "sha256": "6b667b3503eb0f5cd9a1a0a0d503b268988b1c1ddd2ced3923cb282fd255b630" + }, + { + "mode": "100644", + "path": "scripts/__init__.py", + "sha256": "317ff891f7e513544f009641fb1ad4e6da871737a124e683256c21d6dbb86d2a" + }, + { + "mode": "100755", + "path": "scripts/backlog-to-issues", + "sha256": "cf6c09a9ee0ab7263f3b0ff95786cba427316da48cc22ab25b95e910bd4b73cb" + }, + { + "mode": "100644", + "path": "scripts/clean_install.py", + "sha256": "6a6ce13578e679325529b02f56d9196f1fc15bb924d8cdfebd43a8877fc39f9c" + }, + { + "mode": "100755", + "path": "scripts/continuity-state", + "sha256": "ebade22663b4b35729e37c37d35a5c0d969c9708e46b470f53e0500f9446c147" + }, + { + "mode": "100755", + "path": "scripts/install-opencode", + "sha256": "76c8019e94c5806b057109032ae467c8689fec5346c9ff1a7b3fe625cc4ce1f3" + }, + { + "mode": "100644", + "path": "scripts/method_core.py", + "sha256": "72ed9894391ee836611d1dde1c89db8c00ac7c7b68fae648253be84add3a552f" + }, + { + "mode": "100644", + "path": "scripts/package-plugin", + "sha256": "fd12700dcd6864cf0dc0504b8634a193ad58340679073e986840f0550ab3c099" + }, + { + "mode": "100644", + "path": "scripts/package_plugin.py", + "sha256": "1a60cb66c6970a25a2211a2837f0920ba28039c6fa18374093675df07f573a70" + }, + { + "mode": "100644", + "path": "scripts/process_control.py", + "sha256": "971915bd55859f5869e0bae0209c14e8d21d099a93fb4f6e7ccaee8cf0a9e942" + }, + { + "mode": "100755", + "path": "scripts/project-state", + "sha256": "e8ceecc274644219def7fd991965a05f0f6717c8e112394cfbabef92a3080a3f" + }, + { + "mode": "100755", + "path": "scripts/refresh-issue-cache", + "sha256": "925971994a8a66434dcda44821abcea0313e51f41b5b1a9f30829d3efb07de20" + }, + { + "mode": "100644", + "path": "scripts/run_host_evals.py", + "sha256": "b9e06b1ae7b562521d57b04b1d530e14b98ac1f3f6484c8e4ca21fe40a0cb161" + }, + { + "mode": "100755", + "path": "scripts/sync-core", + "sha256": "1b3dae22d97497a958a93c35f671a33dc8be458cf112f9baf36f7b7948ecac46" + }, + { + "mode": "100755", + "path": "scripts/validate-plugin", + "sha256": "3ecb51e522111ef1a402d052e6aa65cb8aafd4b367305608c79a71e141ac5e34" + }, + { + "mode": "100644", + "path": "scripts/validate_plugin.py", + "sha256": "2f3ad25cec0dca4127daa2fcc64f08e15d47a2084b3d5936c8b26ed6bc3ccc9c" + }, + { + "mode": "100644", + "path": "shared/agent-roles/reviewer.md", + "sha256": "8ed94cc55adc7ebbcad64c88496a9ef945e63e01cd920a390a5400c1ad6f4825" + }, + { + "mode": "100644", + "path": "shared/platform/claude.md", + "sha256": "6534484a16e086ee7328ecfec82a747363cd857661319ce9bc65d2932633925a" + }, + { + "mode": "100644", + "path": "shared/platform/codex.md", + "sha256": "b9b2f32eff905f183cfb1f685ddf126363e52847e46bdb160f0f24ead9008e2a" + }, + { + "mode": "100644", + "path": "shared/platform/opencode.md", + "sha256": "3da881555315a55da168aef5c6c26b69f8b2abc35e76e7969c85a054eb377e29" + }, + { + "mode": "100644", + "path": "shared/policies/authority-order.md", + "sha256": "99c45ae09f45eebf2ed0119bc0040f19437258e7949202a924a4077e768c357d" + }, + { + "mode": "100644", + "path": "shared/policies/continuity-contract.md", + "sha256": "81c8162402096840f5ed5ac34a4fed4c21a155ba4a2a526e91ba507a726c1641" + }, + { + "mode": "100644", + "path": "shared/policies/model-routing.md", + "sha256": "6e6bbeb368ab4ba834164d0150b62cd4704cfead6defa56a29a8482010d60e6d" + }, + { + "mode": "100644", + "path": "shared/policies/playbooks.md", + "sha256": "a08a4344863f8dcd682c822b0164a6102042ce3e844b72bd417ff03e0ae0390d" + }, + { + "mode": "100644", + "path": "shared/policies/proportionality.md", + "sha256": "4bb817f1853e058241e1ed860a925342ce73f8ffd10d9e82fc79395ebccc54c7" + }, + { + "mode": "100644", + "path": "skills/dispatching-parallel-agents/SKILL.md", + "sha256": "340659cce89cc6d8dad13f754f1ebe2523460d75fde4e7c998020ea2ebba37d4" + }, + { + "mode": "100644", + "path": "skills/playbook-authoring/SKILL.md", + "sha256": "9ac4be7b74cd19978c4d82eee0f092666ea6792fd18a88be36f370c972d639e8" + }, + { + "mode": "100644", + "path": "skills/playbook-review/SKILL.md", + "sha256": "a784e7986fce41b19a4220e7c98356fd9c23b71504fb4ada9ccbce519290ecd9" + }, + { + "mode": "100644", + "path": "skills/project-backlog/SKILL.md", + "sha256": "6f48f0601757cba76b4c4f3599d45f2b949d63e04e7427efe2c725cad360b0f3" + }, + { + "mode": "100644", + "path": "skills/receiving-code-review/SKILL.md", + "sha256": "0470026a2fb8d9a0faf3c7dfb43ecad2fdcbc1bd20ba888e4c01cd7c762cb957" + }, + { + "mode": "100644", + "path": "skills/requesting-code-review/SKILL.md", + "sha256": "197f746dcb6d5bf10e9e65c532c9b39a042e9daa7184fc27f2fafab848901c25" + }, + { + "mode": "100644", + "path": "skills/requesting-code-review/code-reviewer.md", + "sha256": "1ccb035bef48a862682a7e34557447b04d3b86992c78519b10b2a4bd77f625f2" + }, + { + "mode": "100644", + "path": "skills/using-git-worktrees/SKILL.md", + "sha256": "c913860e385c45657b006097128523cfebafdf7a29c710e4755710d7c606494a" + }, + { + "mode": "100644", + "path": "skills/verification-before-completion/SKILL.md", + "sha256": "faaf2467dbfc9d10d280d1891762ba8e3da6e2220c77f870fdc1ef0347901fa7" + }, + { + "mode": "100644", + "path": "templates/orchestration/agent-report.md", + "sha256": "5f69bede77238ecfdacda598c86842478f0a51e4c2b444f292df0da08d088e73" + }, + { + "mode": "100644", + "path": "templates/orchestration/resume.md", + "sha256": "38c5b475852386d303c3c73108bec28b034ddeac781499bd197c383b5e170094" + }, + { + "mode": "100644", + "path": "templates/orchestration/review-report.md", + "sha256": "f2dc75b25feaec24e865f79db2e510f3ce98948bfdce506655fb1eec2cfb941d" + }, + { + "mode": "100644", + "path": "templates/playbooks/playbook.md", + "sha256": "61c414cd9a6bc95fce20945c706e2db7cb2af0b9bd8afae139963cfb3df59ebb" + }, + { + "mode": "100644", + "path": "templates/playbooks/review.md", + "sha256": "55eac867e0d8014de46075b113f3b51ead2debadff02cf820bf93b54f7c541c9" + }, + { + "mode": "100644", + "path": "tests/__init__.py", + "sha256": "6fd3fc6fdf7a3575d8a6dbd4b8cf68baca19eba0dde2b92bef324f7757339766" + }, + { + "mode": "100644", + "path": "tests/fakes.py", + "sha256": "b7c5b0188fc5f9112e3f26cfcd163adf6342083fdbceedfb091e507e43904092" + }, + { + "mode": "100644", + "path": "tests/fixtures/legacy-project/BACKLOG.md", + "sha256": "876666bde74605c5037daae295caddaff22a31e25d410d47f30b24c6321ad77f" + }, + { + "mode": "100644", + "path": "tests/fixtures/legacy-project/FEATURES.md", + "sha256": "3320ed5408998410fa0959c548f46db4879d6b71da52fdbc4ff1fbe9d0328dea" + }, + { + "mode": "100644", + "path": "tests/test_backlog.py", + "sha256": "010927d338a76c0c6902b013bd9729dd7c7cd446e9d909f996c751624611253f" + }, + { + "mode": "100644", + "path": "tests/test_clean_install.py", + "sha256": "6337cdc751f5659b1d35bdc4265fda1404ed4ab200867977845eca33734cb848" + }, + { + "mode": "100644", + "path": "tests/test_cli.py", + "sha256": "ecb49dbe08e7ab6f709190a17ba2e03cc388d42b77463eead893d0b836132c8b" + }, + { + "mode": "100644", + "path": "tests/test_continuity.py", + "sha256": "003d1de80a9d0d8217cc7954e31bb629e90edb07ce806778968ddf9f883fb589" + }, + { + "mode": "100644", + "path": "tests/test_core_sync.py", + "sha256": "7ba34142488b9fb812e34196f6a272fdabaab0b72077f9bcdc8abcd6c7a9a6d4" + }, + { + "mode": "100644", + "path": "tests/test_features.py", + "sha256": "6e18f6dc43cb5333e3815cb0f3096e886bae22f2063f6610a3f8cc164086db91" + }, + { + "mode": "100644", + "path": "tests/test_host_namespace.py", + "sha256": "529234cfe6ecc430fceed45863cf12c9d03e22a4af0229cc0a4a145dc3377165" + }, + { + "mode": "100644", + "path": "tests/test_issues.py", + "sha256": "b359622e7cb07f10955104bbaabd81239fe8417744e68441e8a181fb974d9f74" + }, + { + "mode": "100644", + "path": "tests/test_issues_regressions.py", + "sha256": "c52456a5dee788f58b0fd8601635ad0ff622676157457818ddcf8bcf8b6fa05b" + }, + { + "mode": "100644", + "path": "tests/test_metadata.py", + "sha256": "c3291738c08d1d17de7df983c2608e2457e98f45e0b8763aaddaaf55e2db9336" + }, + { + "mode": "100644", + "path": "tests/test_method_identity.py", + "sha256": "7014c14fc8871ef6bd1c1c984a6eb56a0a15c9706fb0d2b24d2d4d4deb2ed729" + }, + { + "mode": "100644", + "path": "tests/test_models.py", + "sha256": "5f2a60c2d30d7248b3bc914ff44066d308e80e6db99d88001ce350dd0e95655f" + }, + { + "mode": "100644", + "path": "tests/test_opencode_integration.py", + "sha256": "afa5a621a643c20ff2294b6460575ec82bd1c389caee5565329820b939f3b717" + }, + { + "mode": "100644", + "path": "tests/test_packaging.py", + "sha256": "ec428fccdb567d0ccc0793e044e0ffc74574d0311e8a175beffb4894799f9494" + }, + { + "mode": "100644", + "path": "tests/test_platform_adapters.py", + "sha256": "0e2970719f66384db7fd33db57959ce2c44770801eca86e0721f688dcd922dd9" + }, + { + "mode": "100644", + "path": "third-party/core-sources.lock.json", + "sha256": "91a39dfde56856e141cc29795bea8e151dd49a6bd3efcdc042d523dc01df2db8" + } + ], + "repository": "https://github.com/phense/method-core.git", + "revision": "255026bf88469e904514e093d06153f643ba0adb", + "schema_version": 1, + "version": "0.1.0" +} diff --git a/method.json b/method.json new file mode 100644 index 0000000..b7db23d --- /dev/null +++ b/method.json @@ -0,0 +1,18 @@ +{ + "schema_version": 1, + "name": "engineering-method", + "version": "0.3.0", + "method_skills": [ + "architecture-modeling", + "openspec-apply", + "openspec-archive", + "openspec-propose", + "orchestrated-implementation", + "speckit-converge", + "speckit-plan", + "speckit-specify", + "speckit-tasks", + "systematic-debugging", + "test-driven-development" + ] +} diff --git a/pyproject.toml b/pyproject.toml index 2566459..f9d965a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "engineering-method" -version = "0.2.1" +version = "0.3.0" description = "Risk-proportionate engineering workflows for Codex, Claude and OpenCode." requires-python = ">=3.11" license = { text = "MIT" } diff --git a/scripts/clean_install.py b/scripts/clean_install.py index 64a24f5..02748f6 100644 --- a/scripts/clean_install.py +++ b/scripts/clean_install.py @@ -5,6 +5,7 @@ import hashlib import json import os +import re from pathlib import Path, PurePosixPath import subprocess import tempfile @@ -41,29 +42,35 @@ def run_native(command, cwd, env, timeout): def extract_package(package: Path, destination: Path) -> Path: with zipfile.ZipFile(package) as archive: + roots = {PurePosixPath(m.filename).parts[0] for m in archive.infolist() if m.filename} + if len(roots) != 1: + raise ValueError("package must contain one root") + name = roots.pop() + if not re.fullmatch(r"[a-z][a-z0-9-]*",name): + raise ValueError("invalid package root") for member in archive.infolist(): path = PurePosixPath(member.filename) mode = member.external_attr >> 16 - if path.is_absolute() or ".." in path.parts or path.parts[0] != "engineering-method" or mode & 0o170000 == 0o120000: + if path.is_absolute() or ".." in path.parts or path.parts[0] != name or mode & 0o170000 == 0o120000: raise ValueError("unsafe archive member") archive.extractall(destination) for member in archive.infolist(): if not member.is_dir(): (destination / member.filename).chmod((member.external_attr >> 16) & 0o777 or 0o644) - return destination / "engineering-method" + return destination / name -def assert_installed(payload: str, host: str) -> None: +def assert_installed(payload: str, host: str, name: str = "engineering-method") -> None: try: parsed = json.loads(payload) except json.JSONDecodeError as error: raise ValueError(f"{host} returned malformed plugin inventory") from error - identity = "engineering-method@engineering-method" + identity = name + "@" + name if host == "Codex": entries = parsed.get("installed") if isinstance(parsed, dict) else None valid = isinstance(entries, list) and any( isinstance(entry, dict) and entry.get("pluginId") == identity - and entry.get("name") == "engineering-method" and entry.get("marketplaceName") == "engineering-method" + and entry.get("name") == name and entry.get("marketplaceName") == name and entry.get("installed") is True and entry.get("enabled") is True for entry in entries) elif host == "Claude": @@ -84,6 +91,8 @@ def clean_install(package: Path, timeout: int = 60) -> dict: with tempfile.TemporaryDirectory(prefix="em-clean-install-") as directory: temporary = Path(directory) root = extract_package(package, temporary / "package") + name = json.loads((root / ".codex-plugin/plugin.json").read_text())["name"] + identity = name + "@" + name env = isolated_environment(temporary / "configuration") commands = [] def run(command): @@ -92,14 +101,14 @@ def run(command): return output run(["claude", "plugin", "validate", "--strict", str(root)]) run(["claude", "plugin", "marketplace", "add", str(root)]) - run(["claude", "plugin", "install", "engineering-method@engineering-method"]) - assert_installed(run(["claude", "plugin", "list", "--json"]), "Claude") - details = run(["claude", "plugin", "details", "engineering-method@engineering-method"]) - if "engineering-method" not in details: + run(["claude", "plugin", "install", identity]) + assert_installed(run(["claude", "plugin", "list", "--json"]), "Claude", name) + details = run(["claude", "plugin", "details", identity]) + if name not in details: raise ValueError("Claude did not load the plugin inventory") run(["codex", "plugin", "marketplace", "add", str(root), "--json"]) - run(["codex", "plugin", "add", "engineering-method@engineering-method", "--json"]) - assert_installed(run(["codex", "plugin", "list", "--marketplace", "engineering-method", "--json"]), "Codex") + run(["codex", "plugin", "add", identity, "--json"]) + assert_installed(run(["codex", "plugin", "list", "--marketplace", name, "--json"]), "Codex", name) return {"status": "passed", "package_sha256": hashlib.sha256(package.read_bytes()).hexdigest(), "commands": commands, "credentials_used": False, "live_model_requests": False} diff --git a/scripts/install-opencode b/scripts/install-opencode index 773c9f8..641263c 100755 --- a/scripts/install-opencode +++ b/scripts/install-opencode @@ -4,6 +4,8 @@ from __future__ import annotations import argparse import os +import json +import re from pathlib import Path import sys @@ -38,7 +40,11 @@ def main(argv: list[str] | None = None) -> int: source = args.source_root.expanduser().resolve() # Keep lexical ancestors visible until after the symlink check. config = Path(os.path.abspath(args.config_dir.expanduser())) - destination = config / "plugins" / NAME + manifest = source / ".codex-plugin/plugin.json" + identity = json.loads(manifest.read_text())["name"] if manifest.exists() else "engineering-method" + if not isinstance(identity,str) or not re.fullmatch(r"[a-z][a-z0-9-]*",identity): + raise ValueError("invalid method identity") + destination = config / "plugins" / (identity + ".js") require_plain_parents(destination.parent) content = loader_content(source).encode("utf-8") if destination.is_symlink(): @@ -68,7 +74,7 @@ def main(argv: list[str] | None = None) -> int: stream.write(content) print(f"Installed: {destination}\nSource: {source}") return 0 - except (OSError, ValueError) as error: + except (OSError, ValueError, KeyError, TypeError) as error: print(f"install-opencode: {error}", file=sys.stderr) return 1 diff --git a/scripts/method_core.py b/scripts/method_core.py new file mode 100644 index 0000000..4037344 --- /dev/null +++ b/scripts/method_core.py @@ -0,0 +1,343 @@ +"""Pinned, self-contained Method Core exports with transactional local updates. + +No network operations, provider configuration, or target-project state writes. +""" +from __future__ import annotations +import argparse +from contextlib import contextmanager +import hashlib +import json +import os +from pathlib import Path, PurePosixPath +import re +import shutil +import subprocess +import tempfile + +LOCK = 'method-core.lock.json' +TRANSACTION = '.method-core-transaction' +REPOSITORY = 'https://github.com/phense/method-core.git' + + +def safe_name(value): + if not isinstance(value, str) or not value or '\\' in value or '\x00' in value: + raise ValueError('invalid export path') + path = PurePosixPath(value) + if path.is_absolute() or any(part in {'', '.', '..', '.git', '.engineering-method'} for part in value.split('/')) or value == LOCK or path.parts[0].startswith('.method-core-'): + raise ValueError(f'unsafe export path: {value}') + return value + + +def contained(root, name): + safe_name(name) + result = root / name + for node in (root, *result.parents, result): + if node.is_symlink(): + raise ValueError(f'symlinked managed path: {name}') + if result.exists() and not result.is_file(): + raise ValueError(f'managed path is not a file: {name}') + return result + + +def lock_path(root): + path = root / LOCK + if any(p.is_symlink() for p in (root, *root.parents, path)) or (path.exists() and not path.is_file()): + raise ValueError('unsafe core lock path') + return path + + +def parse_lock(raw): + payload = json.loads(raw) + if not isinstance(payload, dict) or payload.get('schema_version') != 1 or payload.get('repository') != REPOSITORY: + raise ValueError('invalid core lock identity/schema') + if not isinstance(payload.get('revision'),str) or not re.fullmatch(r'[0-9a-f]{40}',payload['revision']): + raise ValueError('invalid core revision') + files = payload.get('files') + if not isinstance(files,list) or not files: + raise ValueError('empty or invalid core inventory') + seen = set() + for item in files: + if not isinstance(item,dict): raise ValueError('invalid core inventory entry') + name = safe_name(item.get('path')) + if name in seen: raise ValueError('duplicate core export') + seen.add(name) + if item.get('mode') not in ('100644','100755') or not isinstance(item.get('sha256'),str) or not re.fullmatch(r'[0-9a-f]{64}',item['sha256']): + raise ValueError(f'invalid core hash/mode: {name}') + return payload + + +def check(root, *, allow_transaction=False): + root = Path(os.path.abspath(root)) + if not allow_transaction and (root / TRANSACTION).exists(): + raise ValueError('pending core transaction; run sync-core --recover first') + lock = parse_lock(lock_path(root).read_bytes()) + for item in lock['files']: + path = contained(root,item['path']) + if not path.is_file() or hashlib.sha256(path.read_bytes()).hexdigest() != item['sha256']: + raise ValueError(f'core drift: {item["path"]}') + if path.stat().st_mode & 0o777 != int(item['mode'],8) & 0o777: + raise ValueError(f'core mode drift: {item["path"]}') + return lock + + +def git(root, *args): + result = subprocess.run(['git','-C',str(root),*args],capture_output=True,timeout=30) + if result.returncode: raise ValueError(f'core Git operation failed: {args[0]}') + return result.stdout + + +def read_source(source, revision=None): + revision = git(source,'rev-parse','--verify',(revision or 'HEAD')+'^{commit}').decode().strip() + manifest = json.loads(git(source,'show',revision+':method-core.json')) + if not isinstance(manifest,dict) or manifest.get('schema_version') != 1 or manifest.get('name') != 'method-core': + raise ValueError('invalid core export manifest') + names = manifest.get('exports') + if not isinstance(names,list) or not names: raise ValueError('empty core exports') + names = [safe_name(n) for n in names] + if len(names) != len(set(names)): raise ValueError('duplicate core export') + entries = {} + for row in git(source,'ls-tree','-rz','--full-tree',revision).split(b'\0'): + if not row: continue + meta, raw_name = row.split(b'\t',1) + mode, kind, oid = meta.decode().split() + entries[raw_name.decode()] = (mode, kind, oid) + blobs = {}; records = [] + for name in sorted(names): + mode,kind,oid = entries.get(name,('','','')) + if kind != 'blob' or mode not in ('100644','100755'): raise ValueError(f'missing or nonregular core export: {name}') + blobs[name] = git(source,'cat-file','blob',oid) + records.append({'path':name,'mode':mode,'sha256':hashlib.sha256(blobs[name]).hexdigest()}) + # Reject dirty current exports even when choosing an older committed revision. + current = json.loads(git(source,'show','HEAD:method-core.json')) + checked = sorted(set(names + current.get('exports',[]) + ['method-core.json'])) + if git(source,'status','--porcelain','--untracked-files=all','--',*checked).strip(): + raise ValueError('core exports have uncommitted changes') + lock = {'schema_version':1,'repository':REPOSITORY,'revision':revision,'version':manifest.get('version'),'files':records} + parse_lock(json.dumps(lock)) + return lock,blobs + + +def _replace(path, data, mode): + path.parent.mkdir(parents=True,exist_ok=True) + descriptor, temporary = tempfile.mkstemp(prefix='.method-core-',dir=path.parent) + temporary = Path(temporary) + try: + with os.fdopen(descriptor,'wb') as stream: + stream.write(data);stream.flush();os.fsync(stream.fileno()) + temporary.chmod(mode) + os.replace(temporary,path) + finally: + if temporary.exists(): temporary.unlink() + + +@contextmanager +def _target_guard(target): + # Keep this file permanently: deleting a lock file creates competing inodes. + path = target / '.method-core-sync.lock' + if path.is_symlink() or (path.exists() and not path.is_file()): + raise ValueError('unsafe core synchronization lock') + descriptor = os.open(path, os.O_RDWR | os.O_CREAT | getattr(os, 'O_NOFOLLOW', 0), 0o600) + try: + try: + if os.name == 'nt': + import msvcrt + if os.fstat(descriptor).st_size == 0: os.write(descriptor, b'0') + os.lseek(descriptor, 0, os.SEEK_SET) + msvcrt.locking(descriptor, msvcrt.LK_NBLCK, 1) + else: + import fcntl + fcntl.flock(descriptor, fcntl.LOCK_EX | fcntl.LOCK_NB) + except OSError as error: + raise ValueError('core synchronization/recovery is already active') from error + yield + finally: + os.close(descriptor) # Closing releases either OS lock, also on process death. + + +def _identity(path): + stat = path.stat() + return stat.st_dev, stat.st_ino + + +def _snapshot(path): + return (path.read_bytes(), path.stat().st_mode & 0o777) if path.exists() else None + + +def _transaction_path(target): + path = target / TRANSACTION + if path.is_symlink() or (path.exists() and not path.is_dir()): + raise ValueError('unsafe core transaction directory') + return path + + +def _end_transaction(transaction, identity): + # Retire the complete journal atomically. A crash during garbage collection + # must not leave an active journal with only some of its backups remaining. + if _identity(transaction) != identity: raise ValueError('core transaction identity changed') + retired = Path(tempfile.mkdtemp(prefix='.method-core-retired-', dir=transaction.parent)) + retired.rmdir() + os.rename(transaction, retired) + shutil.rmtree(retired) + + +def _begin_transaction(target, saved): + # Publish complete backups atomically, before changing any managed file. + transaction = _transaction_path(target) + if transaction.exists(): + raise ValueError('another core transaction is pending') + stage = Path(tempfile.mkdtemp(prefix='.method-core-stage-', dir=target)) + stage.chmod(0o700) + try: + entries = [] + for index, (path, previous) in enumerate(saved.items()): + entry = {'path': path.relative_to(target).as_posix(), 'previous': None} + if previous is not None: + data, mode = previous + with (stage / str(index)).open('wb') as stream: + stream.write(data); stream.flush(); os.fsync(stream.fileno()) + entry['previous'] = {'mode': mode, 'sha256': hashlib.sha256(data).hexdigest()} + entries.append(entry) + with (stage / 'journal.json').open('w') as stream: + json.dump({'schema_version': 1, 'pid': os.getpid(), 'files': entries}, stream) + stream.flush(); os.fsync(stream.fileno()) + os.rename(stage, transaction) + finally: + if stage.exists(): shutil.rmtree(stage) + # A competing updater may have finished between preflight and acquiring the + # transaction. We have written nothing, so discard our backups, never restore them. + identity = _identity(transaction) + if any(_snapshot(path) != previous for path, previous in saved.items()): + _end_transaction(transaction, identity) + raise ValueError('core target changed during preflight; retry synchronization') + return identity + + +def recover_transaction(target): + target = Path(os.path.abspath(target)) + lock_path(target) + with _target_guard(target): + return _recover_transaction(target) + + +def _recover_transaction(target, *, owner=False): + target = Path(os.path.abspath(target)) + transaction = _transaction_path(target) + if not transaction.exists(): return False + identity = _identity(transaction) + journal_path = transaction / 'journal.json' + if journal_path.is_symlink(): raise ValueError('unsafe core transaction journal') + journal = json.loads(journal_path.read_bytes()) + if journal.get('schema_version') != 1 or not isinstance(journal.get('pid'), int) or journal['pid'] <= 0: + raise ValueError('invalid core transaction journal') + if not owner: + try: os.kill(journal['pid'], 0) + except ProcessLookupError: pass + except PermissionError: raise ValueError('core transaction owner is still active') + else: raise ValueError('core transaction owner is still active') + entries = journal.get('files') + if not isinstance(entries, list) or not entries: raise ValueError('invalid transaction inventory') + saved = []; seen = set() + # Validate every backup and destination before attempting recovery. + for index, entry in enumerate(entries): + name = entry['path'] + path = lock_path(target) if name == LOCK else contained(target, name) + if name in seen: raise ValueError('duplicate transaction path') + seen.add(name) + previous = entry['previous'] + if previous is not None: + if not isinstance(previous.get('mode'), int) or not 0 <= previous['mode'] <= 0o777: raise ValueError('invalid backup mode') + backup = transaction / str(index) + if backup.is_symlink(): raise ValueError('unsafe transaction backup') + data = backup.read_bytes() + if hashlib.sha256(data).hexdigest() != previous.get('sha256'): raise ValueError('damaged transaction backup') + previous = (data, previous['mode']) + saved.append((path, previous)) + errors = [] + for path, previous in reversed(saved): + try: + if _snapshot(path) == previous: continue + if previous is None: + path.unlink(missing_ok=True) + else: + _replace(path, *previous) + except OSError as error: + # Restore the other paths too, retaining all durable backups for retry. + errors.append(f'{path.relative_to(target)}: {error}') + if errors: raise OSError('core recovery incomplete; backups retained: ' + '; '.join(errors)) + _end_transaction(transaction, identity) + return True + + +def synchronize(source, target, revision=None): + target = Path(os.path.abspath(target)) + if not target.is_dir(): raise ValueError('target root must exist') + lock_path(target) + proposed, blobs = read_source(source, revision) + with _target_guard(target): + return _synchronize(target, proposed, blobs) + + +def _synchronize(target, proposed, blobs): + target = Path(os.path.abspath(target)) + if not target.is_dir(): raise ValueError('target root must exist') + # Recovery is explicit: an interrupted update cannot silently become a new one. + if _transaction_path(target).exists(): + raise ValueError('pending core transaction; run sync-core --recover first') + lp = lock_path(target) + prior = check(target) if lp.exists() else {'files':[]} + old_names = {entry['path'] for entry in prior['files']} + new_names = {entry['path'] for entry in proposed['files']} + modes = {entry['path']:int(entry['mode'],8)&0o777 for entry in proposed['files']} + for name in sorted(old_names | new_names): + path = contained(target,name) + if path.exists() and name not in old_names: + raise ValueError(f'unowned core destination: {name}') + paths = [contained(target,name) for name in sorted(old_names | new_names)] + [lp] + saved = {path:_snapshot(path) for path in paths} + directories = set() + for path in paths: + parent=path.parent + while parent != target and not parent.exists(): + directories.add(parent);parent=parent.parent + identity = _begin_transaction(target, saved) + try: + for name in sorted(new_names): _replace(target/name,blobs[name],modes[name]) + for name in sorted(old_names-new_names): (target/name).unlink() + _replace(lp,(json.dumps(proposed,indent=2,sort_keys=True)+'\n').encode(),0o644) + check(target, allow_transaction=True) + except BaseException: + _recover_transaction(target, owner=True) + for directory in sorted(directories,key=lambda p:len(p.parts),reverse=True): + if directory.exists() and not any(directory.iterdir()): directory.rmdir() + raise + _end_transaction(_transaction_path(target), identity) + return proposed + + +def main(argv=None): + parser=argparse.ArgumentParser(description=__doc__) + parser.add_argument('--target-root',type=Path,default=Path.cwd()) + parser.add_argument('--source-root',type=Path) + parser.add_argument('--revision') + mode = parser.add_mutually_exclusive_group() + mode.add_argument('--check',action='store_true') + mode.add_argument('--recover',action='store_true') + args=parser.parse_args(argv) + try: + if args.recover: + if args.source_root or args.revision: raise ValueError('--recover is offline; omit source/revision') + recovered = recover_transaction(args.target_root) + print(json.dumps({'status':'passed','recovered':recovered})) + return 0 + if args.check: + if args.source_root or args.revision: raise ValueError('--check is offline; omit source/revision') + result=check(args.target_root) + else: + if not args.source_root: raise ValueError('--source-root is required for synchronization') + result=synchronize(args.source_root,args.target_root,args.revision) + print(json.dumps({'status':'passed','revision':result['revision'],'files':len(result['files'])})) + return 0 + except (OSError,ValueError,TypeError,KeyError,subprocess.TimeoutExpired) as error: + print(json.dumps({'status':'failed','error':str(error)}));return 1 + +if __name__=='__main__': raise SystemExit(main()) diff --git a/scripts/package_plugin.py b/scripts/package_plugin.py index b2942f1..7522314 100644 --- a/scripts/package_plugin.py +++ b/scripts/package_plugin.py @@ -4,6 +4,7 @@ import argparse import hashlib import json +import re from pathlib import Path, PurePosixPath import subprocess import tempfile @@ -34,9 +35,19 @@ def included(name: str) -> bool: def build_package(root: Path, output: Path, *, commit: str | None = None) -> dict: commit = commit or source_commit(root) + tree = git(root, "ls-tree", "--name-only", commit).decode().splitlines() + if ".codex-plugin" in tree: + name = json.loads(git(root, "show", commit + ":.codex-plugin/plugin.json"))["name"] + elif "method-core.json" in tree: + name = "method-core" + else: + name = "engineering-method" + if not isinstance(name, str) or not re.fullmatch(r"[a-z][a-z0-9-]*", name): + raise ValueError("invalid committed package identity") entries = git(root, "ls-tree", "-rz", "--full-tree", commit).split(b"\0") output.parent.mkdir(parents=True, exist_ok=True) count = 0 + package_prefix = name + "/" with zipfile.ZipFile(output, "w", compression=zipfile.ZIP_STORED) as archive: for entry in sorted(item for item in entries if item): metadata, raw_name = entry.split(b"\t", 1) @@ -49,7 +60,7 @@ def build_package(root: Path, output: Path, *, commit: str | None = None) -> dic path = PurePosixPath(name) if path.is_absolute() or ".." in path.parts: raise ValueError("unsafe Git package path") - info = zipfile.ZipInfo("engineering-method/" + name, date_time=(1980, 1, 1, 0, 0, 0)) + info = zipfile.ZipInfo(package_prefix + name, date_time=(1980, 1, 1, 0, 0, 0)) info.create_system = 3 info.external_attr = int(mode, 8) << 16 archive.writestr(info, git(root, "cat-file", "blob", object_id)) diff --git a/scripts/run_host_evals.py b/scripts/run_host_evals.py index eef7fc7..a6d613a 100644 --- a/scripts/run_host_evals.py +++ b/scripts/run_host_evals.py @@ -28,13 +28,17 @@ def private_transcript(path, text): stream.write(text) os.chmod(path, 0o600) -def normalize_skill(name): - if isinstance(name, str) and name.startswith("engineering-method:"): - return name[len("engineering-method:"):] +def normalize_skill(name, plugin=ROOT): + manifest = plugin / ".codex-plugin/plugin.json" + identity = json.loads(manifest.read_text())["name"] if manifest.is_file() else "engineering-method" + prefix = identity + ":" + if isinstance(name, str) and name.startswith(prefix): + return name[len(prefix):] if isinstance(name, str) and ":" in name: raise EvalFailure("unexpected_skill_namespace") return name + def model_policy(host, plugin=ROOT): text = (plugin / f"shared/platform/{host}.md").read_text() policy = json.loads(re.search(r"```json\n(.*?)\n```", text, re.DOTALL).group(1)) @@ -454,7 +458,7 @@ def _parse_transcript(host, text, plugin=ROOT): if name == "Read" and block.get("content"): skills.update(SKILL_PATH.findall(arguments.get("file_path", ""))) if name == "Skill" and block.get("content"): - selected_skill = normalize_skill(arguments.get("skill", "")) + selected_skill = normalize_skill(arguments.get("skill", ""), plugin) skills.add(selected_skill) invoked.add(selected_skill) if name == "Bash" and block.get("content"): @@ -475,9 +479,9 @@ def _parse_transcript(host, text, plugin=ROOT): raise ValueError("decision must be object") except (ValueError, TypeError) as exc: raise EvalFailure("malformed_decision") from exc - decision["primary"] = normalize_skill(decision.get("primary")) + decision["primary"] = normalize_skill(decision.get("primary"), plugin) if isinstance(decision.get("supporting"), list): - decision["supporting"] = [normalize_skill(name) for name in decision["supporting"]] + decision["supporting"] = [normalize_skill(name, plugin) for name in decision["supporting"]] return {"decision": decision, "skills": sorted(skills), "invoked_skills": sorted(invoked), "tools": tools, "reviewers": reviewers, "event_count": len(events)} def check_routing(transcript, expected, repo): @@ -589,7 +593,7 @@ def host_command(host, repo, plugin, config, model, auth_home=None, prompt="", b SKILL_DISCOVERY_INSTRUCTION = """ The shared skill files are linked directly at -.agents/skills//SKILL.md in this repository. The engineering-method: +.agents/skills//SKILL.md in this repository. The method-qualified invocation namespace is not an extra filesystem directory. Discover actual paths with `rg --files --hidden --follow .agents/skills -g SKILL.md`, then read the selected files. Ordinary searches without symlink following may miss these files; @@ -605,7 +609,7 @@ def host_command(host, repo, plugin, config, model, auth_home=None, prompt="", b """ ROUTING_INSTRUCTION = SKILL_DISCOVERY_INSTRUCTION + """ -Assess the request and current repository using the available engineering-method +Assess the request and current repository using the available method skills. Perform the first safe assessment step only; do not implement the entire feature or launch subagents in this routing evaluation. Open the selected skill instructions through tools before applying them. The assessment includes that @@ -687,8 +691,8 @@ def main(argv=None): parser.error("output must not overwrite fixture or plugin sources") output.mkdir(parents=True, exist_ok=True) os.chmod(output, 0o700) - expected = json.loads((ROOT / f"evals/{args.host}/expected.json").read_text()) - cases = [json.loads(path.read_text()) for path in sorted((ROOT / "evals/shared/triggers").glob("*.json"))] + expected = json.loads((args.plugin_root / f"evals/{args.host}/expected.json").read_text()) + cases = [json.loads(path.read_text()) for path in sorted((args.plugin_root / "evals/shared/triggers").glob("*.json"))] if args.case: cases = [case for case in cases if case["id"] == args.case] if not cases: @@ -706,7 +710,7 @@ def main(argv=None): print(json.dumps(result), flush=True) if result["status"] != "passed": break - commit = subprocess.run(["git", "rev-parse", "HEAD"], cwd=ROOT, capture_output=True, text=True) + commit = subprocess.run(["git", "rev-parse", "HEAD"], cwd=args.plugin_root, capture_output=True, text=True) summary = {"status": "passed" if len(results) == len(cases) and all(r["status"] == "passed" for r in results) else "failed", "host": args.host, "native_auth": args.native_auth, "source_commit": commit.stdout.strip(), "source_sha256": fingerprint(args.plugin_root), "completed_at": datetime.now(timezone.utc).isoformat(), diff --git a/scripts/sync-core b/scripts/sync-core new file mode 100755 index 0000000..19a1e83 --- /dev/null +++ b/scripts/sync-core @@ -0,0 +1,3 @@ +#!/usr/bin/env python3 +from method_core import main +raise SystemExit(main()) diff --git a/scripts/validate_plugin.py b/scripts/validate_plugin.py index df3a4e3..2fe7a2b 100644 --- a/scripts/validate_plugin.py +++ b/scripts/validate_plugin.py @@ -474,10 +474,57 @@ def _validate_marketplaces(root: Path, name: object, errors: list[str]) -> None: errors.append(_error(relative, "owner.name is required")) +def _core_integrity(root: Path, errors: list[str]) -> None: + try: + from .method_core import check, contained, safe_name + except ImportError: + from method_core import check, contained, safe_name + if (root / "method-core.json").is_file(): + try: + manifest = json.loads((root / "method-core.json").read_text()) + names = manifest["exports"] + if manifest.get("schema_version") != 1 or manifest.get("name") != "method-core" or not isinstance(names,list) or not names or len(names) != len(set(names)): + raise ValueError("invalid core export inventory") + for name in names: + if not contained(root,safe_name(name)).is_file(): + raise ValueError(f"missing core export: {name}") + except (OSError,ValueError,TypeError,KeyError) as error: + errors.append(_error("method-core.json",str(error))) + if (root / "method.json").is_file(): + try: + check(root) + except (OSError,ValueError,TypeError,KeyError) as error: + errors.append(_error("method-core.lock.json",str(error))) + try: + profile = json.loads((root / "method.json").read_text()) + own = profile["method_skills"] + if not isinstance(own,list) or not own or len(own) != len(set(own)) or not all(isinstance(n,str) and SKILL_NAME.fullmatch(n) for n in own): + raise ValueError("invalid method skill inventory") + bundled = {p.parent.name for p in (root / "skills").glob("*/SKILL.md")} + locked = json.loads((root / "method-core.lock.json").read_text()) + shared = {item["path"].split("/")[1] for item in locked["files"] if re.fullmatch(r"skills/[^/]+/SKILL.md",item["path"])} + if bundled != set(own) | shared or set(own) & shared: + raise ValueError("method skills disagree with owned and shared inventories") + except (OSError,ValueError,TypeError,KeyError) as error: + errors.append(_error("method.json",str(error))) + + def validate_repository(root: Path) -> list[str]: """Return sorted validation errors, or an empty list.""" root = root.resolve() errors: list[str] = [] + _core_integrity(root, errors) + if (root / "method-core.json").is_file() and not (root / "method.json").exists(): + _validate_skill_frontmatter(root, errors) + _validate_project_backlog_contract(root, errors) + _validate_skill_resources(root, errors) + _validate_platform_boundary(root, errors) + if (root / "third-party/sources.lock.json").is_file(): + lock = _load_json(root, "third-party/sources.lock.json", errors) + if lock is not None: _validate_locked_destinations(root,lock,errors) + else: + errors.append(_error("third-party/sources.lock.json","file is required")) + return sorted(errors) codex_relative = ".codex-plugin/plugin.json" claude_relative = ".claude-plugin/plugin.json" codex = _load_json(root, codex_relative, errors) @@ -512,6 +559,10 @@ def validate_repository(root: Path) -> list[str]: _validate_platform_boundary(root, errors) if lock is not None: _validate_locked_destinations(root, lock, errors) + core_provenance = root / "third-party/core-sources.lock.json" + if core_provenance.is_file(): + core_lock = _load_json(root,"third-party/core-sources.lock.json",errors) + if core_lock is not None: _validate_locked_destinations(root,core_lock,errors) _validate_unfinished_markers(root, errors) return sorted(errors) diff --git a/shared/platform/claude.md b/shared/platform/claude.md index 602f0e9..da12e6f 100644 --- a/shared/platform/claude.md +++ b/shared/platform/claude.md @@ -1,6 +1,6 @@ # Claude adapter -Original Engineering Method host mapping. Shared skills keep semantic names; +Shared Method Core host mapping. Shared skills keep semantic names; resolve them against this adapter in Claude Code. The conventional plugin-root `skills/` directory is the same tree exposed by the Codex manifest. @@ -82,10 +82,13 @@ Verified with `claude --help`, `claude plugin validate --help`, `claude plugin marketplace add --help`, and `claude plugin install --help` at the stated version. Commands describe interfaces, not completed live validation. +Set `method_name` to the installed consumer identity from +`.codex-plugin/plugin.json` (`engineering-method` or `writing-method`). + ```sh env CLAUDE_CONFIG_DIR="$em_claude_home" claude plugin validate "$em_package" --strict --json env CLAUDE_CONFIG_DIR="$em_claude_home" claude plugin marketplace add "$em_package" -env CLAUDE_CONFIG_DIR="$em_claude_home" claude plugin install engineering-method@engineering-method +env CLAUDE_CONFIG_DIR="$em_claude_home" claude plugin install "${method_name}@${method_name}" env CLAUDE_CONFIG_DIR="$em_claude_home" claude -p --plugin-dir "$em_package" --output-format stream-json --verbose --no-session-persistence --setting-sources "" --strict-mcp-config --permission-mode dontAsk --permission-prompts none --model fable --effort medium --max-budget-usd 1 ``` @@ -118,13 +121,12 @@ Do not use `--safe-mode`: it disables plugins and skills. If using the separate otherwise be enabled by default. The custom stream driver above does not use that feature. -## Reader-oriented output +## Method integration -Explanations, instructions and troubleshooting help written for the user or -for another reader follow the shared [reader-oriented output -policy](../policies/reader-oriented-output.md) and its skills -`explaining-concepts`, `writing-procedures` and `empathic-troubleshooting`. -Documentation work decides its scale with the [writing-depth -policy](../policies/writing-depth.md) before selecting a writing lifecycle. -The policy shapes wording and order only; verification and evidence rules are -unchanged. +Both consuming methods bundle this same adapter and shared support. The invoking +method owns lifecycle selection and its method-specific policies. Read the +consumer's `shared/policies/lifecycle-selection.md` when present. For shared +support choose the invoking plugin's namespace; do not run duplicate copies or +start another method merely because it is installed. Core support does not +require either method's optional skills. Gemini-specific behavior is deferred +until a separate adapter has been verified. diff --git a/shared/platform/codex.md b/shared/platform/codex.md index c2e579a..28010bd 100644 --- a/shared/platform/codex.md +++ b/shared/platform/codex.md @@ -1,6 +1,6 @@ # Codex adapter -Original Engineering Method host mapping. Shared skills keep semantic names; +Shared Method Core host mapping. Shared skills keep semantic names; resolve those names against this adapter when executing in Codex. Both host manifests expose the same plugin-root `skills/` tree. @@ -81,10 +81,13 @@ Verified locally with `codex exec --help`, `codex plugin marketplace add The following are command shapes, not claims of successful live evaluation. Variables denote absolute paths supplied by the caller. +Set `method_name` to the installed consumer identity from +`.codex-plugin/plugin.json` (`engineering-method` or `writing-method`). + ```sh env CODEX_HOME="$em_codex_home" codex plugin marketplace add "$em_package" --json -env CODEX_HOME="$em_codex_home" codex plugin add engineering-method@engineering-method --json -env CODEX_HOME="$em_codex_home" codex plugin list --marketplace engineering-method --json +env CODEX_HOME="$em_codex_home" codex plugin add "${method_name}@${method_name}" --json +env CODEX_HOME="$em_codex_home" codex plugin list --marketplace "$method_name" --json env CODEX_HOME="$em_codex_home" codex exec -C "$em_fixture" --ephemeral --json --sandbox workspace-write -m gpt-6-astra -c 'model_reasoning_effort="medium"' -o "$em_output/final.txt" - ``` @@ -104,13 +107,12 @@ test. Never copy, read, or symlink credentials for isolation, and never mutate global plugin settings. A fully isolated live home needs human-controlled login. Preserve account authentication and never fall back to an API key. -## Reader-oriented output +## Method integration -Explanations, instructions and troubleshooting help written for the user or -for another reader follow the shared [reader-oriented output -policy](../policies/reader-oriented-output.md) and its skills -`explaining-concepts`, `writing-procedures` and `empathic-troubleshooting`. -Documentation work decides its scale with the [writing-depth -policy](../policies/writing-depth.md) before selecting a writing lifecycle. -The policy shapes wording and order only; verification and evidence rules are -unchanged. +Both consuming methods bundle this same adapter and shared support. The invoking +method owns lifecycle selection and its method-specific policies. Read the +consumer's `shared/policies/lifecycle-selection.md` when present. For shared +support choose the invoking plugin's namespace; do not run duplicate copies or +start another method merely because it is installed. Core support does not +require either method's optional skills. Gemini-specific behavior is deferred +until a separate adapter has been verified. diff --git a/shared/platform/opencode.md b/shared/platform/opencode.md index 717058a..b8b7058 100644 --- a/shared/platform/opencode.md +++ b/shared/platform/opencode.md @@ -82,36 +82,12 @@ agentic-rag remains separate. An existing read-only MCP server can be used when needed and permitted, but this plugin neither configures it nor grants write access. Never read or copy credential files to another host or provider. -## Reader-oriented output - -Because this file is loaded as an OpenCode instruction, the shared -[reader-oriented output policy](../policies/reader-oriented-output.md) applies -to ordinary replies here: explanations lead with an everyday analogy and avoid -undefined jargon (`explaining-concepts`), instructions are numbered imperative -steps with exact locations and a visible result (`writing-procedures`), and -help with failures starts from the symptom the user sees -(`empathic-troubleshooting`). Documentation requests decide their scale with -the [writing-depth policy](../policies/writing-depth.md) before loading -`documentation-authoring` or `documentation-planning`. Evidence and -verification rules are unchanged. - -## Verification interfaces and limits - -- opencode debug skill: native skill inventory. Write stdout directly to a file; - version 1.18.30 can truncate large piped JSON on exit. -- opencode run --model --format json: bounded behavioral probe - in a disposable fixture with explicitly scoped permissions. -- In T3, refresh provider status after installation. If the helper remains cached, - allow it to become idle for at least 30 seconds before refreshing, or finish - active work and restart the helper. Start a new thread for fresh instructions. - -Discovery and bounded skill-use tests do not constitute full workflow, -multi-agent, architecture or compaction acceptance. - -Sources checked 2026-09-11: -- https://opencode.ai/docs/skills/ -- https://opencode.ai/docs/plugins/ -- https://opencode.ai/docs/agents/ -- https://opencode.ai/docs/config/ -- https://github.com/anomalyco/opencode/blob/v1.18.30/packages/plugin/src/index.ts -- https://github.com/pingdotgg/t3code/blob/v0.0.40/docs/user/providers-opencode.md +## Method integration + +Both consuming methods bundle this same adapter and shared support. The invoking +method owns lifecycle selection and its method-specific policies. Read the +consumer's `shared/policies/lifecycle-selection.md` when present. For shared +support choose the invoking plugin's namespace; do not run duplicate copies or +start another method merely because it is installed. Core support does not +require either method's optional skills. Gemini-specific behavior is deferred +until a separate adapter has been verified. diff --git a/shared/policies/engineering-playbooks.md b/shared/policies/engineering-playbooks.md new file mode 100644 index 0000000..d0d1eb2 --- /dev/null +++ b/shared/policies/engineering-playbooks.md @@ -0,0 +1,29 @@ +# Engineering playbook integration + +Shared policy and templates are bundled from Method Core. + + +- `speckit-specify`: identify system-deliverable playbooks from user and operating + scenarios, including preventive recovery. Record scope and acceptance criteria. +- `speckit-plan` and design-time `architecture-modeling`: assess development + operations and refine system needs against dependencies and failure modes. + Material additions to delivery scope return to the specification owner. +- `openspec-propose`: perform both assessments in proposal/delta and design; + include affected existing playbooks and their compatibility changes. +- `speckit-tasks` or OpenSpec tasks: add authoring, review and required rehearsal + tasks with explicit dependencies. Development readiness blocks the operation; + system readiness blocks delivery. Ordinary task planning remains unchanged. +- `orchestrated-implementation` and `openspec-apply`: invoke `playbook-authoring` + for assigned artifacts and `playbook-review` before use/acceptance. Track fixes + in the same work ID. Coordinate authorized rehearsals and preserve evidence. +- As-built `architecture-modeling`: check playbook assumptions against actual + interfaces and relevant recovery flows; flag stale evidence for affected paths. +- `speckit-converge` and `openspec-archive`: check every required playbook against + the need inventory, current artifact/system revision, review and required + rehearsal evidence. Missing or stale proof blocks completion. Return findings + to the existing executor; do not execute or repair procedures in the gate. + +Direct authoring/review requests use the supporting skill without creating an +engineering lifecycle solely for a document. If the request changes system +behavior, the appropriate engineering lifecycle owns that change. + diff --git a/shared/policies/lifecycle-handoffs.md b/shared/policies/lifecycle-handoffs.md index f4e4076..193a56b 100644 --- a/shared/policies/lifecycle-handoffs.md +++ b/shared/policies/lifecycle-handoffs.md @@ -1,10 +1,6 @@ # Lifecycle Handoffs -Every phase consumes current artifacts from disk, creates or updates only its -declared outputs, verifies its completion condition, and names one next phase. -Semantic skill names are portable; platform adapters decide how to invoke them. - -The following JSON is the authoritative, machine-readable handoff graph: +Every phase consumes current artifacts from disk and names one next phase. ```json { @@ -20,70 +16,109 @@ The following JSON is the authoritative, machine-readable handoff graph: "architecture-modeling", "speckit-tasks", "orchestrated-implementation", - "speckit-converge", - "documentation-planning", - "documentation-authoring", - "documentation-review" + "speckit-converge" ], "executors": { "bugfix": "test-driven-development", "openspec": "openspec-apply", - "speckit": "orchestrated-implementation", - "documentation": "documentation-authoring" + "speckit": "orchestrated-implementation" }, "edges": [ - {"from": "systematic-debugging", "to": "test-driven-development", "artifact": "reproduction and root-cause evidence"}, - {"from": "systematic-debugging", "to": "openspec-propose", "artifact": "docs/openspec/changes//proposal.md", "condition": "evidence establishes a bounded intentional contract change", "deactivates": "systematic-debugging", "traceability": "proposal links the reproduction and root-cause evidence"}, - {"from": "systematic-debugging", "to": "speckit-specify", "artifact": "docs/specs/-/spec.md", "condition": "evidence establishes an architecture change or large-feature scope", "deactivates": "systematic-debugging", "traceability": "feature spec links the reproduction and root-cause evidence"}, - {"from": "test-driven-development", "to": "verification-before-completion", "artifact": "verified red-green evidence"}, - {"from": "openspec-propose", "to": "openspec-apply", "artifact": "docs/openspec/changes//tasks.md"}, - {"from": "openspec-apply", "to": "openspec-archive", "artifact": "completed tasks and fresh verification"}, - {"from": "speckit-specify", "to": "speckit-plan", "artifact": "docs/specs/-/spec.md"}, - {"from": "speckit-plan", "to": "architecture-modeling", "artifact": "docs/specs/-/plan.md"}, - {"from": "architecture-modeling", "to": "speckit-tasks", "artifact": "verified design findings"}, - {"from": "speckit-tasks", "to": "orchestrated-implementation", "artifact": "docs/specs/-/tasks.md"}, - {"from": "orchestrated-implementation", "to": "speckit-converge", "artifact": "implementation, as-built models, integration results, and review state", "required_gate": "architecture-modeling:as-built"}, - {"from": "speckit-converge", "to": "verification-before-completion", "artifact": "closed convergence findings", "completion_guard": "no actionable findings and all evidence current"}, - {"from": "openspec-propose", "to": "speckit-specify", "artifact": "docs/openspec/changes//escalation.md", "condition": "status: escalated", "deactivates": "openspec-propose", "traceability": "escalation record preserves the change path and new feature ID"}, - {"from": "openspec-apply", "to": "speckit-specify", "artifact": "docs/openspec/changes//escalation.md", "condition": "status: escalated", "deactivates": "openspec-apply", "traceability": "escalation record preserves completed task IDs, change path, and new feature ID"}, - {"from": "documentation-planning", "to": "documentation-authoring", "artifact": "docs/writing//plan.md"}, - {"from": "documentation-authoring", "to": "documentation-review", "artifact": "drafted chunk files with frontmatter, glossary and asset manifest state"}, - {"from": "documentation-review", "to": "verification-before-completion", "artifact": "docs/writing//review.md", "completion_guard": "no open Critical or Important findings at the reviewed revision"} + { + "from": "systematic-debugging", + "to": "test-driven-development", + "artifact": "reproduction and root-cause evidence" + }, + { + "from": "systematic-debugging", + "to": "openspec-propose", + "artifact": "docs/openspec/changes//proposal.md", + "condition": "evidence establishes a bounded intentional contract change", + "deactivates": "systematic-debugging", + "traceability": "proposal links the reproduction and root-cause evidence" + }, + { + "from": "systematic-debugging", + "to": "speckit-specify", + "artifact": "docs/specs/-/spec.md", + "condition": "evidence establishes an architecture change or large-feature scope", + "deactivates": "systematic-debugging", + "traceability": "feature spec links the reproduction and root-cause evidence" + }, + { + "from": "test-driven-development", + "to": "verification-before-completion", + "artifact": "verified red-green evidence" + }, + { + "from": "openspec-propose", + "to": "openspec-apply", + "artifact": "docs/openspec/changes//tasks.md" + }, + { + "from": "openspec-apply", + "to": "openspec-archive", + "artifact": "completed tasks and fresh verification" + }, + { + "from": "speckit-specify", + "to": "speckit-plan", + "artifact": "docs/specs/-/spec.md" + }, + { + "from": "speckit-plan", + "to": "architecture-modeling", + "artifact": "docs/specs/-/plan.md" + }, + { + "from": "architecture-modeling", + "to": "speckit-tasks", + "artifact": "verified design findings" + }, + { + "from": "speckit-tasks", + "to": "orchestrated-implementation", + "artifact": "docs/specs/-/tasks.md" + }, + { + "from": "orchestrated-implementation", + "to": "speckit-converge", + "artifact": "implementation, as-built models, integration results, and review state", + "required_gate": "architecture-modeling:as-built" + }, + { + "from": "speckit-converge", + "to": "verification-before-completion", + "artifact": "closed convergence findings", + "completion_guard": "no actionable findings and all evidence current" + }, + { + "from": "openspec-propose", + "to": "speckit-specify", + "artifact": "docs/openspec/changes//escalation.md", + "condition": "status: escalated", + "deactivates": "openspec-propose", + "traceability": "escalation record preserves the change path and new feature ID" + }, + { + "from": "openspec-apply", + "to": "speckit-specify", + "artifact": "docs/openspec/changes//escalation.md", + "condition": "status: escalated", + "deactivates": "openspec-apply", + "traceability": "escalation record preserves completed task IDs, change path, and new feature ID" + } ], "retry_transitions": [ - {"from": "speckit-converge", "to": "orchestrated-implementation", "condition": "actionable findings appended as new slices", "artifact": "tasks.md append-only convergence slices", "preserves": "completed work and stable task IDs"}, - {"from": "documentation-review", "to": "documentation-authoring", "condition": "actionable findings returned for affected chunks", "artifact": "docs/writing//review.md findings", "preserves": "accepted chunks and stable chunk IDs"} + { + "from": "speckit-converge", + "to": "orchestrated-implementation", + "condition": "actionable findings appended as new slices", + "artifact": "tasks.md append-only convergence slices", + "preserves": "completed work and stable task IDs" + } ] } ``` -Reclassification and escalation edges are exceptional. Deactivate the prior -lifecycle before the destination becomes active and preserve the source -evidence, stable IDs, and artifact path named by the edge. For OpenSpec, -preserve the change and write the formal escalation record before Spec Kit -starts. - -The forward phase graph remains acyclic. A convergence retry, or a documentation -review returning findings, is an explicit return to the existing executor, -never a new controller or a completion handoff. Before convergence, that executor invokes the architecture skill in -as-built mode and carries its reconciliation and integration evidence forward. - -## Documentation lifecycle - -Reader-facing documentation follows the [writing-depth policy](writing-depth.md). -A documentation set runs `documentation-planning` → `documentation-authoring` -→ `documentation-review` → `verification-before-completion`; review findings -return to the same authoring executor. A standalone document enters -`documentation-authoring` directly and closes with a recorded self-review. The -documentation lifecycle never shares a work ID with an engineering lifecycle; -software behavior stays with Spec Kit, OpenSpec or debugging. - -## Supporting playbook handoffs - -The [playbook policy](playbooks.md) adds conditional support within the existing -engineering phases. `playbook-authoring` returns a drafted procedure to its -owner; `playbook-review` returns a separate report. Findings return to authoring -through that owner. Neither skill is a lifecycle controller or application -executor. Required development readiness precedes its operation; required system -readiness precedes convergence or archival. Both require the agreed current -review and rehearsal evidence, which are distinct acceptance facts. +The forward phase graph remains acyclic. A convergence retry returns to the existing executor. Before convergence, that executor invokes the architecture skill in as-built mode and carries integration evidence forward. Playbook authoring/review are supporting skills under the shared [playbook policy](playbooks.md). diff --git a/shared/policies/lifecycle-selection.md b/shared/policies/lifecycle-selection.md index 7791f5b..eee8d04 100644 --- a/shared/policies/lifecycle-selection.md +++ b/shared/policies/lifecycle-selection.md @@ -10,14 +10,8 @@ state. Supporting skills may compose with it but never take ownership from it. | New capability, cross-component feature, architecture, risky migration, or material unresolved design | `speckit-specify` | Not a localized Brownfield delta or ordinary defect | | Existing lifecycle artifact awaiting its next phase | The phase named by that artifact state | Do not start a second lifecycle for the same work | | Small reversible edit with no behavior-contract impact | Native focused edit | No specification, plan, architecture model, or implementation orchestrator | -| Documentation set: several chapters or documents sharing readers, terms, structure or images | `documentation-planning` | Not one standalone document, a wording fix, or software specification | -| One standalone reader-facing document | `documentation-authoring` | Not a sentence-level fix, a multi-document set, or an engineering artifact | -Prose work decides its scale first with the [writing-depth -policy](writing-depth.md); existing `docs/writing//` artifacts fix the -scale and phase. An active OpenSpec change stays in OpenSpec unless its proposal records a formal -escalation. An active Spec Kit feature stays in Spec Kit. When the request is -ambiguous at the nearest boundary, inspect the affected code and artifacts +Writing requests belong to the optional companion writing-method plugin. If the request is ambiguous at the nearest boundary, inspect the affected code and artifacts read-only; ask only if the answer would materially change scope or ownership. ## Engineering playbooks @@ -27,5 +21,7 @@ Scenario-bound development and system-deliverable playbooks use [playbook policy](playbooks.md). They are engineering artifacts, including when their audience is an end user, and retain the owning engineering work ID. Direct requests enter the supporting skill without starting a new lifecycle. -Generic manuals and tutorials retain the documentation routes above. A request +Generic manuals and tutorials belong to the optional writing-method companion. A request for new system behavior still enters the appropriate engineering phase first. + +Engineering phase hooks: [engineering playbooks](engineering-playbooks.md). diff --git a/shared/policies/playbooks.md b/shared/policies/playbooks.md index 4cee2fe..a5ba8d2 100644 --- a/shared/policies/playbooks.md +++ b/shared/policies/playbooks.md @@ -1,8 +1,8 @@ -# Engineering Playbooks +# Shared Playbooks A playbook is a scenario-bound procedure with decisions, observable outcomes and failure paths. A task list or design explanation alone is not a playbook. -Playbooks support the current engineering lifecycle; they do not create another +Playbooks support the current method lifecycle; they do not create another controller, executor or documentation work ID. Apply [proportionality](proportionality.md). ## Decide whether one is needed @@ -12,8 +12,8 @@ operations and actual system evidence. A prior incident is not required. | Class | Create when | Deadline and lifetime | |---|---|---| -| Development | A multi-step development operation affects live systems/data, crosses coordinated actors/environments, or needs nontrivial decisions, interruption recovery or rollback. Examples: cutover, staged migration, coordinated release. | Reviewed and rehearsed to the agreed risk level before the operation; retain evidence, then archive if no longer needed. | -| System | Successful use, operation or recovery depends on a recurring or high-consequence procedure the delivered system does not fully perform itself. Examples: onboarding with decisions, import recovery, backup restoration. | Included in delivery acceptance; maintained with the system and its interfaces. | +| Development | A multi-step development or publishing operation affects live systems/data, crosses coordinated actors/environments, or needs nontrivial decisions, interruption recovery or rollback. Examples: cutover, staged migration, coordinated release or coordinated publication. | Reviewed and rehearsed to the agreed risk level before the operation; retain evidence, then archive if no longer needed. | +| System | Successful use, operation or recovery depends on a recurring or high-consequence procedure the delivered system or publication does not fully perform itself. Examples: onboarding with decisions, import recovery, backup restoration. | Included in delivery acceptance; maintained with the system and its interfaces. | A simple reversible edit, self-explanatory action, fully automated operation with adequate built-in handling, or ordinary task sequence does not by itself @@ -36,31 +36,18 @@ Follow an existing repository convention. Otherwise use review and rehearsal evidence beside them as `-review.md`. These are output paths in the target project, not files inside the plugin installation. -## Lifecycle integration - -- `speckit-specify`: identify system-deliverable playbooks from user and operating - scenarios, including preventive recovery. Record scope and acceptance criteria. -- `speckit-plan` and design-time `architecture-modeling`: assess development - operations and refine system needs against dependencies and failure modes. - Material additions to delivery scope return to the specification owner. -- `openspec-propose`: perform both assessments in proposal/delta and design; - include affected existing playbooks and their compatibility changes. -- `speckit-tasks` or OpenSpec tasks: add authoring, review and required rehearsal - tasks with explicit dependencies. Development readiness blocks the operation; - system readiness blocks delivery. Ordinary task planning remains unchanged. -- `orchestrated-implementation` and `openspec-apply`: invoke `playbook-authoring` - for assigned artifacts and `playbook-review` before use/acceptance. Track fixes - in the same work ID. Coordinate authorized rehearsals and preserve evidence. -- As-built `architecture-modeling`: check playbook assumptions against actual - interfaces and relevant recovery flows; flag stale evidence for affected paths. -- `speckit-converge` and `openspec-archive`: check every required playbook against - the need inventory, current artifact/system revision, review and required - rehearsal evidence. Missing or stale proof blocks completion. Return findings - to the existing executor; do not execute or repair procedures in the gate. - -Direct authoring/review requests use the supporting skill without creating an -engineering lifecycle solely for a document. If the request changes system -behavior, the appropriate engineering lifecycle owns that change. +## Method integration + +The invoking method owns the need decision, tasks, review, rehearsal and +acceptance. Engineering operations can include migrations, release or recovery; +writing operations can include publication, PDF production or recovery from a +failed export. Use the same scenario-bound template and evidence contract. + +Method-specific phase hooks live in the consuming method's policies. They may +require playbooks for a concrete risk; shared support never requires an absent +engineering or writing lifecycle. Ordinary authoring, a simple export or a +reversible edit does not justify a playbook by itself. Direct authoring/review +requests use the supporting skill without inventing another lifecycle. ## Evidence and acceptance diff --git a/shared/policies/reader-oriented-output.md b/shared/policies/reader-oriented-output.md deleted file mode 100644 index 2e34456..0000000 --- a/shared/policies/reader-oriented-output.md +++ /dev/null @@ -1,35 +0,0 @@ -# Reader-Oriented Output - -The didactic writing skills are not limited to documentation projects. They -govern how any explanation, instruction or troubleshooting help is written for -a reader who lacks the writer's context, including ordinary replies, commit -and pull-request descriptions, review comments, handoff notes and error -reports. Apply them by default; skip them only when the reader has explicitly -asked for terse expert output or the text is machine-consumed. - -## Which rules apply to which reply - -| The reply is mainly | Apply | Not | -|---|---|---| -| Explaining why or how something works to someone who does not already know it | `explaining-concepts`: an everyday analogy before the mechanism, no undefined jargon, one idea per sentence, the analogy's limits stated | A textbook-length detour; an analogy for a term the reader already uses correctly | -| Telling the reader what to do next: install, configure, run, click, review | `writing-procedures`: numbered imperative steps, one action each, exact locations named, three to five steps per block, a visible result to confirm success | Passive descriptions of where something happens; a wall of twelve unnumbered steps | -| Helping with something that went wrong or might go wrong | `empathic-troubleshooting`: start from what the reader sees, name the likely cause, give the first check, then the fix, in order of probability and cost | A table of error codes without the reader's symptom; blame or hedging language | -| A pass, fix, or completion claim | `verification-before-completion` | Reader-oriented tone replacing evidence | - -The curse-of-knowledge filter in -[shared/writing/curse-of-knowledge-filter.md](../writing/curse-of-knowledge-filter.md) -applies to all three: write out the step the expert would skip, name the place -where the reader has to look, and define or avoid every term the reader might -not share. - -## Boundaries - -- These rules shape wording and order. They never replace the evidence a claim - needs, remove required detail, or add filler. A shorter, exact reply is still - the goal. -- Terminology follows the project's glossary when one exists. In a project - without a glossary, keep one term per concept within the reply and reuse the - term the reader used. -- The reader's language decides the reply language; repository artifacts stay - in the project's documented language. -- Host adapters may point to this policy; they do not add host syntax to it. diff --git a/shared/policies/workflow-depth.md b/shared/policies/workflow-depth.md index fe09f1f..b8eba00 100644 --- a/shared/policies/workflow-depth.md +++ b/shared/policies/workflow-depth.md @@ -17,7 +17,5 @@ Do not add lifecycle artifacts merely because tools are available. Add depth when current evidence crosses a boundary above, and record the reason in the owning artifact. -Reader-facing documentation has its own scale table in -[writing-depth](writing-depth.md); the [reader-oriented output -policy](reader-oriented-output.md) governs explanations, instructions and -troubleshooting help in ordinary replies. +Reader-facing documentation belongs to the optional writing-method companion. +Assess operation and system playbooks using `shared/policies/engineering-playbooks.md`. diff --git a/shared/policies/writing-depth.md b/shared/policies/writing-depth.md deleted file mode 100644 index 528fd4e..0000000 --- a/shared/policies/writing-depth.md +++ /dev/null @@ -1,56 +0,0 @@ -# Writing Depth - -Prose deliverables follow the same rule as code: match the workflow to the -observable size, audience risk and lifetime of the text. Decide the scale first, -record it, and select the writing lifecycle from that decision. Do not adopt -documentation-set machinery for a paragraph, and do not write a manual one -chapter at a time without a plan. - -Apply [proportionality](proportionality.md) at every scale. Depth describes the -evidence and structure a reader needs, not an unlimited writing budget. - -## Scale decision - -Estimate from the request and existing material, then confirm by inspecting the -target repository or document tree read-only. Record the chosen scale and its -evidence in the owning artifact or, for small work, in the reply. - -| Observable conditions (any one moves the work to that scale) | Scale | Writing lifecycle | -|---|---|---| -| One sentence, paragraph, or section inside an existing text; wording, correctness or a single explanation; no new document structure; no new terms that other pages must share | Small | Native focused edit; the reader-oriented rules apply inline | -| One self-contained document: a README section set, guide, tutorial, article, report, release note or reference page; one primary audience; expected length up to roughly 3,000 words or 40 procedure steps; no shared glossary or asset plan needed beyond the document | Medium | `documentation-authoring` in standalone mode, with the didactic and structural supporting skills its content type requires | -| Several chapters or documents that must agree on terms, structure and images; more than one audience or reading path; a manual, handbook, course, knowledge base or product documentation set; expected length above roughly 3,000 words, more than five chapters, or contributors and reviews spread over multiple sessions | Large | `documentation-planning` → `documentation-authoring` (per chunk) → `documentation-review` → `verification-before-completion` | - -The word and chapter figures are thresholds for the decision, not targets. When -two conditions disagree, the higher scale wins if the text must stay consistent -over its lifetime; the lower scale wins if the request is reversible and local. -When existing writing artifacts exist under `docs/writing//`, continue -that recorded scale and phase instead of deciding again. - -## Required depth per scale - -| Scale | Required depth | -|---|---| -| Small | Reader-oriented wording, terminology consistent with the surrounding text, focused check of the changed passage and its links; preserve the surrounding voice without loading an additional supporting skill | -| Medium | Content type chosen from the information architecture, one template-based document with frontmatter, explicit reader, prerequisites and validation for procedures, local glossary check, drafting under the `human-prose-drafting` constraints, self-review against the didactic rules, fresh link and rendering check | -| Large | Documentation plan with audience, architecture map, chunk manifest and conventions; shared glossary; asset manifest with placeholders; per-chunk authoring under the `human-prose-drafting` constraints with checkpoints; set-wide consistency review including prose tells; convergence of findings; fresh verification | - -## PDF delivery - -When the user requests a PDF, apply `documentation-pdf` after content review -and before final verification. Use the accepted manifest order for a set, or -the reviewed file for a standalone document. Rendering is local and does not -change the writing scale or add a Humanizer rewrite pass. - -## Escalation between scales - -If a medium document reveals shared terminology, several audiences or a chapter -structure that other documents must mirror, stop extending it. Create the -documentation plan through `documentation-planning`, register the existing -document as its first chunk, and continue at the large scale. Preserve the -written text and its stable identifiers. Never grow a standalone document into -an unplanned manual. - -If a large plan turns out to cover one document, reduce it to standalone mode -explicitly in the plan, keep the glossary if other text uses it, and record the -reason. The scale decision is a checkpoint fact, not a silent assumption. diff --git a/shared/writing/curse-of-knowledge-filter.md b/shared/writing/curse-of-knowledge-filter.md deleted file mode 100644 index 1e62c8e..0000000 --- a/shared/writing/curse-of-knowledge-filter.md +++ /dev/null @@ -1,45 +0,0 @@ -# Curse-of-Knowledge Filter - -Once you know something, it becomes hard to imagine not knowing it. The result -in writing is skipped steps, unexplained terms and locations the reader cannot -find. Run this filter over every explanation and procedure before handing it -over. It is a rewrite pass, not a style preference. - -## Filter questions - -For each sentence that asks the reader to know, find or do something: - -1. **Skipped step.** Would a first-time reader have to do or decide something - between this step and the next? Write it out. "Open Settings" becomes - "Select the gear icon in the top-right corner to open Settings." -2. **Unlocated object.** Does the sentence name a button, menu, file, field, - command or page without saying where it is? Add the location, the path, or - the exact label as the reader sees it, in the reader's interface language. -3. **Unshared term.** Does the sentence use a term, abbreviation or product - name the target audience may not use in the same sense? Replace it with the - glossary term, define it at first use, or remove it. -4. **Assumed state.** Does the step only work if something was already - installed, enabled, logged in, selected or saved? Move that condition into - the prerequisites or state it in the step. -5. **Invisible result.** After the reader acts, what should they see? If the - text does not say, add the observable result so the reader knows it worked. -6. **Expert shortcut.** Does the text rely on a keyboard shortcut, alias, - jargon or a "simply" or "just" that hides difficulty? Give the full path - first; the shortcut is optional information. - -## Audience calibration - -Define the reader once, at the top of the document or plan: role, what they -already know, what they are trying to achieve, and which interface or version -they use. Judge every filter question against that reader, not against -yourself or a colleague. When the audience is mixed, write for the least -experienced reader who is expected to succeed and give experts a way to skip -ahead, such as a short summary or a reference table. - -## Evidence for the pass - -The filter is complete when a sample of the text was read as the defined -reader, each finding was rewritten, and the terms, locations and prerequisites -added are consistent with the glossary and the rest of the document. Record -that the pass was made in the chunk frontmatter or the review report; do not -claim it from intent. diff --git a/skills/documentation-authoring/SKILL.md b/skills/documentation-authoring/SKILL.md deleted file mode 100644 index 9750ee9..0000000 --- a/skills/documentation-authoring/SKILL.md +++ /dev/null @@ -1,179 +0,0 @@ ---- -name: documentation-authoring -description: "Use when reader-facing documentation must be written or revised: one standalone document, or chunks of a planned documentation set with a plan under docs/writing. Applies the content-type skeletons, chunk frontmatter, didactic writing skills, glossary and placeholder conventions. Not for a wording fix inside existing text, for planning a multi-document set (use documentation-planning), or for software specifications." ---- - -# Documentation Authoring - -Apply the shared [proportionality rule](../../shared/policies/proportionality.md) -before adding work, delegating, or repeating verification. - -Write the text readers will use. In a documentation set, author chunks -according to the plan; for a standalone document, apply the same content-type -discipline without the set-level machinery. - -## Recovery preamble - -Before creating or updating an artifact: - -1. Invoke `project-backlog` for read-only discovery: discover an active run - for the stable work ID before requesting agent status. Only a verified absent - run may enroll in the new-run-only coordinator-only mode described there. -2. For an existing ordinary run, obtain host-observed live agent IDs through - the platform capability seam and call `continuity-state recover --live-agents`. - Use an explicit empty observation only when the host confirms none are live. - With no observation, only verified coordinator-only provenance permits - `continuity-state recover --coordinator-only`; saved or uncertain agent - activity remains blocked. Never fabricate observed IDs. -3. Complete recovery, or verified absent-run initialization, before any canonical - or backlog mutation. The coordinator-only mode permits sequential continuity - across phase handoffs, not delegation or bypass of independent-review gates. -4. Read the run's `state.json` and `resume.md` when a run exists. -5. Check recorded commits, worktree, artifacts, and canonical backlog or issue - state against current reality. -6. Reconcile saved agent identities with agents still available from the host; - coordinator-only recovery must verify that no saved agent history exists. -7. Preserve validated completed work and never redispatch completed work after - compaction or resumption. -8. Reconstruct stale state from git and canonical artifacts when they disagree. -9. Continue from the validated next action. - -Repository evidence wins over stale checkpoint or memory data. Never silently -restart or reclassify an active workflow. - -## Operational state handoffs - -Follow the [transition-to-event ordering -contract](../project-backlog/SKILL.md#transition-to-event-ordering): - -1. After each durable transition, invoke `project-backlog` to call - `continuity-state event` with the applicable event and its concise facts. -2. Then call `continuity-state checkpoint` with current state and the exact next - action, except where the dispatch or completion protocol requires two - checkpoints. -3. Event emission is never automatic. Claim it only after the event call - succeeds, and likewise verify every checkpoint call. - -Apply this protocol while updating backlog state and the run checkpoint at work -start, scope change, blocker discovery, each completed slice, and every phase or -final handoff. - -In standalone mode the run is optional. When the project backlog does not track -the document under a stable work ID, record the verified-absent discovery -result in the reply, do not initialize a run, and treat the committed document -as the checkpoint. A documentation set always has a run. - -## Trigger - -Use when the [writing-depth policy](../../shared/policies/writing-depth.md) -places the work at the medium scale (one self-contained document), or when a -documentation plan exists and manifest rows are planned or returned with review -findings. - -An accepted plan is an input to authoring, not a reason to activate -`documentation-planning` again as a supporting skill. Return to planning only -when the requested work changes the set structure, reader scope or manifest; -ordinary continuation follows the existing plan directly. - -## Do not use for - -- Changing a sentence, paragraph or section of existing text without new - structure or shared terms; use a native focused edit. -- A documentation set without a plan; invoke `documentation-planning` first. -- Specifications, plans or architecture documents that belong to an - engineering lifecycle. -- Set-wide consistency review; that is `documentation-review`. - -## Consumes - -- Standalone mode: the request, the defined reader, the subject and version - to describe, any existing style guide or glossary. -- Set mode: `docs/writing//plan.md`, `glossary.md`, `assets.md`, the - manifest rows assigned to this session, and any open findings in - `docs/writing//review.md`. -- The current subject: interface, product, code or process the text describes, - inspected directly rather than remembered. - -## Produces - -- One Markdown file per chunk under the content root named in the plan, or one - standalone document at the requested path, each starting with the frontmatter - of the installed [chunk template](../../templates/documentation/chunk.md). -- Manifest status updates in `plan.md`, new glossary entries through - `terminology-guard`, and new asset rows through `visual-placeholders`. -- For a standalone document with more than a handful of recurring terms, a - glossary section or definition list inside the document. - -## Workflow - -1. Read the plan or, in standalone mode, define the reader, the content type - and the version described at the top of the document. -2. Take one chunk at a time in manifest order. Re-read its dependencies from - disk before writing; do not write from memory of an earlier session. -3. Draft with the type skeleton from the chunk template and the matching - skill: `explaining-concepts` for concept chunks and for the purpose - paragraph of any other type; `writing-procedures` for task and tutorial - chunks, with blocks of three to five steps and a validation section; - `empathic-troubleshooting` for troubleshooting chunks; consistent tables - for reference chunks. Before writing the first sentence, read - [human-prose-drafting](../human-prose-drafting/SKILL.md) and apply its - guidance while drafting: direct statements, concrete facts, natural - rhythm and useful formatting. Preserve its exceptions for source fidelity, - required structure and technical terms. These constraints apply while writing; a - separate humanizing pass afterwards is not part of this lifecycle. -4. Keep one content type per chunk. When a procedure needs explanation, link - the concept chunk; when a concept needs steps, link the task chunk. -5. Check facts against the subject: run or replay commands, open the interface, - read the code. Record the version or revision in the frontmatter. -6. Run the [curse-of-knowledge filter](../../shared/writing/curse-of-knowledge-filter.md), - the `human-prose-drafting` chunk check and the `terminology-guard` - consistency check on the chunk; insert `visual-placeholders` callouts - where an image confirms a state. -7. Mark the manifest row drafted, checkpoint, and continue with the next - chunk. Stop at a section boundary when the plan calls for a section review. - -Write in the documentation language recorded in the plan. Reader-facing text -follows the reader; repository artifacts such as the plan follow the project's -documented language. - -## Completion - -A chunk is complete when its frontmatter is filled, its body follows the type -skeleton, task blocks have three to five imperative steps and an observable -validation, every term passes the glossary check, the prose passes the -`human-prose-drafting` chunk check, every image has a registered placeholder, -cross-references resolve, and the described facts were checked against the -current subject. Standalone documents are complete when the same -holds for the single file and its links render. - -## Next phase - -`documentation-review` - -For a standalone document, the review is a self-review against the review -template's checks recorded in the reply, followed by -`verification-before-completion`. - -If the requested deliverable includes a PDF, invoke -[documentation-pdf](../documentation-pdf/SKILL.md) after the content review is -accepted and before final artifact verification. Export is optional for other -deliverables and does not introduce a new prose-editing phase. - -## Supporting skills - -- `project-backlog` for recovery, canonical task state, events, and checkpoints. -- `explaining-concepts`, `writing-procedures` and `empathic-troubleshooting` - for the text of each content type. -- `human-prose-drafting` for the sentence-level constraints of every draft. -- `terminology-guard` and `visual-placeholders` for glossary and assets. -- `dispatching-parallel-agents` only for chunks with disjoint files, a stable - glossary and no cross-dependency; the coordinator owns the manifest. -- `verification-before-completion` for fresh rendering and link checks. - -## Escalation - -If a standalone document reveals several readers, shared terminology with -other documents or a chapter structure others must mirror, stop extending it. -Record the finding, invoke `documentation-planning`, register the document as -the first manifest row, and continue in set mode. Preserve the written text -and its IDs. diff --git a/skills/documentation-pdf/SKILL.md b/skills/documentation-pdf/SKILL.md deleted file mode 100644 index 7b5b9e9..0000000 --- a/skills/documentation-pdf/SKILL.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -name: documentation-pdf -description: "Use when existing Markdown documentation must become one local PDF with a reusable design, table of contents and page numbers. Supports a standalone document or an accepted documentation set. Not for drafting prose, reviewing content, deploying a website or publishing remotely." ---- - -# Documentation PDF - -Apply the shared [proportionality rule](../../shared/policies/proportionality.md). -Render the reviewed Markdown with Quarto and its bundled Typst engine. Keep -Humanizer guidance in authoring; PDF export does not rewrite the text. - -## Inputs and template - -- A reviewed document or the accepted chunk manifest in `docs/writing//plan.md`. -- Documentation language, title, output path and any brand requirements. -- The bundled [book configuration](../../templates/documentation/pdf/_quarto.yml), - [brand](../../templates/documentation/pdf/_brand.yml) and - [design guide](../../templates/documentation/pdf/DESIGN.md). - -Resolve template resources relative to this skill, never the invoking cwd. -Read the design guide before configuring the output. Use Quarto 1.10.18 for the -verified baseline; inspect `quarto --version` and `quarto typst --version`. -Quarto is an external export dependency, not bundled in the plugin. Install -from the official release only when needed and verify its published checksum. -Rendering is local; no online Typst account or document upload is needed. - -## Prepare the book - -1. For an existing project, preserve its configuration and make the smallest - change. For a new one, copy the complete template directory into the chosen - documentation root. Omit `_book/`, `.quarto/` and generated top-level `.typ` - files if copying from a checkout that has already been rendered; retain the - extension's `.typ` sources. Never overwrite existing files when copying. -2. Set title, subtitle, language and output name in `_quarto.yml`. Configure - colors and fonts in `_brand.yml`; the Typst layout lives in the extension. -3. Replace the example chapter list with the accepted manifest files in their - recorded row order. Include each selected chunk exactly once, omit - superseded rows and do not sort by filename. Reconcile missing or duplicate - files before rendering. Record the manifest revision in the export evidence. - For a standalone text, list that text after the book's `index.md` introduction. -4. Paths in `book.chapters` are relative to the Quarto project root. Keep the - Markdown sources and local images in that tree, retaining their relative - relationships. Preserve chunk frontmatter; rendering options belong in the - project configuration. Give chapters stable heading IDs and use Quarto - cross-references for links that must work inside the PDF. -5. Replace sample title and chapter content before delivering a real document. - Resolve image placeholders before calling the PDF final; a requested preview - may retain them only when clearly labeled as a draft. Do not enable code - execution, remote images or remote includes as a side effect of export. - -## Render and verify - -From the book directory run `quarto render --to em-manual-typst`. The default -output is `_book/manual.pdf`; a different `book.output-file` changes that name. -Keep generated output and `.quarto/` out of the source repository. - -Check the actual PDF, not only the renderer's exit code: - -- Every selected chapter appears once, in manifest order. -- The cover is visually separate from the contents and has no running footer. -- The table of contents is clickable and its page references match the chapters. -- Page numbers and the total in the footer are correct, including the final page. -- Cross-references and images resolve; long tables and code fit within margins. -- Inspect representative rendered pages for clipping, isolated headings, broken - callouts, missing glyphs, excessive line length and usable contrast. Confirm - that chapter rules use the configured dark accent. Check each page in a short - book. -- Compare the source files before and after rendering; export must not change - prose, facts or chunk metadata. - -Use `pdfinfo`, `pdftotext` and page images when available. Record tool versions, -command, source revision, output path, checks and remaining limitations in the -existing review or verification record. Return a clickable local PDF link. - -## Boundaries - -Rendering does not grant content acceptance or deployment approval. Return -content defects to `documentation-authoring`; fix layout in the template. -Do not run GitHub migration, `backlog state-check`, remote publication or a -second prose-humanizing phase during PDF export. Finish with -`verification-before-completion` after inspecting the rendered artifact. diff --git a/skills/documentation-planning/SKILL.md b/skills/documentation-planning/SKILL.md deleted file mode 100644 index f7cf7d0..0000000 --- a/skills/documentation-planning/SKILL.md +++ /dev/null @@ -1,168 +0,0 @@ ---- -name: documentation-planning -description: "Use when a documentation set needs an initial plan or an explicit structural re-plan: a manual, handbook, course, knowledge base, or several documents that must share terms, structure, readers and images. Decides the writing scale, then produces the documentation plan, chunk manifest, glossary and asset manifest. Not for drafting from an existing accepted plan (use documentation-authoring), one standalone document, a wording fix, or software specification." ---- - -# Documentation Planning - -Apply the shared [proportionality rule](../../shared/policies/proportionality.md) -before adding work, delegating, or repeating verification. - -Decide how large the writing project is before writing, record that decision, -and give the authors one plan they can follow chunk by chunk across many -sessions without losing consistency. - -## Recovery preamble - -Before creating or updating an artifact: - -1. Invoke `project-backlog` for read-only discovery: discover an active run - for the stable work ID before requesting agent status. Only a verified absent - run may enroll in the new-run-only coordinator-only mode described there. -2. For an existing ordinary run, obtain host-observed live agent IDs through - the platform capability seam and call `continuity-state recover --live-agents`. - Use an explicit empty observation only when the host confirms none are live. - With no observation, only verified coordinator-only provenance permits - `continuity-state recover --coordinator-only`; saved or uncertain agent - activity remains blocked. Never fabricate observed IDs. -3. Complete recovery, or verified absent-run initialization, before any canonical - or backlog mutation. The coordinator-only mode permits sequential continuity - across phase handoffs, not delegation or bypass of independent-review gates. -4. Read the run's `state.json` and `resume.md` when a run exists. -5. Check recorded commits, worktree, artifacts, and canonical backlog or issue - state against current reality. -6. Reconcile saved agent identities with agents still available from the host; - coordinator-only recovery must verify that no saved agent history exists. -7. Preserve validated completed work and never redispatch completed work after - compaction or resumption. -8. Reconstruct stale state from git and canonical artifacts when they disagree. -9. Continue from the validated next action. - -Repository evidence wins over stale checkpoint or memory data. Never silently -restart or reclassify an active workflow. - -## Operational state handoffs - -Follow the [transition-to-event ordering -contract](../project-backlog/SKILL.md#transition-to-event-ordering): - -1. After each durable transition, invoke `project-backlog` to call - `continuity-state event` with the applicable event and its concise facts. -2. Then call `continuity-state checkpoint` with current state and the exact next - action, except where the dispatch or completion protocol requires two - checkpoints. -3. Event emission is never automatic. Claim it only after the event call - succeeds, and likewise verify every checkpoint call. - -Apply this protocol while updating backlog state and the run checkpoint at work -start, scope change, blocker discovery, each completed slice, and every phase or -final handoff. - -## Trigger - -Use when the [writing-depth policy](../../shared/policies/writing-depth.md) -places the work at the large scale: several chapters or documents, more than -one reader group or reading path, shared terminology and images, or authoring -spread over several sessions or contributors. Also use when a standalone -document escalates to a set. - -## Do not use for - -- One self-contained document with one reader group; use - `documentation-authoring` in standalone mode. -- A sentence, paragraph or section fix; use a native focused edit with the - reader-oriented rules. -- Specifying, planning or documenting software behavior for engineers; that is - the Spec Kit or OpenSpec lifecycle. This skill plans reader-facing text. -- Producing chapter text; that is `documentation-authoring`. - -## Consumes - -- The request: subject, readers, purpose, delivery format, language, deadline - and constraints. -- Existing material: current documents, interface, product or code the text - describes, style guides, glossaries, brand or legal requirements. -- Any existing `docs/writing//` artifacts for the same stable - documentation ID. - -## Produces - -Create one kebab-case `` directory containing: - -- `docs/writing//plan.md` from the installed - [plan template](../../templates/documentation/plan.md): scale decision with - evidence, readers, information architecture, chunk manifest, conventions, - acceptance criteria and out-of-scope list. -- `docs/writing//glossary.md` from the - [glossary template](../../templates/documentation/glossary.md), seeded with - every term the manifest titles and reader goals already use. -- `docs/writing//assets.md` from the - [asset manifest template](../../templates/documentation/assets.md), listing - the images the plan already knows it needs. - -The plan names the content root where chunk files will live; this skill does -not create the chunk files. - -## Workflow - -1. Resolve one stable documentation ID. If it exists, continue the recorded - plan and phase rather than planning again. -2. Inspect the subject read-only: the interface, product version, code paths, - existing documents and any glossary. Record what the text will describe - and which version. -3. Decide the scale with the writing-depth table and record the evidence. If - the evidence shows one document, hand over to `documentation-authoring` in - standalone mode and stop. -4. Define the readers. Name the least experienced reader expected to succeed - and what each reader wants to achieve. Reader goals drive the manifest. -5. Build the information architecture. Assign each planned chunk exactly one - content type: concept, task, tutorial, reference or troubleshooting. Types - classify chunks; they are not the navigation. Arrange sections by reader - journey and keep each level internally consistent. -6. Write the chunk manifest. One row per Markdown file, stable IDs, type, - readers, dependencies, assets and status. Each chunk must make sense on its - own; chunks link to each other rather than repeating content. -7. Fix conventions: frontmatter fields, file naming, heading levels, step - block rules, placeholder syntax, cross-reference style, documentation - language. Invoke `terminology-guard` to seed the glossary and - `visual-placeholders` to record known assets. -8. Define acceptance: which reader goals must have a complete path, which - findings block acceptance, when set-wide review runs. -9. Verify the artifacts against the completion condition and hand over. - -## Modular chunking - -Large sets are written as one file per chunk, never as one growing document. -Each chunk carries the frontmatter from the -[chunk template](../../templates/documentation/chunk.md), so that any chunk can -be authored, reviewed, reordered, translated or regenerated independently, -and so that a new session can resume from the manifest without rereading the -whole set. Order lives in the manifest and in navigation files, not in file -names or IDs. - -## Completion - -The plan is ready when the scale decision and its evidence are recorded, every -reader has a goal and a path through the manifest, every manifest row has one -type and stable ID, conventions are complete enough that two authors would -produce interchangeable chunks, the glossary and asset manifest exist, and -acceptance criteria are observable. - -## Next phase - -`documentation-authoring` - -## Supporting skills - -- `project-backlog` for recovery, canonical task state, events, and checkpoints. -- `terminology-guard` for seeding and owning the glossary. -- `visual-placeholders` for the asset manifest conventions. -- `verification-before-completion` for fresh artifact checks. - -## Planning boundary - -This phase writes plan, glossary and manifest artifacts only. It must not -draft chapter text. After verifying the artifacts, return control to the -coordinator. When the original request authorizes end-to-end writing, the -coordinator continues with `documentation-authoring` without a new request -unless a material decision, blocker, or authority boundary requires user input. diff --git a/skills/documentation-review/SKILL.md b/skills/documentation-review/SKILL.md deleted file mode 100644 index 36e9c4f..0000000 --- a/skills/documentation-review/SKILL.md +++ /dev/null @@ -1,152 +0,0 @@ ---- -name: documentation-review -description: "Use when drafted chunks of a documentation set under docs/writing must be checked for set-wide consistency before acceptance: frontmatter against the manifest, one content type per chunk, step-block and validation rules, terminology, curse-of-knowledge gaps, placeholders and cross-references. Not for code review, for reviewing a single standalone document, or for writing corrections." ---- - -# Documentation Review - -Apply the shared [proportionality rule](../../shared/policies/proportionality.md) -before adding work, delegating, or repeating verification. - -Read the set as its least experienced reader and as its glossary owner. Record -findings with evidence, and return actionable findings to the author with the -text they must change, not with a verdict alone. - -## Recovery preamble - -Before creating or updating an artifact: - -1. Invoke `project-backlog` for read-only discovery: discover an active run - for the stable work ID before requesting agent status. Only a verified absent - run may enroll in the new-run-only coordinator-only mode described there. -2. For an existing ordinary run, obtain host-observed live agent IDs through - the platform capability seam and call `continuity-state recover --live-agents`. - Use an explicit empty observation only when the host confirms none are live. - With no observation, only verified coordinator-only provenance permits - `continuity-state recover --coordinator-only`; saved or uncertain agent - activity remains blocked. Never fabricate observed IDs. -3. Complete recovery, or verified absent-run initialization, before any canonical - or backlog mutation. The coordinator-only mode permits sequential continuity - across phase handoffs, not delegation or bypass of independent-review gates. -4. Read the run's `state.json` and `resume.md` when a run exists. -5. Check recorded commits, worktree, artifacts, and canonical backlog or issue - state against current reality. -6. Reconcile saved agent identities with agents still available from the host; - coordinator-only recovery must verify that no saved agent history exists. -7. Preserve validated completed work and never redispatch completed work after - compaction or resumption. -8. Reconstruct stale state from git and canonical artifacts when they disagree. -9. Continue from the validated next action. - -Repository evidence wins over stale checkpoint or memory data. Never silently -restart or reclassify an active workflow. - -## Operational state handoffs - -Follow the [transition-to-event ordering -contract](../project-backlog/SKILL.md#transition-to-event-ordering): - -1. After each durable transition, invoke `project-backlog` to call - `continuity-state event` with the applicable event and its concise facts. -2. Then call `continuity-state checkpoint` with current state and the exact next - action, except where the dispatch or completion protocol requires two - checkpoints. -3. Event emission is never automatic. Claim it only after the event call - succeeds, and likewise verify every checkpoint call. - -Apply this protocol while updating backlog state and the run checkpoint at work -start, scope change, blocker discovery, each completed slice, and every phase or -final handoff. - -## Trigger - -Use when all manifest rows of a section, or of the whole set, are drafted, and -before any chunk is marked accepted. Also use after a glossary or interface -change that affects already drafted chunks. - -## Do not use for - -- Code or engineering artifacts; use `requesting-code-review`. -- A standalone document; `documentation-authoring` performs a recorded - self-review with the same checks. -- Making the corrections; findings return to `documentation-authoring`. - -## Consumes - -- `docs/writing//plan.md`, `glossary.md`, `assets.md`. -- Every chunk file in the review scope at a named revision. -- Prior `docs/writing//review.md` findings and their dispositions. - -## Produces - -- `docs/writing//review.md` from the installed - [review template](../../templates/documentation/review.md), with the reviewed - revision, each check's method and result, findings with stable IDs, chunk, - severity, quoted evidence and required change, and a verdict. -- Manifest status updates: reviewed for chunks without open Critical or - Important findings, otherwise unchanged with the finding IDs noted. - -## Checks - -Run every row of the review template against the actual files, using search -on the text rather than recollection: - -1. Frontmatter fields present and consistent with the manifest row. -2. One content type per chunk; headings match the type skeleton. -3. Task and tutorial chunks: goal, prerequisites, step blocks of three to - five imperative single-action steps, an observable result per block, a - validation section. -4. Terminology through the `terminology-guard` consistency check across the - whole scope, not chunk by chunk in isolation. -5. Curse-of-knowledge sample: read at least one chunk per type as the defined - least experienced reader and record skipped steps, unlocated objects, - unshared terms and assumed state. -6. Placeholders: every callout registered in the asset manifest with capture - instructions; every manifest row referenced from a chunk. -7. Cross-references: every relative link and chunk ID resolves; no "see above". -8. Troubleshooting chunks: symptom first, causes ordered, first check, fix, - confirmation, escalation. -9. Read [human-prose-drafting](../human-prose-drafting/SKILL.md) and assess - passages for staged contrasts, empty closers, dash chains, inflated wording - and chatbot residue. Apply its context and preservation exceptions; a - word match alone is not a finding. Return specific prose findings to the - author within the existing review cycle; add no separate rewrite phase. - -Independence: a set-wide acceptance review is performed by a reviewer who did -not draft the reviewed chunks when the host can provide one; otherwise record -that the review was a coordinator self-review and its limits. - -## Completion - -The review is complete when every check has a recorded method and result at -the named revision, every finding has evidence and a required change, and the -verdict states the count of open Critical and Important findings. Acceptance -of the scope requires zero open Critical or Important findings. - -## Next phase - -`verification-before-completion` when the verdict is Ready. Otherwise return -the findings to `documentation-authoring` as new work for the affected chunks; -that return preserves accepted chunks and stable IDs and is not a new plan. - -If the requested deliverable includes a PDF, invoke -[documentation-pdf](../documentation-pdf/SKILL.md) after the content review is -accepted and before final artifact verification. Export is optional for other -deliverables and does not introduce a new prose-editing phase. - -## Supporting skills - -- `project-backlog` for recovery, canonical task state, events, and checkpoints. -- `terminology-guard` for the set-wide term check. -- `human-prose-drafting` for the prose-tell check. -- `receiving-code-review` for evaluating disputed findings against the text. -- `verification-before-completion` for the final fresh check. - -## Common mistakes - -- Reviewing chunk by chunk and never reading a reader's whole path. -- Reporting "inconsistent terminology" without the term, the chunk and the - replacement. -- Accepting a set with placeholders that no one could capture from the - instructions. -- Treating a rendered page without errors as proof that the reader can succeed. diff --git a/skills/empathic-troubleshooting/SKILL.md b/skills/empathic-troubleshooting/SKILL.md deleted file mode 100644 index a737dca..0000000 --- a/skills/empathic-troubleshooting/SKILL.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -name: empathic-troubleshooting -description: "Use when writing help for something that has gone wrong or may go wrong, in documentation or an ordinary reply: start from what the reader sees, name likely causes in order, give the first check, then the fix and its confirmation. Not for diagnosing a defect in code you own (use systematic-debugging), for normal procedures, or for reference lists of error codes." ---- - -# Empathic Troubleshooting - -Apply the shared [proportionality rule](../../shared/policies/proportionality.md) -before adding work, delegating, or repeating verification. - -The reader arrives with a symptom, not an error code, and often under time -pressure. Troubleshooting text meets them at the symptom, tells them the most -likely reason in plain words, and leads them through the cheapest check first. - -## Trigger - -Use for troubleshooting chunks, "if this does not work" paragraphs after a -procedure, FAQ entries about failures, support macros, and replies where the -user reports that something is not working for them. - -## Do not use for - -- Finding the root cause of a defect in a system you can inspect; that is - `systematic-debugging`. This skill writes the reader-facing help once causes - are known. -- Ordinary procedures where nothing has failed; use `writing-procedures`. -- Machine-readable error catalogs. A code table may exist as reference, but - the troubleshooting text is organized by what the reader experiences. - -## Entry pattern - -Each troubleshooting entry follows this order: - -1. **What you see.** The symptom in the reader's words and observable terms: - "The screen stays black after you sign in", not "Authentication callback - fails." Include the exact message text if the reader will see one. -2. **What it usually means.** The most common cause first, stated plainly, - with a reassuring frame where honest: how common it is, whether data is - at risk. -3. **Check this first.** The cheapest and most likely check, as one to three - imperative steps with the result that tells the reader which cause applies. -4. **Fix.** Steps for each confirmed cause, using the `writing-procedures` - rules. Order causes by probability and then by cost to check. -5. **Confirm it is resolved.** The observable result that shows the problem - is gone. -6. **If it is still not working.** Where to get help and exactly what to - include: version, the message, what was already tried. - -## Tone rules - -- Address the reader directly and never assign blame: "the password was - entered differently" rather than "you typed it wrong". -- State uncertainty honestly and usefully: "most often", "in rare cases", - never "should work". -- Use the glossary term and the exact interface label; the reader will search - for what they see. -- Keep the whole entry scannable: a reader in trouble reads headings and the - first line of each section. -- Do not hide the fix behind an explanation. A one-sentence cause is enough; - link to a concept chunk for the rest. - -## Organizing many entries - -Group entries by the situation the reader is in, such as "signing in", -"during installation", "after an update", and order them by frequency. Give -each entry a stable ID and a symptom-based title. Apply the -[curse-of-knowledge filter](../../shared/writing/curse-of-knowledge-filter.md) -to each check and fix: the expert's mental shortcut is exactly what the -troubled reader lacks. - -## Completion - -An entry is complete when it opens with the reader's symptom, orders causes by -likelihood and cost, gives a first check with a decisive result, provides a -fix and a confirmation for each cause, and tells the reader how to escalate -with the right information. Where a cause was established by -`systematic-debugging`, link that evidence in the chunk metadata rather than -repeating internals in the reader's text. - -## Common mistakes - -- Titling entries by internal cause or error code instead of the symptom. -- Listing every possible cause with equal weight. -- Explaining the architecture before offering the first check. -- Ending with the fix and never telling the reader how to confirm it. -- Phrases that imply the reader is at fault or that the problem is trivial. diff --git a/skills/explaining-concepts/SKILL.md b/skills/explaining-concepts/SKILL.md deleted file mode 100644 index d74ced2..0000000 --- a/skills/explaining-concepts/SKILL.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -name: explaining-concepts -description: "Use when a technical concept, mechanism, or design must be explained to a reader who lacks the writer's expertise, in documentation or an ordinary reply. Introduces each concept with an everyday analogy before the mechanism and removes undefined jargon. Not for step-by-step instructions, reference tables, or error diagnosis." ---- - -# Explaining Concepts - -Apply the shared [proportionality rule](../../shared/policies/proportionality.md) -before adding work, delegating, or repeating verification. - -Explain so that the defined reader could restate the idea in their own words. -This is the Feynman technique applied to writing: if the explanation needs -jargon to stand up, the writer has not understood it well enough yet. - -## Trigger - -Use for concept sections in documentation, the "why" paragraph before a -procedure, architecture or design explanations for non-specialists, onboarding -material, and any reply where the reader asked how or why something works. -The [reader-oriented output policy](../../shared/policies/reader-oriented-output.md) -applies this skill to ordinary replies as well as to documents. - -## Do not use for - -- Procedures and instructions; use `writing-procedures`. -- Symptom-driven help for something that is failing; use `empathic-troubleshooting`. -- Reference material whose value is exactness and completeness, not - understanding. Reference text may link to a concept chunk instead. -- Readers who demonstrably share the vocabulary and asked for the short - expert version. - -## Explanation pattern - -Write each concept in this order. Keep the sections short; a concept chunk is -usually under 600 words. - -1. **One sentence of purpose.** What the concept does for the reader, in the - reader's terms. -2. **Everyday analogy.** One concrete image from ordinary life that shares the - concept's structure. Choose it for structural fit, not for charm. State in - one sentence where the analogy stops being true. -3. **Mechanism.** How it actually works, in the same order the reader would - observe it. Use only glossary terms and terms defined in the previous - sentences. Prefer a small concrete example over a general statement. -4. **Consequence.** What changes for the reader because this is how it works: - what they can rely on, what they must avoid, what to do next. -5. **Related terms.** Link the glossary terms and the neighboring concept, - task or reference chunks. - -## Jargon rule - -Every term in the explanation is one of: a word the defined reader already -uses in this sense, a glossary term introduced before this point, or a term -defined in the sentence where it first appears. Anything else is rewritten or -removed. Abbreviations are expanded at first use. Do not introduce a second -name for something already named. - -Run the [curse-of-knowledge filter](../../shared/writing/curse-of-knowledge-filter.md) -after drafting: the expert's skipped intermediate idea is the most common gap. - -## Self-check - -Before handing over, answer with evidence from the text: - -- Could the reader restate the idea without the analogy? If the analogy is the - only explanation, the mechanism section is missing. -- Does any sentence carry more than one new idea? Split it. -- Is the analogy's limit stated? An unbounded analogy misleads later. -- Would the mechanism paragraph still be true for an expert? Simplification - must not become falsehood; mark deliberate omissions with "for now" or a - link to the reference. - -## Completion - -The explanation is complete when the pattern is present, every term passes the -jargon rule, the analogy's limit is stated, and the text was read once as the -defined reader. In a documentation set, record `last_reviewed` in the chunk -frontmatter only after `documentation-review` confirms it. - -## Common mistakes - -- Starting with history, internals or a definition instead of the reader's - purpose. -- Stacking several analogies; one that fits beats three that half fit. -- Using the analogy in the procedure that follows; procedures use the exact - interface terms. -- Explaining what the writer finds interesting rather than what the reader - needs for their next action. diff --git a/skills/human-prose-drafting/SKILL.md b/skills/human-prose-drafting/SKILL.md deleted file mode 100644 index 34336d6..0000000 --- a/skills/human-prose-drafting/SKILL.md +++ /dev/null @@ -1,158 +0,0 @@ ---- -name: human-prose-drafting -description: "Use within documentation-authoring for medium and large texts to apply Humanizer prose guidance from the first sentence, with a brief per-chunk check. Not a separate rewrite phase or a reason to change facts, code, quotations or required document structure." ---- - -# Human Prose Drafting - -Apply the shared [proportionality rule](../../shared/policies/proportionality.md) -before adding work, delegating, or repeating verification. - -Write for the defined reader and subject from the first sentence. Apply the -patterns below while choosing words and organizing each paragraph. The writing -lifecycle includes a short check of each chunk, with no separate humanizing phase. - -Adapted from blader/humanizer (MIT); patterns trace to Wikipedia's "Signs of AI -writing" maintained by WikiProject AI Cleanup. See the third-party notices. - -## Trigger - -Use inside `documentation-authoring` for every chunk or standalone document at -the medium or large scale, and inside `documentation-review` as one check. -The didactic skills decide what to say and in what order; this skill decides -how the sentences may not be built. - -## Do not use for - -- Code blocks, inline code, commands, paths, YAML frontmatter, data tables, - link targets and quoted material: leave them unchanged. -- Changing claims. A name, number, date, quote, citation or fact comes from - verified source material, never from this skill; when a sentence needs a - missing detail, write a simpler sentence or record the gap. -- Small-scale edits inside existing text that keep the surrounding voice. - -## Two rules while drafting - -1. Give each sentence a purpose for the reader. Omit sentences that only - signal importance, echo a heading or repeat a conclusion. Keep useful - teaching recaps and required warnings. -2. Choose for the defined reader. Vary sentence length as speech does; name - the actor; use the number of items the meaning has; pick the plain word. - -## Constraints by strength - -Use these patterns as contextual writing guidance, not a string blacklist. -The staged rhetoric in group A warrants attention on one occurrence. Weak -signals such as a dash or a three-item list need context before changing them. -User instructions, required templates, glossary terms, source fidelity and -project style take precedence over stylistic preferences here. - -### A. State instead of staging - -- **No "not X but Y".** Also not "not just X, it's Y", "X rather than Y" as a - reveal, or the split form "This does not mean X. It means Y." State the - point. Keep a contrast only when the negative half corrects a belief the - reader actually holds. -- **No one-line closers or fragment rows.** No "That is the real win.", no - sentence-long paragraph that restates the one before, no "No prior. No - nostalgia." Merge fragments into one sentence with a specific claim. -- **No sayings dressed as depth.** Not "at its core", "the real question is", - "what really matters", "X is the language of Y". Write the specific claim. -- **No run-up before the point.** Not "Let's dive in", "Here's what you need - to know", "Honestly?", "Here's the thing". Begin with the point. -- **No arguing with no one.** Not "This isn't about", "To be clear", "A - tempting approach would be", "You might think". Keep an objection only - when the text attributes it or the reader would actually weigh it. - -### B. Rhythm follows meaning - -- **No forced triads.** Three items only when the meaning has three; three - parallel examples plus a lesson is the same tell at paragraph scale. -- **No repeated sentence openings** in a row unless deliberate for rhythm. -- **Avoid dash chains.** Use periods, commas, colons or parentheses when they - make the sentence easier to read. Keep meaningful ranges, names and dashes - required by the project's style. *Weak alone.* -- **No stacked qualifiers.** "could potentially possibly" becomes "may". Keep - scope statements, safety notices and honest uncertainty. *Weak alone.* -- **Hyphenate only where grammar needs it**: "a high-quality report", "the - report is high quality". *Weak alone.* -- **Name the actor.** "You do not need a configuration file", not "No - configuration file needed". Procedures already require this. *Weak alone.* - -### C. Facts without inflation - -- **Avoid the stock words**: actually, additionally, align with, bolstered, - crucial, deep dive, delve, emphasizing, enduring, enhance, fostering, - garner, highlight (verb), interplay, intricate, key (adjective), landscape - (abstract), meticulous, pivotal, quietly, robust (figurative), showcase, - tapestry, testament, underscore (verb), valuable, vibrant. Keep precise - technical senses, glossary terms and interface names. This is a watch list, - not a ban on words that accurately describe the subject. -- **No inflated significance.** Not "marks a pivotal moment", "plays a key - role", "the future looks bright", and no closing send-off paragraph. End on - the last concrete fact. -- **No vague association.** Not "associated with", "in connection with" when - the subject shows the actual relationship; when it does not, keep the vague - wording rather than inventing a role. -- **No shallow -ing riders**: "highlighting", "ensuring", "reflecting", - "showcasing" bolted onto a fact. Keep the fact. -- **No sales language**: boasts, vibrant, rich (figurative), nestled, - renowned, breathtaking, seamless, powerful. State what the thing is. -- **No borrowed authority.** Not "experts believe", not a list of outlets. - Name the source and what it said, or leave the claim out. -- **Use is, are and has.** Not "serves as", "features", "boasts", "offers". - -### D. Formatting carries information - -- **Bold only for interface labels** as `writing-procedures` requires, and - for the first words of a list item when the reader scans by them. No bold - for emphasis, no list where every item is a bold label with a colon and a - sentence that repeats the label. -- **Prefer sentence-case headings** and avoid decorative emojis, arrows and - rules. Preserve required headings, anchors and template title structure. -- **Straight quotation marks** unless the project's style guide says - otherwise. *Weak alone.* - -### E. Nothing left over from the chat - -- **No chatbot residue**: "Great question", "I hope this helps", "Let me - know", "Would you like", "Here is a". Documentation stands on its own. -- **No knowledge-limit disclaimers or guesses.** Not "details are limited in - available sources, it appears". State what the subject shows or leave it - out; never present a guess as a fact. -- **No heading repeated in the first sentence.** -- **No writing about the previous version** except in release notes, - changelogs and migration guides. Describe current behavior. - -## Voice for documentation - -Concept, task, reference and troubleshooting text stays neutral and plain, -addresses the reader as "you", and keeps the project's glossary terms. The -plan or project contract decides the language of the text; the tells above have -equivalents in every language and are treated the same. Do not add opinions, -humor or asides to documentation; those belong to personal writing. - -## Chunk check - -Before marking a chunk drafted, read it once for the five tells that most -often survive drafting: a not-X-but-Y contrast, a one-line closer, a dash, a -triad, a bold label. Assess each in context, including the exceptions below. -Correct unnecessary rhetoric within the chunk; retain useful structure. Confirm the fix dropped no fact, step, warning or -claim. This check is part of authoring the chunk and adds no separate -humanizing stage or extra output artifact. - -## When not to act - -Leave a watched phrase alone inside a quotation, a title, a product or -interface name, or a passage that discusses the phrase rather than uses it. -Keep scope statements, legal and safety notices, and real corrections. A -specific unusual detail, a stated limit or an honest "we do not know" is not a -tell; it is what a person would write. - -## Completion - -A chunk is complete when the contextual check finds no unresolved prose -problem and preserves facts, steps, uncertainty, warnings, glossary terms and -required structure. Record the check in the existing self-review or review -report; update `last_reviewed` only when the full chunk review is complete. -A literal word match alone is not a failure. diff --git a/skills/playbook-authoring/SKILL.md b/skills/playbook-authoring/SKILL.md index e158c1a..e5923ea 100644 --- a/skills/playbook-authoring/SKILL.md +++ b/skills/playbook-authoring/SKILL.md @@ -1,17 +1,17 @@ --- name: playbook-authoring -description: "Create or update a scenario-bound engineering playbook for a development operation or as a system deliverable, after its need is identified or on direct request. Use for decision paths, actions, recovery and verification. Not for generic documentation, task planning, playbook review, or executing the procedure." +description: "Create or update a scenario-bound playbook for a development or publishing operation, or as a recurring-use deliverable, after its need is identified or on direct request. Use for decision paths, actions, recovery and verification. Not for generic documentation, task planning, playbook review, or executing the procedure." --- # Playbook Authoring Apply [proportionality](../../shared/policies/proportionality.md) and the [playbook policy](../../shared/policies/playbooks.md). Support the existing -engineering owner; do not start a competing lifecycle. +method owner; do not start a competing lifecycle. ## Trigger -A required development or system playbook has an authoring task, an existing +A required operation or delivered playbook has an authoring task, an existing procedure changed, review findings require corrections, or the user directly requests a playbook. A planned operation or accepted future usage requirement is sufficient origin evidence; do not wait for an incident. diff --git a/skills/playbook-review/SKILL.md b/skills/playbook-review/SKILL.md index d7d47e3..a69911e 100644 --- a/skills/playbook-review/SKILL.md +++ b/skills/playbook-review/SKILL.md @@ -1,6 +1,6 @@ --- name: playbook-review -description: "Review a drafted or changed engineering playbook for a development operation or system deliverable against its scenario and acceptance requirements. Check decisions, executable steps, failure paths and evidence freshness without hidden context. Not for authoring fixes, general code review, or executing the procedure." +description: "Review a drafted or changed playbook for a development or publishing operation, or a recurring-use deliverable against its scenario and acceptance requirements. Check decisions, executable steps, failure paths and evidence freshness without hidden context. Not for authoring fixes, general code review, or executing the procedure." --- # Playbook Review @@ -19,7 +19,7 @@ authorized read-only inspection; do not invent operational facts or execute step ## Review checks - Is the scenario applicable, with clear use/exclusion conditions and a bounded - target? Is the development-operation or system-delivery obligation satisfied? + target? Is the operation-readiness or delivery obligation satisfied? - Can the intended reader verify prerequisites, obtain inputs and identify the correct environment with the documented access and tools? - Does each decision name an observable condition and an explicit next action? diff --git a/skills/receiving-code-review/SKILL.md b/skills/receiving-code-review/SKILL.md index ccf78b4..96654ae 100644 --- a/skills/receiving-code-review/SKILL.md +++ b/skills/receiving-code-review/SKILL.md @@ -9,14 +9,17 @@ Apply the shared [proportionality rule](../../shared/policies/proportionality.md before adding work, delegating, or repeating verification. Treat feedback as a technical hypothesis. Understand it, verify against current -code and governing requirements, then act on evidence. +artifacts and governing requirements, then act on evidence. This workflow remains primary while checking an incoming allegation, even when that check runs code or tests. If the allegation is disproved, record the evidence -and reject it without entering a debugging lifecycle. Transfer to -`systematic-debugging` only for a confirmed failure whose cause still needs -diagnosis; the review finding retains its identity and returns here for its -final disposition after diagnosis and repair. +and reject it without entering another lifecycle. For a confirmed failure in code +whose cause needs diagnosis, the owning engineering method may use its +`systematic-debugging` skill when available. That is an optional companion +capability, not a dependency of shared review handling. For writing feedback, +check the document, sources, terminology and acceptance criteria directly. +Missing evidence remains unresolved; never invent a cause. The finding keeps +its identity and returns here for final disposition after repair. ## Evaluate first @@ -42,9 +45,12 @@ Work one finding at a time in impact and dependency order: 2. Important requirement, architecture, interface, and test gaps. 3. Accepted Minor improvements within current scope. -For behavior changes, use `test-driven-development` and observe a meaningful -failure before the fix. Run the narrow affected checks after each correction, -then use `verification-before-completion` before claiming the finding resolved. +For code behavior changes, require meaningful regression evidence and the +owning engineering method's test-first process; its `test-driven-development` +skill is optional companion support. For document corrections, verify facts, +links, terminology and the affected acceptance criteria; do not require a code +test for prose. Run the narrow affected checks after each correction, then use +the bundled `verification-before-completion` before claiming resolution. Re-review when a correction changes an interface or integration boundary. ## Completion diff --git a/skills/terminology-guard/SKILL.md b/skills/terminology-guard/SKILL.md deleted file mode 100644 index 975927b..0000000 --- a/skills/terminology-guard/SKILL.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -name: terminology-guard -description: "Use as a supporting skill when a document or documentation set must use one term per concept: create or extend the glossary before new terms appear, check drafts for banned variants and undefined terms, and align wording with interface labels. Not for choosing content structure, writing the text itself, or code identifiers." ---- - -# Terminology Guard - -Apply the shared [proportionality rule](../../shared/policies/proportionality.md) -before adding work, delegating, or repeating verification. - -Over hundreds of pages, readers lose trust when the same thing has three names. -The glossary is the single authority for terms; text follows it, and checks -are run against it rather than against memory. - -## Trigger - -Use when a documentation plan is created, before a chunk introduces a new -term, during set-wide review, and when an interface label, product name or -translation changes. In standalone documents, keep a local glossary section or -an inline definition list when more than a handful of terms recur. - -## Do not use for - -- Deciding chunk types or structure; that is `documentation-planning`. -- Writing the explanatory or procedural text; the didactic skills do that - using the terms this skill fixes. -- Code identifiers, API names and command syntax, which stay exactly as - implemented and are quoted in code formatting. - -## Glossary authority - -The glossary lives at `docs/writing//glossary.md` from the installed -[glossary template](../../templates/documentation/glossary.md). It contains a -machine-checkable JSON list and a readable table that must agree. Each entry -has the preferred term, a reader-level definition, the variants to avoid, the -chunk of first use and, when different, the exact interface label. - -Rules: - -- One term per concept and one concept per term. Introduce a synonym only as - an `avoid` entry that points to the preferred term. -- Add the term before the chunk that uses it is drafted. A term found in a - draft but not in the glossary is a finding, not a style choice. -- Interface labels are quoted exactly as the reader sees them, in the reader's - interface language, even when the glossary term differs; record both. -- Capitalization, plural and hyphenation are fixed per entry and followed - everywhere, including headings and captions. -- Deprecated terms remain listed with their replacement so old text can be - found and corrected. - -## Consistency check - -Run before a chunk is marked drafted and during `documentation-review`: - -1. Search the text for every `avoid` variant in the glossary; each hit is a - finding with the chunk, line and replacement. -2. List capitalized nouns, abbreviations and product names in the text that - are not glossary terms and not code; classify each as define, add to - glossary, or replace. -3. Confirm every abbreviation is expanded at first use in the chunk or linked - to its glossary entry. -4. Confirm interface labels in steps match the recorded `ui_label`. -5. Record the check in the chunk's `last_reviewed` field or the review report - with the glossary revision used. - -Use exact search on the actual files; do not rely on recollection of what a -chunk says. When a prose linter that reads term lists is available, generate -its lists from the glossary JSON rather than maintaining a second list by -hand: preferred terms with fixed casing become the accepted list, `avoid` -variants become the rejected list or a substitution rule mapping each variant -to its preferred term. The glossary remains the source; generated lists are -derived artifacts. - -## Completion - -The guard is satisfied for a scope when the glossary contains every recurring -term with a definition and avoid-list, no avoid variant appears in the scope, -no undefined abbreviation or unlisted term remains, interface labels match, -and the check is recorded with the revision it ran against. - -## Common mistakes - -- Treating the glossary as an appendix written last instead of a contract - written first. -- Allowing "the app", "the application" and the product name to alternate for - variety. -- Translating interface labels that the reader sees untranslated. -- Fixing a term in one chunk and not searching the rest of the set. diff --git a/skills/visual-placeholders/SKILL.md b/skills/visual-placeholders/SKILL.md deleted file mode 100644 index 1fbacbd..0000000 --- a/skills/visual-placeholders/SKILL.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -name: visual-placeholders -description: "Use as a supporting skill when documentation needs screenshots, diagrams, or other images that do not exist yet or must be reproducible: insert standardized placeholder callouts with stable IDs, alt text, captions and capture instructions, and keep the asset manifest in step. Not for producing the images, for UML architecture analysis, or for decorative illustration." ---- - -# Visual Placeholders - -Apply the shared [proportionality rule](../../shared/policies/proportionality.md) -before adding work, delegating, or repeating verification. - -Text and image must say the same thing. A placeholder is a contract: it states -what the reader must see, where in the text it belongs, and how to produce the -image later so that it proves exactly that. - -## Trigger - -Use while drafting any chunk where a screenshot or diagram would let the -reader confirm a state faster than words, when the interface is not available -to capture, when images will be produced by someone else, or when the image -must be regenerated for every version. - -## Do not use for - -- Creating or editing image files; capture and drawing happen outside this - skill following the manifest instructions. -- Architecture or design diagrams that answer engineering questions; those - belong to `architecture-modeling` under `docs/uml/`. -- Images without a claim: if the caption cannot state what the reader learns, - do not add the image. - -## When an image earns its place - -Add a placeholder when the image confirms a result after a step block, -locates an element that words locate poorly, shows a structure with more than -about five related parts, or compares states. Do not add one for every step; -a task chunk normally has one to three. - -## Callout syntax - -Insert the callout at the exact position in the text, as its own paragraph: - -```markdown -> **[IMAGE A-012 | screenshot]** Settings page with the **API keys** tab -> selected and one key listed. -> Alt: The Settings page shows the API keys tab with one key named Production. -> Capture: Sign in as an administrator, open Settings from the gear icon in the -> top-right corner, select the API keys tab, ensure exactly one key exists, -> capture the full page at 1440 px width, highlight the Generate key button. -``` - -Rules: - -- `A-` is a stable ID that never changes; the number is not an order. -- Kind is one of screenshot, diagram, video, table-image, icon. -- The first line is the caption the reader will see: it states the fact the - image proves, using glossary terms and exact interface labels. -- Alt text states the same fact in one sentence of at most about 150 - characters for readers who cannot see the image. It may start with the kind - ("Screenshot of ..."), never with "Image of", and never repeats the caption - word for word or names the file. -- Introduce the image in the preceding sentence and refer to it by ID or - figure number, never as "above" or "below". -- Capture instructions are precise enough for another person: role, path, - required state, element to highlight, size, and anything to mask. -- For diagrams, give the elements, relationships and reading direction, or - point to a text source such as a Mermaid file that will render the image. - -## Asset manifest - -Every callout has one row in `docs/writing//assets.md` from the -installed [asset manifest template](../../templates/documentation/assets.md), -and the chunk lists the asset ID in its `assets` frontmatter field. Update the -manifest in the same change as the callout. When an asset is captured, the -row moves to captured, the callout is replaced by the image reference with the -same caption and alt text, and the placeholder ID stays in an HTML comment -beside the image for later regeneration. - -## Completion - -Placeholders are complete for a scope when every callout has an ID, kind, -caption, alt text and capture instructions; every ID appears in the manifest -and in the chunk frontmatter; and no image lacks a claim the text also makes. - -## Common mistakes - -- Captions that name the screen instead of the fact to be observed. -- Alt text duplicating the caption word for word without the observable fact, - or omitting alt text altogether. -- Capture instructions that assume the capturer knows the product. -- Renumbering asset IDs when chapters are reordered. diff --git a/skills/writing-procedures/SKILL.md b/skills/writing-procedures/SKILL.md deleted file mode 100644 index 5a34892..0000000 --- a/skills/writing-procedures/SKILL.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -name: writing-procedures -description: "Use when a reader must perform actions: installation, configuration, operation, or any how-to steps in documentation or an ordinary reply. Produces numbered imperative steps, one action each, exact locations named, three to five steps per block, and a check that it worked. Not for conceptual explanation, reference tables, or diagnosing a failure." ---- - -# Writing Procedures - -Apply the shared [proportionality rule](../../shared/policies/proportionality.md) -before adding work, delegating, or repeating verification. - -Write for the reader's hands. A procedure tells one defined reader exactly what -to do, where, in what order, and how to see that it worked. Passive descriptions -of where something happens are not instructions. - -## Trigger - -Use for task and tutorial chunks, README installation and usage sections, -runbooks, handoff notes that ask someone to act, and replies that tell the -user what to do next. The [reader-oriented output -policy](../../shared/policies/reader-oriented-output.md) applies it to -ordinary replies. - -## Do not use for - -- Explaining why something works; use `explaining-concepts` before or beside - the procedure, not inside it. -- Symptom-first help when something has gone wrong; use - `empathic-troubleshooting`. -- Reference tables of options, fields or commands; link to them from a step. - -## Chapter pattern - -Every task chunk and every procedure section uses these four parts in this -order. In a short reply the headings may be implied, but the parts remain. - -1. **Goal.** One sentence: what the reader will have achieved. -2. **Before you start.** Prerequisites the reader can verify: access, installed - software with versions, state of the system, data they need, expected time. -3. **Steps.** Blocks of three to five numbered steps. Each block has a short - heading naming its sub-goal and ends with what the reader now sees. Split a - longer sequence into more blocks; never let a block grow past five steps. -4. **Check that it worked.** The observable result that proves success, and - the first thing to do if it is absent, with a link to the matching - troubleshooting chunk when one exists. - -## Step rules - -- Imperative mood, reader as the actor: "Select **Save**", not "The settings - are saved here" and not "You can now save". -- One action per step. A condition or a location may accompany it: "In the - top-right corner, select the gear icon." -- Name locations and labels exactly as the reader sees them, in the reader's - interface language, in bold for interface labels and in code for commands, - paths and values. -- Put the purpose before the action when it helps the reader decide: "To keep - the old key, select **Skip**." -- Write out the step an expert would skip. Apply the - [curse-of-knowledge filter](../../shared/writing/curse-of-knowledge-filter.md) - for skipped steps, unlocated objects and assumed state. -- Put warnings before the step they concern, not after it. -- Give the full path first; keyboard shortcuts and aliases are optional - extras in parentheses. -- Use the glossary term for every object; do not vary wording for style. -- Show the exact command or value in a fenced block when the reader must type - it; do not paraphrase it in prose. - -## Result statements - -After each block, state what the reader now sees: a dialog, a status, an -output line, a file. Where the result can vary, name the acceptable range. -Use a `visual-placeholders` callout when a screenshot would confirm the state -faster than words. - -## Completion - -A procedure is complete when the four parts are present, every block has three -to five imperative single-action steps, every location and label is exact, -prerequisites are verifiable, and the validation names an observable result. -Where possible, run or replay the procedure against the current system and -record the revision or version it was checked against. - -## Common mistakes - -- Numbering explanations, options or warnings as if they were steps. -- Describing the interface instead of instructing the reader. -- Hiding two or three actions in one step joined by "and". -- Ending a block without telling the reader what they should now see. -- Leaving "simply", "just" or "obviously" in the text; they signal a skipped - step. diff --git a/templates/documentation/assets.md b/templates/documentation/assets.md deleted file mode 100644 index b7c7ef5..0000000 --- a/templates/documentation/assets.md +++ /dev/null @@ -1,13 +0,0 @@ -# Asset Manifest: - -- Documentation ID: `` -- Artifact path: `docs/writing//assets.md` -- Rule: every placeholder callout in a chunk has one row here; every row has - capture instructions precise enough for someone else to produce the asset. - -| Asset ID | Kind | Chunk | Purpose (what the reader must see) | Capture or drawing instructions | Alt text | Status | -|---|---|---|---|---|---|---| -| A-001 | screenshot | C-002 | | | | placeholder | - -Kinds: screenshot, diagram, video, table-image, icon. Statuses: placeholder, -captured, reviewed, outdated. diff --git a/templates/documentation/chunk.md b/templates/documentation/chunk.md deleted file mode 100644 index fdf6174..0000000 --- a/templates/documentation/chunk.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -id: C-000 -title: -type: <concept | task | tutorial | reference | troubleshooting> -doc_id: <doc-id or standalone> -readers: [R1] -status: drafted -version: <product or content version this text describes> -depends_on: [] -assets: [] -last_reviewed: <YYYY-MM-DD or unreviewed> -summary: <One sentence the search index and the reader can use to decide whether to read this chunk.> ---- - -# <Title> - -<!-- -Body skeleton per type. Keep only the sections your type requires. - -concept: - ## In everyday terms (one analogy, then where the analogy stops) - ## How it works (the mechanism, no undefined terms) - ## Why it matters to you (consequence for the reader's goal) - ## Related terms (glossary links) - -task: - ## Goal (one sentence: what the reader will have achieved) - ## Before you start (prerequisites, access, state, time) - ## Steps (blocks of 3-5 numbered imperative steps; each block ends - with what the reader now sees) - ## Check that it worked (observable validation; what to do if it did not) - -tutorial: - ## What you will build (the visible end result) - ## Before you start - ## Step blocks (each block ends with a visible intermediate result) - ## What you have learned (and one next tutorial or how-to) - -reference: - ## Overview (one paragraph) - ## <Element tables> (consistent columns; no narrative) - ## Limits and defaults - -troubleshooting: - ## What you see (symptom in the reader's words) - ## Likely causes (most probable and cheapest to check first) - ## First check - ## Fix - ## Confirm it is resolved - ## If it is still not working (where to escalate; what to include) ---> diff --git a/templates/documentation/glossary.md b/templates/documentation/glossary.md deleted file mode 100644 index ba665d2..0000000 --- a/templates/documentation/glossary.md +++ /dev/null @@ -1,31 +0,0 @@ -# Glossary: <documentation set name> - -- Documentation ID: `<doc-id>` -- Artifact path: `docs/writing/<doc-id>/glossary.md` -- Rule: one term per concept, one concept per term. Add a term here before it - appears in a chunk. Deprecated variants are listed so a check can find them. - -```json -{ - "schema_version": 1, - "doc_id": "<doc-id>", - "language": "<documentation language>", - "terms": [ - { - "term": "<preferred term exactly as written in the text>", - "definition": "<one or two sentences a reader of the least experienced reader ID understands>", - "avoid": ["<synonym or spelling that must not appear>"], - "first_use": "<chunk ID where the term is first introduced>", - "ui_label": "<exact label in the interface if it differs>", - "notes": "<capitalization, plural, translation notes>" - } - ] -} -``` - -| Term | Definition | Avoid | First use | UI label | -|---|---|---|---|---| -| <term> | <definition> | <variants> | C-001 | <label> | - -Keep the table and the JSON block in agreement; the JSON block is the -machine-checkable list, the table is what readers and reviewers read. diff --git a/templates/documentation/pdf/.gitignore b/templates/documentation/pdf/.gitignore deleted file mode 100644 index e46c373..0000000 --- a/templates/documentation/pdf/.gitignore +++ /dev/null @@ -1,5 +0,0 @@ -/.quarto/ -/_book/ -/*.typ - -**/*.quarto_ipynb diff --git a/templates/documentation/pdf/DESIGN.md b/templates/documentation/pdf/DESIGN.md deleted file mode 100644 index 97d101d..0000000 --- a/templates/documentation/pdf/DESIGN.md +++ /dev/null @@ -1,146 +0,0 @@ -# Manual PDF design - -Use this template to turn a reviewed Markdown document set into one local PDF. -It uses white A4 pages, dark-navy rules, a restrained sans-serif hierarchy, -quiet callouts and a running footer. The layout and sample text are original. - -The design is deliberately editorial rather than application-like. The cover -has one focal point, the contents begin on their own page, chapter numbers are -typography rather than badges, and colour supports the hierarchy instead of -carrying it alone. - -## Build - -Copy this directory's source files into a new documentation directory. Exclude -`_book/`, `.quarto/` and generated top-level `.typ` files when copying an already -rendered checkout; keep `.typ` sources inside `_extensions/`. Run from that copy: - -```sh -quarto --version -quarto render --to em-manual-typst -``` - -Open `_book/manual.pdf`. The verified baseline is Quarto 1.10.18 with bundled -Typst 0.15.1. No R, Python, LaTeX or online Typst account is needed to render -these Markdown chapters. The plugin does not bundle Quarto or install it -implicitly. Get it from the [official release](https://github.com/quarto-dev/quarto-cli/releases/tag/v1.10.18) -and check the release's SHA-256 checksum before installing. - -The sample uses Helvetica Neue and Menlo, available on the verified Mac. On -other systems, select installed font families in `_brand.yml`, for example -locally installed Noto Sans and Noto Sans Mono. Do not ignore missing-font -warnings. Fonts are not downloaded or redistributed by this template. - -## Source and order - -Replace the sample files with your accepted chapters. Set their explicit order -in `book.chapters` in `_quarto.yml`, with paths relative to that file. The first -file is `index.md`, containing introductory material. Compare the list with the -accepted chunk manifest, in row order; include each selected chunk exactly once. -No manifest parser or filename sorting runs implicitly. - -Each chapter has one H1. Existing Engineering Method chunk frontmatter can stay: -when Quarto adds a matching title heading from that metadata, the bundled filter -removes only the generated duplicate in the render tree. It preserves the -original Markdown files and the authored heading ID. Use stable IDs such as -`{#sec-start}` and references such as `@sec-start` for links across chapters. - -Keep image paths relative to the chapter that contains them. Inspect images, -links and callouts in the actual PDF. The sample configuration disables code -execution. Use local assets; remote includes and external image downloads are -not part of this workflow. - -## Design settings - -| Element | Default | Where to change it | -|---|---|---| -| Page | A4, 28 mm side margins, 22 mm top, 24 mm bottom | `_quarto.yml` | -| Accent | Dark navy `#173A5E` | `_brand.yml`, `color.palette.navy` | -| Text | Dark ink `#232A31`, 12 pt | `_brand.yml`, foreground and base typography | -| Heading hierarchy | 36 pt cover, 25 pt chapter, 15 pt section | `typst-template.typ` | -| Chapter marker | Navy number, dark title and a 1 pt navy rule | `typst-template.typ` | -| Contents | Linked headings, two levels, automatic page references | `_quarto.yml`, `toc-depth` | -| Footer | No cover footer; then document title and current/total page count | `typst-template.typ` | -| Code | 9.5 pt monospace, shaded blocks | `_brand.yml` and Typst layout | -| Notes and warnings | Quarto callouts with icons disabled in the sample | Markdown callout attributes | - -The two `.typ` files live in `_extensions/em-manual/`. Change design rules there -instead of adding layout instructions to chapter prose. Keep required headings, -content order, facts and warnings intact when adapting the appearance. For a -long document, use a short title in the footer or adapt the footer layout before -letting it wrap across several lines. - -## Typographic rationale - -Treat the defaults as a coherent starting system, not isolated numbers: - -- The 28 mm side margins move ordinary A4 prose toward the established 45–75 - character reading range instead of filling almost the entire sheet. Actual - characters per line still vary with the font and the text. -- The 12 pt body and open leading favour sustained reading. Left-aligned, - non-justified text avoids the uneven word spaces produced by narrow justified - columns. -- Space, size and weight establish hierarchy before colour. The navy accent is - reserved for headings, links and rules; paragraphs remain dark neutral ink. -- Heading space is asymmetric: more separation before a new section, less - between its heading and first paragraph. Chapter rules sit close enough to - read as part of the heading. -- The default ink, navy and muted text have contrast ratios of 14.51:1, - 11.65:1 and 5.87:1 against white. These exceed the WCAG 2.1 AA threshold for - ordinary text, although contrast alone is not a PDF accessibility claim. - -Do not reduce margins merely to fit one more paragraph. First shorten or split -content, simplify tables, or give a wide figure its own layout. A successful -render is not evidence that a dense page is comfortable to read. - -## Typst and LaTeX - -The layout principles above are engine-independent. Quarto's LaTeX route uses -KOMA-Script by default and is a strong choice when a publisher requires `.tex`, -specialist TeX packages, or print-binding controls. This template retains Typst -because its custom format is already local, fast and self-contained in Quarto; -it does not require a separate TeX distribution. Changing engines would not by -itself repair weak margins, spacing or hierarchy. - -Keep one accepted layout implementation rather than maintaining visually -divergent Typst and LaTeX templates. Add a LaTeX variant only for a concrete -delivery requirement and verify it as a separate output contract. - -## Language and numbering - -`lang: en` selects English labels. `lang: de` selects German labels and the -footer `Seite X von Y`. This setting does not translate the content. The title -page is PDF page 1 but intentionally has no running footer. The contents begin -on page 2, and printed footer numbers then agree with PDF viewer page numbers. -Chapters begin on a new page; this template uses single-sided layout without -blank recto/verso pages. It supports a flat ordered chapter list; parts and -separately numbered appendices need their own layout work. - -Keep headings with the following paragraph. Split very long commands or table -cells at meaningful points rather than shrinking text until it is unreadable. -Check long tables, figures and callouts for overflow. A renderer's successful -exit status does not prove a usable layout or PDF accessibility conformance. - -## Verification - -Run `python3 tests/e2e/test-documentation-pdf --quarto /path/to/quarto` from the -Engineering Method checkout for the native sample check. It requires Poppler's -`pdfinfo` and `pdftotext` and MuPDF's `mutool`. These tools are verification -utilities; the render itself only needs Quarto and the configured fonts. - -Check the rendered cover, contents, chapter openings, code, tables, callouts and -last page visually. Confirm that the cover is uncluttered and has no footer, -the chapter rule is dark navy, and prose uses the intended narrower measure. -For delivery, confirm manifest order, working PDF links, correct contents page -references, every footer total and unchanged Markdown sources. Keep `_book/`, -`.quarto/` and generated `.typ` files out of version control; the sample -`.gitignore` does this without hiding the extension sources. - -Sources: [Quarto book output](https://quarto.org/docs/books/book-output.html), -[custom Typst formats](https://quarto.org/docs/output-formats/typst-custom.html), -[central branding](https://quarto.org/docs/authoring/brand.html), and -[Typst page layout](https://typst.app/docs/guides/page-setup/). The design -rationale also draws on the [ONS accessible text guidance](https://service-manual.ons.gov.uk/brand-guidelines/typography/accessible-text-formatting), -the [Eurostat A4 publication grid and heading styles](https://ec.europa.eu/eurostat/documents/4187653/7192088/STYLE_GUIDE_2016.pdf), -the [W3C minimum-contrast explanation](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum), -and Quarto's [LaTeX/KOMA-Script PDF documentation](https://quarto.org/docs/output-formats/pdf-basics). diff --git a/templates/documentation/pdf/_brand.yml b/templates/documentation/pdf/_brand.yml deleted file mode 100644 index 58ebc89..0000000 --- a/templates/documentation/pdf/_brand.yml +++ /dev/null @@ -1,21 +0,0 @@ -meta: - name: Documentation -color: - palette: - navy: "#173A5E" - ink: "#232A31" - muted: "#5B6670" - paper: "#FFFFFF" - primary: navy - foreground: ink - background: paper -typography: - base: - family: "Helvetica Neue" - size: 12pt - headings: - family: "Helvetica Neue" - weight: 700 - monospace: - family: "Menlo" - size: 9.5pt diff --git a/templates/documentation/pdf/_extensions/em-manual/_extension.yml b/templates/documentation/pdf/_extensions/em-manual/_extension.yml deleted file mode 100644 index 51cc4ee..0000000 --- a/templates/documentation/pdf/_extensions/em-manual/_extension.yml +++ /dev/null @@ -1,13 +0,0 @@ -title: Engineering Method Manual -author: Peter Hense -version: 0.1.0 -quarto-required: ">=1.10.18" -contributes: - formats: - typst: - filters: - - path: chunk-title.lua - at: pre-quarto - template-partials: - - typst-template.typ - - typst-show.typ diff --git a/templates/documentation/pdf/_extensions/em-manual/chunk-title.lua b/templates/documentation/pdf/_extensions/em-manual/chunk-title.lua deleted file mode 100644 index 1b7df11..0000000 --- a/templates/documentation/pdf/_extensions/em-manual/chunk-title.lua +++ /dev/null @@ -1,25 +0,0 @@ --- Quarto book composition inserts a title header and a quarto-title-block --- before the original chapter body. Our chunk contract already has a matching --- H1. Remove only that generated header before cross-reference numbering; --- retain the metadata block and authored heading, including its stable ID. -return {{ - Blocks = function(blocks) - local result = pandoc.List() - local i = 1 - while i <= #blocks do - local first, metadata, authored = blocks[i], blocks[i + 1], blocks[i + 2] - if authored and first.t == "Header" and first.level == 1 - and metadata.t == "CodeBlock" and metadata.classes:includes("quarto-title-block") - and authored.t == "Header" and authored.level == 1 - and pandoc.utils.stringify(first.content) == pandoc.utils.stringify(authored.content) then - result:insert(metadata) - result:insert(authored) - i = i + 3 - else - result:insert(first) - i = i + 1 - end - end - return result - end, -}} diff --git a/templates/documentation/pdf/_extensions/em-manual/typst-show.typ b/templates/documentation/pdf/_extensions/em-manual/typst-show.typ deleted file mode 100644 index bc5d595..0000000 --- a/templates/documentation/pdf/_extensions/em-manual/typst-show.typ +++ /dev/null @@ -1,17 +0,0 @@ -#show: body => em-manual( - title: [$title$], - subtitle: [$if(subtitle)$$subtitle$$endif$], - lang: "$if(lang)$$lang$$else$en$endif$", - accent: brand-color.at("primary", default: rgb("173A5E")), - ink: brand-color.at("foreground", default: rgb("232A31")), - muted: brand-color.at("muted", default: rgb("5B6670")), - font: $if(brand.typography.base.family)$$brand.typography.base.family$$else$("Libertinus Serif",)$endif$, - font-size: $if(brand.typography.base.size)$$brand.typography.base.size$$else$12pt$endif$, - code-font: $if(brand.typography.monospace.family)$$brand.typography.monospace.family$$else$("DejaVu Sans Mono",)$endif$, - code-size: $if(brand.typography.monospace.size)$$brand.typography.monospace.size$$else$9.5pt$endif$, - show-toc: $if(toc)$true$else$false$endif$, - toc-title: [$if(toc-title)$$toc-title$$endif$], - toc-depth: $if(toc-depth)$$toc-depth$$else$2$endif$, - numbering-pattern: $if(section-numbering)$"$section-numbering$"$else$none$endif$, - body, -) diff --git a/templates/documentation/pdf/_extensions/em-manual/typst-template.typ b/templates/documentation/pdf/_extensions/em-manual/typst-template.typ deleted file mode 100644 index 26cbaff..0000000 --- a/templates/documentation/pdf/_extensions/em-manual/typst-template.typ +++ /dev/null @@ -1,91 +0,0 @@ -// Original Engineering Method layout. Quarto supplies document conversion, -// callouts, cross-references and brand-color through its standard template. -#let em-manual( - title: [], subtitle: [], lang: "en", font: ("Helvetica Neue",), - font-size: 12pt, code-font: ("Menlo",), code-size: 9.5pt, show-toc: true, - toc-title: [], toc-depth: 2, numbering-pattern: "1.1", - accent: rgb("173A5E"), ink: rgb("232A31"), muted: rgb("5B6670"), body, -) = { - let german = lang.starts-with("de") - set document(title: title) - set text(font: font, size: font-size, fill: ink, lang: lang) - set par(justify: false, leading: 0.62em, spacing: 0.62em) - set heading(numbering: numbering-pattern) - set page( - footer: context { - if counter(page).get().first() > 1 [ - #line(length: 100%, stroke: 0.45pt + accent.lighten(64%)) - #v(2.2mm) - #set text(size: 8.2pt, fill: muted) - #grid(columns: (1fr, auto), gutter: 5mm, - title, [ - #if german { [Seite] } else { [Page] } - #counter(page).get().first() - #if german { [von] } else { [of] } - #counter(page).final().first() - ]) - ] - }, - ) - show link: set text(fill: accent) - show raw: set text(font: code-font, size: code-size) - set table( - inset: 5pt, - stroke: 0.4pt + accent.lighten(70%), - fill: (x, y) => if y == 0 { accent.lighten(94%) } else { none }, - ) - show table.cell.where(y: 0): set text(weight: "bold") - show heading.where(level: 1): it => { - if it.numbering != none { pagebreak(weak: true) } - block(above: 2mm, below: 5.5mm, width: 100%, sticky: true)[ - #stack( - dir: ttb, - spacing: 3mm, - [ - #set text(size: 25pt, weight: "bold") - #if it.numbering != none { - text(fill: accent, weight: "regular", counter(heading).display(it.numbering)) - h(9pt) - } - #it.body - ], - line(length: 100%, stroke: 1pt + accent), - ) - ] - } - show heading.where(level: 2): set text(size: 15pt, weight: "bold", fill: accent) - show heading.where(level: 2): set block(above: 10pt, below: 4pt, sticky: true) - show heading.where(level: 3): set text(size: 11.5pt, weight: "bold") - show heading.where(level: 3): set block(above: 8pt, below: 3pt, sticky: true) - show quote.where(block: true): it => block( - width: 100%, inset: 10pt, fill: accent.lighten(93%), - stroke: (left: 2pt + accent), it.body, - ) - line(length: 100%, stroke: 2.2pt + accent) - v(10mm) - text(size: 9pt, weight: "bold", tracking: 0.08em, fill: accent, - if german { "DOKUMENTATION" } else { "DOCUMENTATION" }) - v(7mm) - block(width: 88%)[ - #set par(leading: 0.18em) - #text(size: 36pt, weight: "bold", title) - ] - v(5mm) - line(length: 34mm, stroke: 1pt + accent) - v(5mm) - block(width: 78%)[#text(size: 15pt, fill: muted, subtitle)] - pagebreak(weak: false) - if show-toc { - { - show outline.entry.where(level: 1): set block(above: 0.75em) - show outline.entry.where(level: 1): set text(weight: "bold") - show outline.entry.where(level: 2): set text(size: 10pt, fill: muted) - outline( - title: if toc-title != [] { toc-title } else if german { [Inhaltsverzeichnis] } else { [Contents] }, - depth: toc-depth, indent: 1.15em, - ) - } - v(7mm) - } - body -} diff --git a/templates/documentation/pdf/_quarto.yml b/templates/documentation/pdf/_quarto.yml deleted file mode 100644 index 9dd8511..0000000 --- a/templates/documentation/pdf/_quarto.yml +++ /dev/null @@ -1,31 +0,0 @@ -project: - type: book - output-dir: _book - -book: - title: "A clear guide" - subtitle: "Markdown chapters, one designed PDF" - author: "Documentation team" - output-file: manual - chapters: - - index.md - - chapters/01-start.md - - chapters/02-reference.md - - chapters/03-check.md - -lang: en -execute: - enabled: false - -format: - em-manual-typst: - papersize: a4 - margin: - x: 28mm - top: 22mm - bottom: 24mm - toc: true - toc-depth: 2 - number-sections: true - section-numbering: "1.1" - keep-typ: true diff --git a/templates/documentation/pdf/chapters/01-start.md b/templates/documentation/pdf/chapters/01-start.md deleted file mode 100644 index 5eaf685..0000000 --- a/templates/documentation/pdf/chapters/01-start.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -id: C-001 -title: Create your first PDF -type: task -doc_id: pdf-example -readers: [R1] -status: reviewed -version: Quarto 1.10.18 -last_reviewed: 2026-09-16 ---- - -# Create your first PDF {#sec-start} - -## Goal - -Create one PDF from the introduction and three Markdown chapter files. - -## Before you start - -Install Quarto 1.10.18 and confirm that the fonts listed in `_brand.yml` are -available. This template uses Helvetica Neue and Menlo on macOS. Change those -names to installed fonts when rendering on another operating system. - -::: {.callout-note icon=false} -The PDF is built locally. You do not need a Typst account or a browser session. -::: - -## Build the document - -1. Open a terminal in the copied template directory. -2. Run `quarto render --to em-manual-typst`. -3. Open `_book/manual.pdf` in your PDF viewer. - -You should see a title, contents with page references, and the chapter headings -listed in `_quarto.yml`. Each page has a footer with its number and the total. - -```sh -quarto --version -quarto render --to em-manual-typst -``` - -## Check that it worked - -Use the contents to open @sec-reference. Confirm that the footer shows the same -page as the contents entry. Follow the final checklist in @sec-check before -sharing a real document. diff --git a/templates/documentation/pdf/chapters/02-reference.md b/templates/documentation/pdf/chapters/02-reference.md deleted file mode 100644 index 9ee9961..0000000 --- a/templates/documentation/pdf/chapters/02-reference.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -id: C-002 -title: Configure the document -type: reference -doc_id: pdf-example -readers: [R1] -status: reviewed -version: Quarto 1.10.18 -last_reviewed: 2026-09-16 ---- - -# Configure the document {#sec-reference} - -## Files and responsibilities - -| File | What you change | -|---|---| -| `_quarto.yml` | Title, language, ordered chapter list and PDF filename | -| `_brand.yml` | Accent color, text color and font families | -| `chapters/*.md` | The text, tables, links and images readers will use | -| `_extensions/em-manual/typst-template.typ` | Heading layout, whitespace and footer | - -## Chapter order - -List files explicitly in `book.chapters`. Use the order in the accepted -documentation plan and include each selected chapter once. A filename does not -determine the reading order. - -::: {.callout-warning icon=false} -Copy templates into a new directory. Do not replace an existing guide's -configuration or chapter files without inspecting them first. -::: - -## Links and numbers - -Give important headings a stable ID such as `{#sec-start}`. A reference such as -`@sec-start` produces a link and a chapter number in the PDF. The contents and -footer page numbers are recalculated when text changes. - -## Language and fonts - -Set `lang: de` for German labels, including the footer “Seite X von Y”. The -content remains in the language in which you wrote it. Changing this option -does not translate your Markdown files. - -Font files are not bundled. Keep font names and installed versions consistent -on the machines that produce your PDFs. diff --git a/templates/documentation/pdf/chapters/03-check.md b/templates/documentation/pdf/chapters/03-check.md deleted file mode 100644 index 9481d51..0000000 --- a/templates/documentation/pdf/chapters/03-check.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -id: C-003 -title: Check the finished PDF -type: task -doc_id: pdf-example -readers: [R1] -status: reviewed -version: Quarto 1.10.18 -last_reviewed: 2026-09-16 ---- - -# Check the finished PDF {#sec-check} - -## Verify the reading path - -1. Compare the PDF chapter order with the documentation plan. -2. Click an entry in the contents and check its destination page. -3. Follow the link back to @sec-start and verify that it reaches the first chapter. - -The links should stay inside the PDF, and their printed numbers should match -the destination headings. This [relative chapter link](01-start.md) should also -open the first chapter. - -## Inspect the pages - -Look at every page in a short guide. For a long manual, inspect the title, -contents, chapter openings, tables, figures, code and final page. Check that -nothing is clipped and that headings stay with their following text. - -> Keep the content review separate from the layout check. A successful render -> confirms that the document can be built; it does not confirm the instructions -> are correct for the reader. - -## Record the result - -Record the source revision, tool versions, output path and any unresolved -layout defects. On this final page, the current page and the total in the footer -should be equal. The Markdown source files must remain unchanged after rendering. diff --git a/templates/documentation/pdf/index.md b/templates/documentation/pdf/index.md deleted file mode 100644 index 6446b06..0000000 --- a/templates/documentation/pdf/index.md +++ /dev/null @@ -1,8 +0,0 @@ -# About this guide {.unnumbered .unlisted} - -This sample shows the reusable manual layout. The chapter files remain ordinary -Markdown. Quarto joins them in the configured order and Typst lays out the PDF. - -The dark-blue accents, measured line length and restrained callouts establish a -clear reading hierarchy. Replace this sample text with the introduction to your -guide. diff --git a/templates/documentation/plan.md b/templates/documentation/plan.md deleted file mode 100644 index 8c32007..0000000 --- a/templates/documentation/plan.md +++ /dev/null @@ -1,89 +0,0 @@ -# Documentation Plan: <documentation set name> - -## Stable work ID - -- Documentation ID: `<doc-id>` -- Artifact path: `docs/writing/<doc-id>/plan.md` -- Glossary: `docs/writing/<doc-id>/glossary.md` -- Asset manifest: `docs/writing/<doc-id>/assets.md` -- Content root: `<path where the chunk files live, for example docs/manual/>` -- Status: Planned - -## Scale decision - -- Scale: Large -- Evidence: <chapter count, audiences, expected length, shared terms, sessions> -- Documentation language: <language the readers read> -- Source-of-truth systems: <product version, UI build, API version, code paths> - -## Readers - -| Reader ID | Role and prior knowledge | Goal when reading | Interface and version | -|---|---|---|---| -| R1 | <role; what they already know and do not know> | <what they need to achieve> | <UI language, version, platform> | - -Name the least experienced reader who is expected to succeed. Every chunk -declares which reader IDs it serves. - -## Information architecture - -Each chunk has exactly one content type. Do not mix a tutorial with reference -material or a procedure with a long explanation; link between them instead. -Types classify chunks; they are not the top-level navigation. Arrange sections -by the readers' journey and keep every level internally consistent. - -| Type | Reader question | Shape | -|---|---|---| -| concept | Why and how does this work? | Analogy, mechanism, limits, related terms | -| task | How do I do X? | Goal, prerequisites, three-to-five-step blocks, validation | -| tutorial | Can you walk me through my first success? | Ordered lesson with a guaranteed visible result | -| reference | What exactly are the options, fields, limits? | Consistent tables and lists, no narrative | -| troubleshooting | Something is wrong; what now? | Symptom, likely causes in order, first check, fix, verification | - -## Chunk manifest - -One row per Markdown file. Rows define reading order; reorder rows without -renaming stable IDs. - -| Chunk ID | File | Type | Title | Readers | Depends on | Assets | Status | -|---|---|---|---|---|---|---|---| -| C-001 | <content root>/<section>/<slug>.md | concept | <title> | R1 | none | none | planned | - -Statuses: planned, drafted, reviewed, accepted, superseded. - -## Conventions - -- Frontmatter: every chunk uses the fields defined in the chunk template. -- File naming: `<section>/<kebab-case-slug>.md`; one chunk per file. -- Headings: one H1 equal to the title; H2 for the type's required sections. -- Procedures: imperative steps, one action per step, three to five steps per - block, an observable result after each block. -- Terminology: the glossary is authoritative; add a term before using it. -- Prose: every chunk is drafted under the `human-prose-drafting` constraints; - preserve source facts, technical terms and required structure while avoiding - staged rhetoric and filler. There is no separate humanizing pass. -- Assets: use the placeholder callout syntax from `visual-placeholders` and - register every placeholder in the asset manifest. -- Cross-references: link by relative file path and chunk ID; no bare "see above". - -## Review and acceptance - -- Set-wide review occurs when all chunks in a section reach drafted, and again - before acceptance of the whole set. -- Acceptance criteria: <what makes the set complete, for example every reader - goal has a path, every placeholder has capture instructions, no terminology - findings remain>. - -## PDF output (when requested) - -- Export skill: `documentation-pdf`, after content acceptance. -- Quarto project root: <directory containing the chapters and _quarto.yml> -- PDF title, language and output name: <values> -- Design: <bundled em-manual template or named project template> -- Chapter list: accepted manifest rows in the same order, each included once. -- Verification: inspect contents links, page references, footer totals, assets - and representative pages; record source revision and tool versions. - -## Out of scope - -- <documents, audiences, versions or platforms intentionally excluded> diff --git a/templates/documentation/review.md b/templates/documentation/review.md deleted file mode 100644 index 0b2ffe4..0000000 --- a/templates/documentation/review.md +++ /dev/null @@ -1,37 +0,0 @@ -# Documentation Review: <documentation set name> - -## Stable work ID - -- Documentation ID: `<doc-id>` -- Plan: `docs/writing/<doc-id>/plan.md` -- Artifact path: `docs/writing/<doc-id>/review.md` -- Reviewed revision: `<full commit>` -- Scope: <section IDs or whole set> - -## Checks - -| Check | Method | Result | -|---|---|---| -| Frontmatter complete and matches the manifest | Read every chunk header against the manifest | pass / findings | -| One content type per chunk | Read headings against the type skeleton | pass / findings | -| Task chunks: goal, prerequisites, step blocks of three to five, validation | Count steps per block; confirm each block ends with a result | pass / findings | -| Terminology | Search for every `avoid` variant and undefined capitalized terms | pass / findings | -| Curse-of-knowledge filter | Sample read as the least experienced reader; locations, skipped steps, assumed state | pass / findings | -| Placeholders and assets | Every callout has a manifest row and capture instructions | pass / findings | -| Cross-references | Every relative link resolves; no dangling chunk IDs | pass / findings | -| Troubleshooting chunks | Symptom first, causes ordered, fix, confirmation | pass / findings | -| Prose tells | Assess passages in context per `human-prose-drafting`; preserve facts, terms, warnings and required structure; no word-blacklist failures | pass / findings | - -## Findings - -| Finding ID | Chunk | Severity | Evidence | Required change | Status | -|---|---|---|---|---|---| -| DR-001 | C-003 | Important | <quoted passage or missing item> | <what the author must do> | open | - -Severities: Critical (reader cannot succeed or is misled), Important (reader -succeeds with friction or inconsistency), Minor (style within conventions). - -## Verdict - -- Open Critical or Important findings: <count> -- Result: Ready / Return to `documentation-authoring` with the findings above diff --git a/tests/e2e/test-documentation-pdf b/tests/e2e/test-documentation-pdf deleted file mode 100644 index f42fd1d..0000000 --- a/tests/e2e/test-documentation-pdf +++ /dev/null @@ -1,150 +0,0 @@ -#!/usr/bin/env python3 -"""Native template check; requires Quarto, Poppler and MuPDF, no model calls.""" -from pathlib import Path -import argparse -import hashlib -import json -import re -import shutil -import subprocess -import tempfile -import xml.etree.ElementTree as ET - -ROOT = Path(__file__).resolve().parents[2] -TEMPLATE = ROOT / 'templates/documentation/pdf' -CHAPTERS = [('sec-start', 'Create your first PDF'), - ('sec-reference', 'Configure the document'), - ('sec-check', 'Check the finished PDF')] - - -def run(*args, cwd=None): - result = subprocess.run(args, cwd=cwd, text=True, capture_output=True, timeout=120) - if result.returncode: - raise AssertionError(f'{args[0]} failed ({result.returncode}):\n{result.stdout}\n{result.stderr}') - return result.stdout + result.stderr if args[0].endswith('quarto') else result.stdout - - -def source_hashes(root): - return {str(p.relative_to(root)): hashlib.sha256(p.read_bytes()).hexdigest() - for p in root.rglob('*.md') - if not {'_book', '.quarto'}.intersection(p.relative_to(root).parts)} - - -def check(quarto, root, language, stress=False): - shutil.copytree(TEMPLATE, root, ignore=shutil.ignore_patterns('_book', '.quarto', 'index.typ')) - config = root / '_quarto.yml' - config.write_text(config.read_text().replace('lang: en', f'lang: {language}')) - expected = list(CHAPTERS) - if stress: - text = config.read_text().replace( - ' - chapters/01-start.md\n - chapters/02-reference.md', - ' - chapters/02-reference.md\n - chapters/01-start.md') - config.write_text(text) - expected[0], expected[1] = expected[1], expected[0] - chapter = root / 'chapters/02-reference.md' - with chapter.open('a') as f: - f.write('\n## Long table\n\n| Row | Description |\n|---|---|\n') - for row in range(1, 121): - f.write(f'| ROW-{row:03} | This row verifies a table spanning PDF pages. |\n') - before = source_hashes(root) - output = run(quarto, 'render', '--to', 'em-manual-typst', cwd=root) - assert not re.search(r'\b(?:warning|error):', output, re.I), output - pdf = root / '_book/manual.pdf' - assert pdf.is_file(), 'Missing PDF' - assert source_hashes(root) == before, 'Rendering changed Markdown source bytes' - info = run('pdfinfo', str(pdf)) - count = int(re.search(r'^Pages:\s+(\d+)', info, re.M)[1]) - text = run('pdftotext', '-layout', str(pdf), '-') - pages = text.rstrip('\f\n').split('\f') - assert len(pages) == count - assert 'A4' in info - contents_title = 'Inhaltsverzeichnis' if language == 'de' else 'Table of contents' - cover_footer = f'Seite 1 von {count}' if language == 'de' else f'Page 1 of {count}' - assert 'A clear guide' in pages[0], 'Missing cover title' - assert contents_title not in pages[0], 'Contents must not crowd the cover' - assert cover_footer not in ' '.join(pages[0].split()), 'Cover must not show a running footer' - contents_page = pages[1] - assert contents_title in contents_page - for number, page in enumerate(pages[1:], 2): - footer = f'Seite {number} von {count}' if language == 'de' else f'Page {number} of {count}' - assert footer in ' '.join(page.split()), (number, footer) - chapter_pages = {} - for number, (anchor, title) in enumerate(expected, 1): - matches = [i for i, page in enumerate(pages[1:], 2) - if re.search(r'^\s*' + str(number) + r'\s+' + re.escape(title) + r'\s*$', page, re.M)] - assert len(matches) == 1, (title, 'Missing or duplicate chapter', matches) - chapter_pages[anchor] = matches[0] - assert len(re.findall(re.escape(title), contents_page)) == 1, 'Duplicate contents entry' - toc = next(line for line in contents_page.splitlines() if title in line) - assert re.search(r'\b' + str(matches[0]) + r'\s*$', toc), (title, toc) - assert list(chapter_pages.values()) == sorted(chapter_pages.values()) - page_objects = {int(obj): int(page) for page, obj in re.findall( - r'page (\d+) = (\d+) 0 R', run('mutool', 'show', str(pdf), 'pages'))} - named = run('mutool', 'show', str(pdf), 'trailer/Root/Names/Dests') - destinations = dict(re.findall(r'\(([^)]+)\)\s+(\d+) 0 R', named)) - for anchor, page in chapter_pages.items(): - target = run('mutool', 'show', str(pdf), destinations[anchor]) - obj = int(re.search(r'\[\s*(\d+) 0 R', target)[1]) - assert page_objects[obj] == page, (anchor, 'Wrong PDF destination') - links = run('mutool', 'show', str(pdf), 'pages/*/Annots/*') - for anchor in chapter_pages: - assert '/Dest (' + anchor + ')' in links, (anchor, 'Missing clickable link') - for anchor in re.findall(r'/Dest \(([^)]+)\)', links): - assert anchor in destinations, ('Dangling PDF link', anchor) - first_chapter_svg = run( - 'mutool', 'draw', '-F', 'svg', '-o', '-', str(pdf), - str(chapter_pages[expected[0][0]])) - assert 'stroke="#173a5e"' in first_chapter_svg, 'Missing dark-blue chapter rule' - layout_bbox = ET.fromstring(run('pdftotext', '-bbox-layout', str(pdf), '-')) - layout_pages = list(layout_bbox.iter('{http://www.w3.org/1999/xhtml}page')) - sample_task_page = layout_pages[chapter_pages['sec-start'] - 1] - body_lines = [] - for line in sample_task_page.iter('{http://www.w3.org/1999/xhtml}line'): - words = [word.text or '' for word in line] - if ' '.join(words).startswith('Create one PDF'): - body_lines.append(line) - assert len(body_lines) == 1, 'Could not identify the sample body measure' - sample_line = body_lines[0].attrib - assert float(sample_line['xMin']) >= 79, 'Body measure is too wide for A4 reading' - assert float(sample_line['yMax']) - float(sample_line['yMin']) >= 13.9, 'Body type is too small' - bbox = ET.fromstring(run('pdftotext', '-bbox', str(pdf), '-')) - for page in bbox.iter('{http://www.w3.org/1999/xhtml}page'): - width, height = float(page.attrib['width']), float(page.attrib['height']) - for word in page: - box = {key: float(word.attrib[key]) for key in ['xMin','xMax','yMin','yMax']} - assert box['xMin'] >= -0.1 and box['xMax'] <= width + 0.1, ('Horizontal overflow', word.text) - assert box['yMin'] >= -0.1 and box['yMax'] <= height + 0.1, ('Vertical overflow', word.text) - if stress: - assert count > 4, 'Long table did not span additional pages' - for row in range(1, 121): - assert text.count(f'ROW-{row:03}') == 1, ('Missing/duplicate table row', row) - return {'language': language, 'stress': stress, 'pages': count, - 'chapter_pages': chapter_pages, 'source_unchanged': True, - 'contents_links_and_page_totals': 'passed', 'pdf': str(pdf)} - - -def main(): - parser = argparse.ArgumentParser(description=__doc__) - parser.add_argument('--quarto', default=shutil.which('quarto')) - parser.add_argument('--output-dir', type=Path) - args = parser.parse_args() - if not args.quarto: - parser.error('Provide --quarto or install Quarto on PATH') - for tool in ['pdfinfo', 'pdftotext', 'mutool']: - if not shutil.which(tool): - parser.error(f'Required verification tool missing: {tool}') - root = args.output_dir.resolve() if args.output_dir else Path(tempfile.mkdtemp(prefix='em-pdf-check-')) - root.mkdir(parents=True, exist_ok=True) - # Each destination must be absent; never overwrite a prior verification run. - results = [check(args.quarto, root/'en', 'en'), - check(args.quarto, root/'de', 'de'), - check(args.quarto, root/'stress', 'en', stress=True)] - report = {'quarto': run(args.quarto, '--version').strip(), - 'typst': run(args.quarto, 'typst', '--version').strip(), - 'results': results} - (root/'verification.json').write_text(json.dumps(report, indent=2)+'\n') - print(json.dumps(report, indent=2)) - - -if __name__ == '__main__': - main() diff --git a/tests/e2e/test-method-split b/tests/e2e/test-method-split new file mode 100644 index 0000000..41c3404 --- /dev/null +++ b/tests/e2e/test-method-split @@ -0,0 +1,138 @@ +#!/usr/bin/env python3 +"""Verify immutable archives through isolated use, interruption and recovery.""" +import argparse +import hashlib +import json +import os +from pathlib import Path +import subprocess +import sys +import tempfile +import zipfile + + +def run(command, cwd, *, expected=0): + result = subprocess.run([str(x) for x in command], cwd=cwd, capture_output=True, text=True, timeout=60) + if result.returncode != expected: + raise RuntimeError(f'{command[0]} exited {result.returncode}, expected {expected}: {result.stdout}{result.stderr}') + return result.stdout.strip() + + +def extract(archive, parent): + with zipfile.ZipFile(archive) as z: + names = {Path(x.filename).parts[0] for x in z.infolist()} + if len(names) != 1: raise ValueError('archive must have one root') + for member in z.infolist(): + path = Path(member.filename) + if path.is_absolute() or '..' in path.parts or member.external_attr >> 16 & 0o170000 == 0o120000: + raise ValueError('unsafe archive member') + z.extractall(parent) + for member in z.infolist(): + if not member.is_dir(): (parent / member.filename).chmod(member.external_attr >> 16 & 0o777) + return parent / names.pop() + + +def initialize_git(root): + run(['git', 'init', '-q', '-b', 'main'], root) + run(['git', 'config', 'user.name', 'Integration Test'], root) + run(['git', 'config', 'user.email', 'integration@example.invalid'], root) + + +def commit(root): + run(['git', 'add', '.'], root) + run(['git', 'commit', '-qm', 'integration fixture'], root) + return run(['git', 'rev-parse', 'HEAD'], root) + + +def snapshot(root): + return {p.relative_to(root).as_posix(): (hashlib.sha256(p.read_bytes()).hexdigest(), p.stat().st_mode & 0o777) + for p in root.rglob('*') if p.is_file() and not {'.git', '__pycache__'}.intersection(p.relative_to(root).parts)} + + +CRASH = ''' +import importlib.util, os, sys +from pathlib import Path +spec=importlib.util.spec_from_file_location('sync_crash',sys.argv[1]) +m=importlib.util.module_from_spec(spec);spec.loader.exec_module(m) +replace=m.os.replace +def crash(src,dst): + replace(src,dst) + if Path(dst).as_posix().endswith('shared/platform/claude.md'): os._exit(23) +m.os.replace=crash +m.synchronize(Path(sys.argv[2]),Path(sys.argv[3])) +''' + + +def verify(core_zip, engineering_zip, writing_zip): + with tempfile.TemporaryDirectory(prefix='method-split-e2e-') as temporary: + base = Path(temporary) + core = extract(core_zip, base / 'source') + initialize_git(core) + first = commit(core) + methods = [extract(engineering_zip, base / 'isolated-a'), extract(writing_zip, base / 'isolated-b')] + reports = [] + for index, method in enumerate(methods): + target = base / f'project-{index}'; target.mkdir(); initialize_git(target) + sync = [sys.executable, method / 'scripts/sync-core', '--target-root', method] + state = [sys.executable, method / 'scripts/project-state'] + run(sync + ['--source-root', core], target) + run(sync + ['--check'], target) + run([sys.executable, method / 'scripts/validate-plugin', method], target) + plugin_before = snapshot(method) + run(state + ['backlog', 'init', '--project-key', 'TEST'], target) + run(state + ['backlog', 'add', '--id', 'TEST-001', '--title', 'Retain target state', '--priority', 'P1'], target) + run(state + ['backlog', 'start', 'TEST-001'], target) + (target / '.gitignore').write_text('.engineering-method/\n') + head = commit(target) + # Construct the input with the actual extracted runtime's schema. + payload = run([sys.executable, '-c', + 'import sys,json;from dataclasses import asdict;sys.path.insert(0,sys.argv[1]);' + 'from engineering_method.continuity import RunState;' + 'print(json.dumps(asdict(RunState(work_id="TEST-001",backlog_id="TEST-001",' + 'lifecycle="integration",phase="verification",next_action="Continue retained work",' + 'base_commit=sys.argv[2],last_observed_head=sys.argv[2],coordination_mode="coordinator-only"))))', + method, head], target) + (target / 'state-input.json').write_text(payload) + (target / 'resume-input.md').write_text('Continue TEST-001 in this target project.\n') + run(state + ['continuity-state', 'init', 'TEST-001', '--file', 'state-input.json', '--resume-file', 'resume-input.md'], target) + run(state + ['continuity-state', 'recover', 'TEST-001', '--coordinator-only'], target) + retained = snapshot(target) + if plugin_before != snapshot(method): raise AssertionError('project state leaked into the plugin') + reports.append({'method': method.name, 'work_id': 'TEST-001', 'target_files': len(retained)}) + # Change two real exported adapters, then interrupt after the first changed one. + for name in ('shared/platform/claude.md', 'shared/platform/codex.md'): + path = core / name; path.write_bytes(path.read_bytes() + b'\nIntegration revision marker.\n') + second = commit(core) + for method in methods: + target = base / f'project-{methods.index(method)}' + retained = snapshot(target) + before = snapshot(method) + run([sys.executable, '-c', CRASH, method / 'scripts/method_core.py', core, method], target, expected=23) + sync = [sys.executable, method / 'scripts/sync-core', '--target-root', method] + run(sync + ['--check'], target, expected=1) + run(sync + ['--recover'], target) + if before != snapshot(method): raise AssertionError('recovery changed the previous plugin snapshot') + run(sync + ['--check'], target) + run(sync + ['--source-root', core], target) + run(sync + ['--check'], target) + run([sys.executable, method / 'scripts/project-state', 'continuity-state', 'recover', 'TEST-001', '--coordinator-only'], target) + if retained != snapshot(target): raise AssertionError('Core update changed target project state') + locks = [json.loads((method / 'method-core.lock.json').read_text()) for method in methods] + if locks[0] != locks[1] or locks[0]['revision'] != second: raise AssertionError('consumer Core locks differ') + return {'status': 'passed', 'methods': reports, 'core_exports': len(locks[0]['files']), + 'isolated_archive_runtime': True, 'abrupt_exit': 23, 'recovered_original_bytes_and_modes': True, + 'target_state_preserved': True, 'archive_sha256': {p.name:hashlib.sha256(p.read_bytes()).hexdigest() for p in (core_zip, engineering_zip, writing_zip)}, 'core_fixture_revisions': [first, second], 'live_model_requests': False} + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + for name in ('core', 'engineering', 'writing'): parser.add_argument('--' + name, type=Path, required=True) + parser.add_argument('--output', type=Path, required=True) + args = parser.parse_args() + result = verify(args.core.resolve(), args.engineering.resolve(), args.writing.resolve()) + args.output.parent.mkdir(parents=True, exist_ok=True) + args.output.write_text(json.dumps(result, indent=2) + '\n') + print(json.dumps(result)) + + +if __name__ == '__main__': main() diff --git a/tests/fixtures/legacy-project/BACKLOG.md b/tests/fixtures/legacy-project/BACKLOG.md new file mode 100644 index 0000000..dedb6a6 --- /dev/null +++ b/tests/fixtures/legacy-project/BACKLOG.md @@ -0,0 +1,152 @@ +# Backlog +<!-- engineering-method:backlog-document {"schema_version":1,"project_key":"EM","mode":"local"} --> + +This is the canonical local task register until GitHub Issues become writable and canonical. +Keep stable IDs unchanged. Order groups unblocker-first, then priority and dependency order. + +## Status legend + +- `⭕` Open +- `🔄` In progress +- `✅` Complete +- `❌` Blocked + +## Tasks + +<!-- engineering-method:backlog {"schema_version":1,"id":"EM-000","title":"Approve and commit the consolidated plugin design (`877a7ea`).","status":"complete","priority":"P0","parent_id":null,"depends_on":[],"notes":"","updated_at":"1970-01-01T00:00:00Z"} --> +- ✅ `EM-000` **P0** Approve and commit the consolidated plugin design (`877a7ea`). +<!-- engineering-method:backlog {"schema_version":1,"id":"EM-001","title":"Establish the dual-host plugin foundation and provenance controls. Blocks `EM-002` through `EM-005`.","status":"complete","priority":"P0","parent_id":null,"depends_on":[],"notes":"","updated_at":"1970-01-01T00:00:00Z"} --> +- ✅ `EM-001` **P0** Establish the dual-host plugin foundation and provenance controls. Blocks `EM-002` through `EM-005`. + <!-- engineering-method:backlog {"schema_version":1,"id":"EM-001.1","title":"Create compatible Codex and Claude plugin manifests.","status":"complete","priority":"P0","parent_id":"EM-001","depends_on":[],"notes":"","updated_at":"1970-01-01T00:00:00Z"} --> + - ✅ `EM-001.1` **P0** Create compatible Codex and Claude plugin manifests. + <!-- engineering-method:backlog {"schema_version":1,"id":"EM-001.2","title":"Add the dependency-free Python validation and test scaffold.","status":"complete","priority":"P0","parent_id":"EM-001","depends_on":[],"notes":"","updated_at":"1970-01-01T00:00:00Z"} --> + - ✅ `EM-001.2` **P0** Add the dependency-free Python validation and test scaffold. + <!-- engineering-method:backlog {"schema_version":1,"id":"EM-001.3","title":"Pin upstream revisions and implement MIT attribution controls.","status":"complete","priority":"P0","parent_id":"EM-001","depends_on":[],"notes":"","updated_at":"1970-01-01T00:00:00Z"} --> + - ✅ `EM-001.3` **P0** Pin upstream revisions and implement MIT attribution controls. + <!-- engineering-method:backlog {"schema_version":1,"id":"EM-001.4","title":"Add baseline structural validation for both hosts.","status":"complete","priority":"P0","parent_id":"EM-001","depends_on":[],"notes":"","updated_at":"1970-01-01T00:00:00Z"} --> + - ✅ `EM-001.4` **P0** Add baseline structural validation for both hosts. +<!-- engineering-method:backlog {"schema_version":1,"id":"EM-013","title":"Make state checks read-only and verify documentation skill routing","status":"complete","priority":"P0","parent_id":null,"depends_on":[],"notes":"Read-only state-check fix and native routing verified: Codex 5/5, Claude 5/5, OpenCode 2 bounded probes. Corrected native Claude authentication environment after forced config selected different account metadata; 319 tests and independent reviews passed. See docs/verification/EM-013-prepublication.md. No remote publication.","updated_at":"2026-09-16T09:20:15Z"} --> +- ✅ `EM-013` **P0** Make state checks read-only and verify documentation skill routing + - Notes: Read-only state-check fix and native routing verified: Codex 5/5, Claude 5/5, OpenCode 2 bounded probes. Corrected native Claude authentication environment after forced config selected different account metadata; 319 tests and independent reviews passed. See docs/verification/EM-013-prepublication.md. No remote publication. +<!-- engineering-method:backlog {"schema_version":1,"id":"EM-002","title":"Implement durable project state and compact continuity","status":"complete","priority":"P1","parent_id":null,"depends_on":["EM-001"],"notes":"","updated_at":"2026-09-04T14:43:50Z"} --> +- ✅ `EM-002` **P1** Implement durable project state and compact continuity + - Depends on: `EM-001` + <!-- engineering-method:backlog {"schema_version":1,"id":"EM-002.1","title":"Add state models and safe filesystem primitives.","status":"complete","priority":"P1","parent_id":"EM-002","depends_on":[],"notes":"","updated_at":"2026-09-04T14:43:50Z"} --> + - ✅ `EM-002.1` **P1** Add state models and safe filesystem primitives. + <!-- engineering-method:backlog {"schema_version":1,"id":"EM-002.2","title":"Implement stable local backlog parsing, sorting, and archiving.","status":"complete","priority":"P1","parent_id":"EM-002","depends_on":[],"notes":"","updated_at":"2026-09-04T14:43:50Z"} --> + - ✅ `EM-002.2` **P1** Implement stable local backlog parsing, sorting, and archiving. + <!-- engineering-method:backlog {"schema_version":1,"id":"EM-002.3","title":"Maintain the non-duplicative `FEATURES.md` capability inventory.","status":"complete","priority":"P1","parent_id":"EM-002","depends_on":[],"notes":"","updated_at":"2026-09-04T14:43:50Z"} --> + - ✅ `EM-002.3` **P1** Maintain the non-duplicative `FEATURES.md` capability inventory. + <!-- engineering-method:backlog {"schema_version":1,"id":"EM-002.4","title":"Add the testable GitHub boundary.","status":"complete","priority":"P1","parent_id":"EM-002","depends_on":[],"notes":"","updated_at":"2026-09-04T14:43:50Z"} --> + - ✅ `EM-002.4` **P1** Add the testable GitHub boundary. + <!-- engineering-method:backlog {"schema_version":1,"id":"EM-002.5","title":"Implement idempotent issue migration, relationships, cache, and offline reconciliation.","status":"complete","priority":"P1","parent_id":"EM-002","depends_on":[],"notes":"","updated_at":"2026-09-04T14:43:50Z"} --> + - ✅ `EM-002.5` **P1** Implement idempotent issue migration, relationships, cache, and offline reconciliation. + <!-- engineering-method:backlog {"schema_version":1,"id":"EM-002.6","title":"Implement versioned compact-continuity checkpoints and events.","status":"complete","priority":"P1","parent_id":"EM-002","depends_on":[],"notes":"","updated_at":"2026-09-04T14:43:50Z"} --> + - ✅ `EM-002.6` **P1** Implement versioned compact-continuity checkpoints and events. + <!-- engineering-method:backlog {"schema_version":1,"id":"EM-002.7","title":"Wire project-state commands and the `project-backlog` skill.","status":"complete","priority":"P1","parent_id":"EM-002","depends_on":[],"notes":"","updated_at":"2026-09-04T14:43:50Z"} --> + - ✅ `EM-002.7` **P1** Wire project-state commands and the `project-backlog` skill. +<!-- engineering-method:backlog {"schema_version":1,"id":"EM-003","title":"Build the curated, non-overlapping lifecycle and quality skills","status":"complete","priority":"P1","parent_id":null,"depends_on":["EM-001"],"notes":"","updated_at":"2026-09-04T14:43:51Z"} --> +- ✅ `EM-003` **P1** Build the curated, non-overlapping lifecycle and quality skills + - Depends on: `EM-001` + <!-- engineering-method:backlog {"schema_version":1,"id":"EM-003.1","title":"Define exclusive lifecycle contracts and artifact templates.","status":"complete","priority":"P1","parent_id":"EM-003","depends_on":[],"notes":"","updated_at":"2026-09-04T14:43:50Z"} --> + - ✅ `EM-003.1` **P1** Define exclusive lifecycle contracts and artifact templates. + <!-- engineering-method:backlog {"schema_version":1,"id":"EM-003.2","title":"Adapt Spec Kit `specify`, `plan`, `tasks`, and `converge`.","status":"complete","priority":"P1","parent_id":"EM-003","depends_on":[],"notes":"","updated_at":"2026-09-04T14:43:50Z"} --> + - ✅ `EM-003.2` **P1** Adapt Spec Kit `specify`, `plan`, `tasks`, and `converge`. + <!-- engineering-method:backlog {"schema_version":1,"id":"EM-003.3","title":"Adapt OpenSpec `propose`, `apply`, and `archive`.","status":"complete","priority":"P1","parent_id":"EM-003","depends_on":[],"notes":"","updated_at":"2026-09-04T14:43:50Z"} --> + - ✅ `EM-003.3` **P1** Adapt OpenSpec `propose`, `apply`, and `archive`. + <!-- engineering-method:backlog {"schema_version":1,"id":"EM-003.4","title":"Port Superpowers debugging, TDD, and verification.","status":"complete","priority":"P1","parent_id":"EM-003","depends_on":[],"notes":"","updated_at":"2026-09-04T14:43:50Z"} --> + - ✅ `EM-003.4` **P1** Port Superpowers debugging, TDD, and verification. + <!-- engineering-method:backlog {"schema_version":1,"id":"EM-003.5","title":"Port review, worktree, and parallel-dispatch support.","status":"complete","priority":"P1","parent_id":"EM-003","depends_on":[],"notes":"","updated_at":"2026-09-04T14:43:50Z"} --> + - ✅ `EM-003.5` **P1** Port review, worktree, and parallel-dispatch support. + <!-- engineering-method:backlog {"schema_version":1,"id":"EM-003.6","title":"Integrate project-backlog support and collision acceptance.","status":"complete","priority":"P1","parent_id":"EM-003","depends_on":[],"notes":"","updated_at":"2026-09-04T14:43:51Z"} --> + - ✅ `EM-003.6` **P1** Integrate project-backlog support and collision acceptance. +<!-- engineering-method:backlog {"schema_version":1,"id":"EM-004","title":"Add efficient subagent orchestration and the architecture gate","status":"complete","priority":"P1","parent_id":null,"depends_on":["EM-002","EM-003"],"notes":"","updated_at":"2026-09-05T10:52:23Z"} --> +- ✅ `EM-004` **P1** Add efficient subagent orchestration and the architecture gate + - Depends on: `EM-002`, `EM-003` + <!-- engineering-method:backlog {"schema_version":1,"id":"EM-004.1","title":"Add shared model roles, host adapters, and agent-role briefs.","status":"complete","priority":"P1","parent_id":"EM-004","depends_on":[],"notes":"","updated_at":"2026-09-05T10:52:23Z"} --> + - ✅ `EM-004.1` **P1** Add shared model roles, host adapters, and agent-role briefs. + <!-- engineering-method:backlog {"schema_version":1,"id":"EM-004.2","title":"Implement cohesive-slice orchestration with targeted review and evidence-driven fix loops.","status":"complete","priority":"P1","parent_id":"EM-004","depends_on":[],"notes":"","updated_at":"2026-09-05T10:52:23Z"} --> + - ✅ `EM-004.2` **P1** Implement cohesive-slice orchestration with targeted review and evidence-driven fix loops. + <!-- engineering-method:backlog {"schema_version":1,"id":"EM-004.3","title":"Implement evidence-driven defect convergence.","status":"complete","priority":"P1","parent_id":"EM-004","depends_on":[],"notes":"","updated_at":"2026-09-05T10:52:23Z"} --> + - ✅ `EM-004.3` **P1** Implement evidence-driven defect convergence. + <!-- engineering-method:backlog {"schema_version":1,"id":"EM-004.4","title":"Implement design-time and as-built UML analysis under `docs/uml/`.","status":"complete","priority":"P1","parent_id":"EM-004","depends_on":[],"notes":"","updated_at":"2026-09-05T10:52:23Z"} --> + - ✅ `EM-004.4` **P1** Implement design-time and as-built UML analysis under `docs/uml/`. + <!-- engineering-method:backlog {"schema_version":1,"id":"EM-004.5","title":"Add the system-architect integration-test gate.","status":"complete","priority":"P1","parent_id":"EM-004","depends_on":[],"notes":"","updated_at":"2026-09-05T10:52:23Z"} --> + - ✅ `EM-004.5` **P1** Add the system-architect integration-test gate. + <!-- engineering-method:backlog {"schema_version":1,"id":"EM-004.6","title":"Verify recovery across compaction and subagent lifecycle boundaries.","status":"complete","priority":"P1","parent_id":"EM-004","depends_on":[],"notes":"","updated_at":"2026-09-05T10:52:23Z"} --> + - ✅ `EM-004.6` **P1** Verify recovery across compaction and subagent lifecycle boundaries. +<!-- engineering-method:backlog {"schema_version":1,"id":"EM-008","title":"Add source-linked OpenCode skill integration","status":"complete","priority":"P1","parent_id":null,"depends_on":[],"notes":"Implemented and independently reviewed; all 17 shared skills discovered from retained main checkout and bounded DeepSeek skill invocation passed. Installed locally; no remote publication or RAG lifecycle acceptance.","updated_at":"2026-09-11T14:19:43Z"} --> +- ✅ `EM-008` **P1** Add source-linked OpenCode skill integration + - Notes: Implemented and independently reviewed; all 17 shared skills discovered from retained main checkout and bounded DeepSeek skill invocation passed. Installed locally; no remote publication or RAG lifecycle acceptance. +<!-- engineering-method:backlog {"schema_version":1,"id":"EM-009","title":"Publish OpenCode integration as patch release 0.1.1","status":"complete","priority":"P1","parent_id":null,"depends_on":[],"notes":"Published v0.1.1 from b6bff25; 317 tests, reproducible package and isolated native installs passed. Downloaded GitHub asset matches c96f758a14c4ed3fd2c5b457d6c97beee3c4a37b3262e7de70a7e11e96a1a448.","updated_at":"2026-09-11T15:11:54Z"} --> +- ✅ `EM-009` **P1** Publish OpenCode integration as patch release 0.1.1 + - Notes: Published v0.1.1 from b6bff25; 317 tests, reproducible package and isolated native installs passed. Downloaded GitHub asset matches c96f758a14c4ed3fd2c5b457d6c97beee3c4a37b3262e7de70a7e11e96a1a448. +<!-- engineering-method:backlog {"schema_version":1,"id":"EM-010","title":"Add scale-aware documentation and reader-oriented writing skills","status":"complete","priority":"P1","parent_id":null,"depends_on":[],"notes":"Eight original skills, writing-depth and reader-oriented-output policies, curse-of-knowledge filter, five documentation templates, handoff graph and trigger matrix extension. Local suite, validators and Claude strict validation passed; native routing evaluation of the new cases not run (paid); OpenCode discovery of new skills not re-verified.","updated_at":"2026-09-16T07:48:30Z"} --> +- ✅ `EM-010` **P1** Add scale-aware documentation and reader-oriented writing skills + - Notes: Eight original skills, writing-depth and reader-oriented-output policies, curse-of-knowledge filter, five documentation templates, handoff graph and trigger matrix extension. Local suite, validators and Claude strict validation passed; native routing evaluation of the new cases not run (paid); OpenCode discovery of new skills not re-verified. + <!-- engineering-method:backlog {"schema_version":1,"id":"EM-010.1","title":"Add writing-depth and reader-oriented-output shared policies and documentation templates.","status":"complete","priority":"P1","parent_id":"EM-010","depends_on":[],"notes":"","updated_at":"2026-09-16T07:48:29Z"} --> + - ✅ `EM-010.1` **P1** Add writing-depth and reader-oriented-output shared policies and documentation templates. + <!-- engineering-method:backlog {"schema_version":1,"id":"EM-010.2","title":"Add the documentation-planning, documentation-authoring and documentation-review lifecycle skills.","status":"complete","priority":"P1","parent_id":"EM-010","depends_on":[],"notes":"","updated_at":"2026-09-16T07:48:29Z"} --> + - ✅ `EM-010.2` **P1** Add the documentation-planning, documentation-authoring and documentation-review lifecycle skills. + <!-- engineering-method:backlog {"schema_version":1,"id":"EM-010.3","title":"Add explaining-concepts, writing-procedures, empathic-troubleshooting, terminology-guard and visual-placeholders supporting skills.","status":"complete","priority":"P1","parent_id":"EM-010","depends_on":[],"notes":"","updated_at":"2026-09-16T07:48:29Z"} --> + - ✅ `EM-010.3` **P1** Add explaining-concepts, writing-procedures, empathic-troubleshooting, terminology-guard and visual-placeholders supporting skills. + <!-- engineering-method:backlog {"schema_version":1,"id":"EM-010.4","title":"Extend handoff graph, trigger matrix, contract tests and host adapters.","status":"complete","priority":"P1","parent_id":"EM-010","depends_on":[],"notes":"","updated_at":"2026-09-16T07:48:29Z"} --> + - ✅ `EM-010.4` **P1** Extend handoff graph, trigger matrix, contract tests and host adapters. + <!-- engineering-method:backlog {"schema_version":1,"id":"EM-010.5","title":"Record sources, update README, usage, features and verification evidence.","status":"complete","priority":"P1","parent_id":"EM-010","depends_on":[],"notes":"","updated_at":"2026-09-16T07:48:29Z"} --> + - ✅ `EM-010.5` **P1** Record sources, update README, usage, features and verification evidence. +<!-- engineering-method:backlog {"schema_version":1,"id":"EM-011","title":"Integrate adapted Humanizer drafting constraints into medium and large documentation writing","status":"complete","priority":"P1","parent_id":null,"depends_on":["EM-010"],"notes":"Humanizer drafting rules loaded before medium/large authoring; contextual preservation rules, provenance and independent review verified. See docs/verification/EM-011-humanizer-drafting.md. Native host routing and installation are not claimed.","updated_at":"2026-09-16T08:07:31Z"} --> +- ✅ `EM-011` **P1** Integrate adapted Humanizer drafting constraints into medium and large documentation writing + - Depends on: `EM-010` + - Notes: Humanizer drafting rules loaded before medium/large authoring; contextual preservation rules, provenance and independent review verified. See docs/verification/EM-011-humanizer-drafting.md. Native host routing and installation are not claimed. +<!-- engineering-method:backlog {"schema_version":1,"id":"EM-012","title":"Add local Quarto and Typst PDF export for documentation","status":"complete","priority":"P1","parent_id":null,"depends_on":["EM-011"],"notes":"Original Quarto/Typst manual template and export skill integrated; native en/de and reordered 120-row table checks passed, source bytes preserved, pages visually inspected. Independent review Ready. See docs/verification/EM-012-quarto-pdf.md. No remote publication or host-routing acceptance.","updated_at":"2026-09-16T08:29:21Z"} --> +- ✅ `EM-012` **P1** Add local Quarto and Typst PDF export for documentation + - Depends on: `EM-011` + - Notes: Original Quarto/Typst manual template and export skill integrated; native en/de and reordered 120-row table checks passed, source bytes preserved, pages visually inspected. Independent review Ready. See docs/verification/EM-012-quarto-pdf.md. No remote publication or host-routing acceptance. +<!-- engineering-method:backlog {"schema_version":1,"id":"EM-014","title":"Integrate development and system-deliverable playbooks into engineering lifecycles","status":"complete","priority":"P1","parent_id":null,"depends_on":[],"notes":"Two supporting playbook skills and need/evidence policy integrated into Spec Kit and OpenSpec. 319 tests, validators, pinned-source audit, independent review, reproducible package and disposable Claude/Codex installation passed. No publication, persistent installation or native routing evaluation. See docs/verification/EM-014-playbooks.md.","updated_at":"2026-09-17T07:16:38Z"} --> +- ✅ `EM-014` **P1** Integrate development and system-deliverable playbooks into engineering lifecycles + - Notes: Two supporting playbook skills and need/evidence policy integrated into Spec Kit and OpenSpec. 319 tests, validators, pinned-source audit, independent review, reproducible package and disposable Claude/Codex installation passed. No publication, persistent installation or native routing evaluation. See docs/verification/EM-014-playbooks.md. +<!-- engineering-method:backlog {"schema_version":1,"id":"EM-015","title":"Publish documentation, PDF, playbook and state-check work as minor release 0.2.0","status":"complete","priority":"P1","parent_id":null,"depends_on":["EM-013","EM-014"],"notes":"Published v0.2.0 from a050f0e; 319 tests, validators and reproducible package passed. Downloaded GitHub asset matches 3549be2d733267397b868d1f2b2aa21cce758cd2baf31ade482f644fd12a5e2c.","updated_at":"2026-09-17T08:12:00Z"} --> +- ✅ `EM-015` **P1** Publish documentation, PDF, playbook and state-check work as minor release 0.2.0 + - Depends on: `EM-013`, `EM-014` + - Notes: Published v0.2.0 from a050f0e; 319 tests, validators and reproducible package passed. Downloaded GitHub asset matches 3549be2d733267397b868d1f2b2aa21cce758cd2baf31ade482f644fd12a5e2c. +<!-- engineering-method:backlog {"schema_version":1,"id":"EM-016","title":"Refine the documentation PDF template with professional A4 typography","status":"complete","priority":"P1","parent_id":null,"depends_on":["EM-012"],"notes":"Professional A4 template and native PDF checks pass. Authorized for publication in v0.2.1. A stale installed wrapper created closed GitHub Issues #82-134; they remain closed and were not deleted.","updated_at":"2026-09-18T16:29:51Z"} --> +- ✅ `EM-016` **P1** Refine the documentation PDF template with professional A4 typography + - Depends on: `EM-012` + - Notes: Professional A4 template and native PDF checks pass. Authorized for publication in v0.2.1. A stale installed wrapper created closed GitHub Issues #82-134; they remain closed and were not deleted. +<!-- engineering-method:backlog {"schema_version":1,"id":"EM-017","title":"Publish the professional PDF template as patch release 0.2.1","status":"complete","priority":"P1","parent_id":null,"depends_on":["EM-016"],"notes":"Published stable Latest v0.2.1 from 49aa3c6; 319 tests, native PDF checks, validators, reproducible 256-file package and clean installs passed. Downloaded asset matches 2a0d0b6d520d509276c7d04d80b83a43a5aada78132d1ae48461c03fe3c21693.","updated_at":"2026-09-18T16:32:15Z"} --> +- ✅ `EM-017` **P1** Publish the professional PDF template as patch release 0.2.1 + - Depends on: `EM-016` + - Notes: Published stable Latest v0.2.1 from 49aa3c6; 319 tests, native PDF checks, validators, reproducible 256-file package and clean installs passed. Downloaded asset matches 2a0d0b6d520d509276c7d04d80b83a43a5aada78132d1ae48461c03fe3c21693. +<!-- engineering-method:backlog {"schema_version":1,"id":"EM-005","title":"Validate, document, and package the complete plugin","status":"complete","priority":"P2","parent_id":null,"depends_on":["EM-001","EM-004"],"notes":"All nine original gate criteria accepted on 0784c79 with explicit same-package evidence reuse, Claude checkpoint supplement and independently verified ownership metadata correction. Failed reports preserved; see docs/verification/EM-005-acceptance.md. Accidental Issues #1-38 removed with approval; local backlog remains canonical.","updated_at":"2026-09-05T19:11:37Z"} --> +- ✅ `EM-005` **P2** Validate, document, and package the complete plugin + - Depends on: `EM-001`, `EM-004` + - Notes: All nine original gate criteria accepted on 0784c79 with explicit same-package evidence reuse, Claude checkpoint supplement and independently verified ownership metadata correction. Failed reports preserved; see docs/verification/EM-005-acceptance.md. Accidental Issues #1-38 removed with approval; local backlog remains canonical. + <!-- engineering-method:backlog {"schema_version":1,"id":"EM-005.1","title":"Finalize platform adapters and marketplace metadata.","status":"complete","priority":"P2","parent_id":"EM-005","depends_on":[],"notes":"","updated_at":"2026-09-05T11:04:23Z"} --> + - ✅ `EM-005.1` **P2** Finalize platform adapters and marketplace metadata. + <!-- engineering-method:backlog {"schema_version":1,"id":"EM-005.2","title":"Add Codex/Claude trigger, collision, fallback, and workflow evaluations.","status":"complete","priority":"P2","parent_id":"EM-005","depends_on":[],"notes":"All 12 routing cases passed on each host: gpt-6-astra low and claude-fable-5-1 low, package 0784c79.","updated_at":"2026-09-05T19:11:37Z"} --> + - ✅ `EM-005.2` **P2** Add Codex/Claude trigger, collision, fallback, and workflow evaluations. + - Notes: All 12 routing cases passed on each host: gpt-6-astra low and claude-fable-5-1 low, package 0784c79. + <!-- engineering-method:backlog {"schema_version":1,"id":"EM-005.3","title":"Execute the large-feature architecture fixture on both hosts.","status":"complete","priority":"P2","parent_id":"EM-005","depends_on":[],"notes":"All ten architecture phases and original native-review/hash/integration assertions passed on both hosts; Claude required the documented invocation supplement and one clerical report correction. See docs/verification/EM-005-acceptance.md.","updated_at":"2026-09-05T19:11:37Z"} --> + - ✅ `EM-005.3` **P2** Execute the large-feature architecture fixture on both hosts. + - Notes: All ten architecture phases and original native-review/hash/integration assertions passed on both hosts; Claude required the documented invocation supplement and one clerical report correction. See docs/verification/EM-005-acceptance.md. + <!-- engineering-method:backlog {"schema_version":1,"id":"EM-005.4","title":"Complete static, package, and clean-install validation.","status":"complete","priority":"P2","parent_id":"EM-005","depends_on":[],"notes":"308 tests, both validators, provenance, reproducible 188-file package and both native clean installs passed on 0784c79.","updated_at":"2026-09-05T19:11:37Z"} --> + - ✅ `EM-005.4` **P2** Complete static, package, and clean-install validation. + - Notes: 308 tests, both validators, provenance, reproducible 188-file package and both native clean installs passed on 0784c79. + <!-- engineering-method:backlog {"schema_version":1,"id":"EM-005.5","title":"Write and verify the public README and third-party notices.","status":"complete","priority":"P2","parent_id":"EM-005","depends_on":[],"notes":"","updated_at":"2026-09-05T11:04:23Z"} --> + - ✅ `EM-005.5` **P2** Write and verify the public README and third-party notices. + <!-- engineering-method:backlog {"schema_version":1,"id":"EM-005.6","title":"Run the system-architect release gate.","status":"complete","priority":"P2","parent_id":"EM-005","depends_on":[],"notes":"Independent Astra low reviewer accepted complete original gate coverage with explicit evidence reuse; no unresolved Critical or Important findings. Not a successful single release-check invocation.","updated_at":"2026-09-05T19:11:37Z"} --> + - ✅ `EM-005.6` **P2** Run the system-architect release gate. + - Notes: Independent Astra low reviewer accepted complete original gate coverage with explicit evidence reuse; no unresolved Critical or Important findings. Not a successful single release-check invocation. + <!-- engineering-method:backlog {"schema_version":1,"id":"EM-005.7","title":"Apply shared proportionality and an effort brake to every skill.","status":"complete","priority":"P2","parent_id":"EM-005","depends_on":[],"notes":"User-approved scope correction; see docs/verification/EM-005-completion-path.md for remaining release evidence.","updated_at":"2026-09-05T13:22:56Z"} --> + - ✅ `EM-005.7` **P2** Apply shared proportionality and an effort brake to every skill. + - Notes: User-approved scope correction; see docs/verification/EM-005-completion-path.md for remaining release evidence. + <!-- engineering-method:backlog {"schema_version":1,"id":"EM-005.8","title":"Capture native Codex reviewer replies with independently confirmed scope","status":"complete","priority":"P2","parent_id":"EM-005","depends_on":[],"notes":"305 local tests, one independent bounded code review and one successful native Codex capture probe (90-second maximum). Existing release assertions unchanged; full architecture/release acceptance remains open.","updated_at":"2026-09-05T14:49:20Z"} --> + - ✅ `EM-005.8` **P2** Capture native Codex reviewer replies with independently confirmed scope + - Notes: 305 local tests, one independent bounded code review and one successful native Codex capture probe (90-second maximum). Existing release assertions unchanged; full architecture/release acceptance remains open. +<!-- engineering-method:backlog {"schema_version":1,"id":"EM-006","title":"Publish the documented public prerelease with bounded verification","status":"complete","priority":"P2","parent_id":null,"depends_on":[],"notes":"Published phense/engineering-method and v0.1.0-rc.1 at 9ff0bdd. Verified public visibility, tag, prerelease flag, downloaded ZIP/checksum and GitHub install/update/disable/removal on both hosts. EM-005 remains incomplete; no issue migration.","updated_at":"2026-09-05T14:13:52Z"} --> +- ✅ `EM-006` **P2** Publish the documented public prerelease with bounded verification + - Notes: Published phense/engineering-method and v0.1.0-rc.1 at 9ff0bdd. Verified public visibility, tag, prerelease flag, downloaded ZIP/checksum and GitHub install/update/disable/removal on both hosts. EM-005 remains incomplete; no issue migration. +<!-- engineering-method:backlog {"schema_version":1,"id":"EM-007","title":"Publish stable version 0.1.0 and update public documentation","status":"complete","priority":"P2","parent_id":null,"depends_on":["EM-005"],"notes":"Published v0.1.0 at e9f5130 as stable Latest with checked ZIP and SHA256SUMS. 308 tests, validators, provenance, reproducible packaging, both clean installs, downloaded bytes and GitHub/main plus fixed-tag installs verified. Prior rc.1 unchanged; no issue migration.","updated_at":"2026-09-05T19:27:21Z"} --> +- ✅ `EM-007` **P2** Publish stable version 0.1.0 and update public documentation + - Depends on: `EM-005` + - Notes: Published v0.1.0 at e9f5130 as stable Latest with checked ZIP and SHA256SUMS. 308 tests, validators, provenance, reproducible packaging, both clean installs, downloaded bytes and GitHub/main plus fixed-tag installs verified. Prior rc.1 unchanged; no issue migration. diff --git a/tests/fixtures/legacy-project/FEATURES.md b/tests/fixtures/legacy-project/FEATURES.md new file mode 100644 index 0000000..ca7c5b0 --- /dev/null +++ b/tests/fixtures/legacy-project/FEATURES.md @@ -0,0 +1,73 @@ +# Features + +This inventory records implemented, changed, and historically removed capabilities. Planned work belongs only in `BACKLOG.md`. + +<!-- engineering-method:feature {"schema_version":1,"id":"F-001","name":"Dual-host foundation","summary":"Shared plugin identity, MIT licensing, portable validation and pinned-source provenance controls.","status":"available","related_backlog_ids":["EM-001"],"updated_at":"2026-09-05T10:52:23Z"} --> +## `F-001` Dual-host foundation + +- Status: available +- Summary: Shared plugin identity, MIT licensing, portable validation and pinned-source provenance controls. +- Related backlog: `EM-001` + +<!-- engineering-method:feature {"schema_version":1,"id":"F-002","name":"Durable project state","summary":"Blocker-first local backlog, feature inventory, GitHub migration and native relationships, offline queue and compact recovery. State checks are read-only even with a writable remote; migration requires an explicitly authorized backlog-to-issues migrate command.","status":"available","related_backlog_ids":["EM-002"],"updated_at":"2026-09-16T08:51:39Z"} --> +## `F-002` Durable project state + +- Status: available +- Summary: Blocker-first local backlog, feature inventory, GitHub migration and native relationships, offline queue and compact recovery. State checks are read-only even with a writable remote; migration requires an explicitly authorized backlog-to-issues migrate command. +- Related backlog: `EM-002` + +<!-- engineering-method:feature {"schema_version":1,"id":"F-003","name":"Exclusive workflow skills","summary":"Twenty-five shared lifecycle and quality skills with artifact-specific handoffs: the original seventeen engineering skills plus eight documentation and reader-oriented writing skills added by EM-010. All 12 engineering routing cases passed on both hosts for 0784c79; the three documentation routing cases have contract-test coverage only.","status":"changed","related_backlog_ids":["EM-003"],"updated_at":"2026-09-16T07:47:28Z"} --> +## `F-003` Exclusive workflow skills + +- Status: changed +- Summary: Twenty-five shared lifecycle and quality skills with artifact-specific handoffs: the original seventeen engineering skills plus eight documentation and reader-oriented writing skills added by EM-010. All 12 engineering routing cases passed on both hosts for 0784c79; the three documentation routing cases have contract-test coverage only. +- Related backlog: `EM-003` + +<!-- engineering-method:feature {"schema_version":1,"id":"F-004","name":"Orchestration and architecture gates","summary":"Cohesive slices, protected continuity artifacts, independent review and evidence-driven fixes; relevant Mermaid views and executable checkout success/recovery acceptance. Mermaid sources are semantically checked, not rendered.","status":"available","related_backlog_ids":["EM-004"],"updated_at":"2026-09-05T10:52:23Z"} --> +## `F-004` Orchestration and architecture gates + +- Status: available +- Summary: Cohesive slices, protected continuity artifacts, independent review and evidence-driven fixes; relevant Mermaid views and executable checkout success/recovery acceptance. Mermaid sources are semantically checked, not rendered. +- Related backlog: `EM-004` + +<!-- engineering-method:feature {"schema_version":1,"id":"F-005","name":"Proportionate execution guidance","summary":"Every skill references shared local-check-first, evidence-reuse, focused-review and effort-brake instructions. Behavioral compliance is not guaranteed across arbitrary prompts.","status":"available","related_backlog_ids":["EM-005.7"],"updated_at":"2026-09-05T19:11:37Z"} --> +## `F-005` Proportionate execution guidance + +- Status: available +- Summary: Every skill references shared local-check-first, evidence-reuse, focused-review and effort-brake instructions. Behavioral compliance is not guaranteed across arbitrary prompts. +- Related backlog: `EM-005.7` + +<!-- engineering-method:feature {"schema_version":1,"id":"F-006","name":"Stable distribution and English documentation","summary":"Stable v0.1.0 on public GitHub with English documentation, reproducible package, checksum and verified dual-host main/tag installation. Original gate coverage accepted with the documented EM-005 evidence reuse and limits; historical rc.1 remains available.","status":"available","related_backlog_ids":["EM-006","EM-007"],"updated_at":"2026-09-05T19:27:21Z"} --> +## `F-006` Stable distribution and English documentation + +- Status: available +- Summary: Stable v0.1.0 on public GitHub with English documentation, reproducible package, checksum and verified dual-host main/tag installation. Original gate coverage accepted with the documented EM-005 evidence reuse and limits; historical rc.1 remains available. +- Related backlog: `EM-006`, `EM-007` + +<!-- engineering-method:feature {"schema_version":1,"id":"F-007","name":"Native OpenCode skill integration","summary":"Source-linked additive skill and adapter loading with guarded reversible installation; 17 skills discovered and bounded DeepSeek skill use verified on OpenCode 1.18.30. Full lifecycle and RAG hooks are outside this acceptance.","status":"available","related_backlog_ids":["EM-008"],"updated_at":"2026-09-11T14:19:43Z"} --> +## `F-007` Native OpenCode skill integration + +- Status: available +- Summary: Source-linked additive skill and adapter loading with guarded reversible installation; 17 skills discovered and bounded DeepSeek skill use verified on OpenCode 1.18.30. Full lifecycle and RAG hooks are outside this acceptance. +- Related backlog: `EM-008` + +<!-- engineering-method:feature {"schema_version":1,"id":"F-008","name":"Scale-aware documentation and reader-oriented writing","summary":"Writing-depth scale decision (small, medium, large); documentation-planning, documentation-authoring and documentation-review lifecycle with plan, chunk manifest, glossary, asset manifest and review templates under docs/writing; didactic skills explaining-concepts, writing-procedures and empathic-troubleshooting applied to documentation and ordinary replies; terminology-guard and visual-placeholders; human-prose-drafting (adapted from Humanizer, MIT) applied while drafting medium and large texts. Contract tests and validators pass; five bounded native routing cases pass on both Codex and Claude, with OpenCode pre-draft Humanizer invocation verified. These probes do not claim full document quality.","status":"available","related_backlog_ids":["EM-009","EM-010","EM-011","EM-013"],"updated_at":"2026-09-16T09:47:44Z"} --> +## `F-008` Scale-aware documentation and reader-oriented writing + +- Status: available +- Summary: Writing-depth scale decision (small, medium, large); documentation-planning, documentation-authoring and documentation-review lifecycle with plan, chunk manifest, glossary, asset manifest and review templates under docs/writing; didactic skills explaining-concepts, writing-procedures and empathic-troubleshooting applied to documentation and ordinary replies; terminology-guard and visual-placeholders; human-prose-drafting (adapted from Humanizer, MIT) applied while drafting medium and large texts. Contract tests and validators pass; five bounded native routing cases pass on both Codex and Claude, with OpenCode pre-draft Humanizer invocation verified. These probes do not claim full document quality. +- Related backlog: `EM-009`, `EM-010`, `EM-011`, `EM-013` + +<!-- engineering-method:feature {"schema_version":1,"id":"F-009","name":"Local Markdown book PDF export","summary":"Optional documentation-pdf skill with a professional A4 Quarto/Typst template: dark-navy editorial hierarchy, separate cover and contents, 12 pt body text, ordered Markdown chapters, linked contents and current/total page numbers. Native macOS English, German and long-table checks pass; PDF skill selection is verified on Codex, Claude and OpenCode. Rendering remains local.","status":"changed","related_backlog_ids":["EM-012","EM-013","EM-016"],"updated_at":"2026-09-18T16:29:51Z"} --> +## `F-009` Local Markdown book PDF export + +- Status: changed +- Summary: Optional documentation-pdf skill with a professional A4 Quarto/Typst template: dark-navy editorial hierarchy, separate cover and contents, 12 pt body text, ordered Markdown chapters, linked contents and current/total page numbers. Native macOS English, German and long-table checks pass; PDF skill selection is verified on Codex, Claude and OpenCode. Rendering remains local. +- Related backlog: `EM-012`, `EM-013`, `EM-016` + +<!-- engineering-method:feature {"schema_version":1,"id":"F-010","name":"Engineering playbook authoring and acceptance","summary":"Two supporting skills distinguish development-operation and system-deliverable playbooks, with phase-specific need assessment, authoring/review templates, interruption and rollback paths, and separate current review and rehearsal evidence. Local contracts, independent instruction scenarios and disposable Claude/Codex installation verified; no native-host routing or operational rehearsal claimed.","status":"available","related_backlog_ids":["EM-014"],"updated_at":"2026-09-17T07:16:38Z"} --> +## `F-010` Engineering playbook authoring and acceptance + +- Status: available +- Summary: Two supporting skills distinguish development-operation and system-deliverable playbooks, with phase-specific need assessment, authoring/review templates, interruption and rollback paths, and separate current review and rehearsal evidence. Local contracts, independent instruction scenarios and disposable Claude/Codex installation verified; no native-host routing or operational rehearsal claimed. +- Related backlog: `EM-014` diff --git a/tests/fixtures/trigger-cases/matrix.json b/tests/fixtures/trigger-cases/matrix.json index 90fc35d..38ad8a1 100644 --- a/tests/fixtures/trigger-cases/matrix.json +++ b/tests/fixtures/trigger-cases/matrix.json @@ -232,121 +232,6 @@ "next": "complete" } }, - { - "id": "standalone-document", - "request": "Write one how-to guide for an existing feature for a single reader group.", - "primary": "documentation-authoring", - "supporting": [ - "project-backlog", - "writing-procedures", - "human-prose-drafting", - "terminology-guard", - "verification-before-completion" - ], - "prohibited": [ - "native-focused-edit", - "systematic-debugging", - "openspec-propose", - "speckit-specify", - "documentation-planning" - ], - "handoff": { - "consumes": [ - "standalone document request", - "defined reader and subject version" - ], - "produces": [ - "one document with chunk frontmatter and recorded self-review" - ], - "next": "verification-before-completion" - } - }, - { - "id": "documentation-set", - "request": "Create a multi-chapter user manual with several reader groups that must share terminology and screenshots.", - "primary": "documentation-planning", - "supporting": [ - "project-backlog", - "terminology-guard", - "visual-placeholders", - "verification-before-completion" - ], - "prohibited": [ - "native-focused-edit", - "systematic-debugging", - "openspec-propose", - "speckit-specify", - "documentation-authoring" - ], - "handoff": { - "consumes": [ - "documentation set request", - "existing material and subject version" - ], - "produces": [ - "docs/writing/<doc-id>/plan.md", - "docs/writing/<doc-id>/glossary.md", - "docs/writing/<doc-id>/assets.md" - ], - "next": "documentation-authoring" - } - }, - { - "id": "existing-documentation-plan", - "request": "Continue a documentation set whose plan and manifest are complete and whose chunks are not yet drafted.", - "primary": "documentation-authoring", - "supporting": [ - "project-backlog", - "explaining-concepts", - "writing-procedures", - "empathic-troubleshooting", - "human-prose-drafting", - "terminology-guard", - "visual-placeholders" - ], - "prohibited": [ - "native-focused-edit", - "systematic-debugging", - "openspec-propose", - "speckit-specify", - "documentation-planning" - ], - "handoff": { - "consumes": [ - "docs/writing/<doc-id>/plan.md", - "docs/writing/<doc-id>/glossary.md" - ], - "produces": [ - "drafted chunk files under the content root" - ], - "next": "documentation-review" - } - }, - { - "id": "documentation-pdf", - "request": "Export reviewed Markdown chapters into one local PDF with a reusable design, table of contents and page numbers.", - "primary": "documentation-pdf", - "supporting": [ - "verification-before-completion" - ], - "prohibited": [ - "native-focused-edit", - "documentation-authoring", - "documentation-planning", - "systematic-debugging", - "speckit-specify", - "openspec-propose" - ], - "handoff": { - "consumes": [ - "reviewed Markdown and accepted chapter order" - ], - "produces": [ - "local PDF and export verification" - ], - "next": "verification-before-completion" - } - }, { "id": "playbook-system-requirement", "request": "Specify a new data-import service. Operators must recover interrupted imports and restore backups before its first production launch; no incident has happened yet. Identify which playbooks belong to the delivered system.", diff --git a/tests/test_backlog.py b/tests/test_backlog.py index d4049e9..f4c11b1 100644 --- a/tests/test_backlog.py +++ b/tests/test_backlog.py @@ -83,7 +83,7 @@ def test_round_trip_preserves_stable_ids_across_status_and_priority_changes(self self.assertEqual(loaded.items[1].parent_id, "EM-001") def test_loads_the_existing_backlog_without_changing_its_stable_ids_or_meanings(self) -> None: - root = Path(__file__).resolve().parents[1] + root = Path(__file__).resolve().parent / "fixtures/legacy-project" legacy = load_backlog(root / "BACKLOG.md") with tempfile.TemporaryDirectory() as temporary: rendered_path = Path(temporary) / "BACKLOG.md" diff --git a/tests/test_core_sync.py b/tests/test_core_sync.py new file mode 100644 index 0000000..41f6fb7 --- /dev/null +++ b/tests/test_core_sync.py @@ -0,0 +1,213 @@ +"""Exercise real sync boundaries: modes, overwrite protection and recovery.""" +import importlib.util +import json +import os +from pathlib import Path +import subprocess +import tempfile +import unittest +from unittest.mock import patch +ROOT = Path(__file__).resolve().parents[1] + +class CoreSyncTests(unittest.TestCase): + def setUp(self): + self.tmp = tempfile.TemporaryDirectory(prefix='method-sync-');self.addCleanup(self.tmp.cleanup) + self.base = Path(self.tmp.name);self.source = self.base/'source';self.source.mkdir() + self.target = self.base/'target';self.target.mkdir() + subprocess.run(['git','init','-q','-b','main',str(self.source)],check=True) + for key,value in [('user.name','Sync Test'),('user.email','sync@example.invalid')]: self.git('config',key,value) + self.put('shared/platform/codex.md',b'adapter v1\n') + self.put('scripts/project-state',b'#!/usr/bin/env python3\nprint("state")\n',0o755) + self.manifest(['scripts/project-state','shared/platform/codex.md']);self.commit() + def put(self,name,data,mode=0o644): + p=self.source/name;p.parent.mkdir(parents=True,exist_ok=True);p.write_bytes(data);p.chmod(mode) + def manifest(self,exports): + self.put('method-core.json',json.dumps({'schema_version':1,'name':'method-core','version':'0.1.0','exports':exports}).encode()) + def git(self,*args): + return subprocess.check_output(['git','-C',str(self.source),*args],stderr=subprocess.STDOUT).decode().strip() + def commit(self): + self.git('add','.');self.git('commit','-qm','fixture');return self.git('rev-parse','HEAD') + def sync(self,*args): + return subprocess.run([os.sys.executable,str(ROOT/'scripts/sync-core'),'--target-root',str(self.target),*args],capture_output=True,text=True) + def install(self): + r=self.sync('--source-root',str(self.source));self.assertEqual(0,r.returncode,r.stdout+r.stderr) + def test_immutable_copy_modes_and_offline_drift_check(self): + # Dropping execute bits or accepting offline tampering breaks installed commands. + self.install() + self.assertEqual(b'adapter v1\n',(self.target/'shared/platform/codex.md').read_bytes()) + self.assertEqual(0o755,(self.target/'scripts/project-state').stat().st_mode&0o777) + self.assertEqual(0,self.sync('--check').returncode) + (self.target/'shared/platform/codex.md').write_text('locally edited') + self.assertNotEqual(0,self.sync('--check').returncode) + before=(self.target/'method-core.lock.json').read_bytes() + self.assertNotEqual(0,self.sync('--source-root',str(self.source)).returncode) + self.assertEqual('locally edited',(self.target/'shared/platform/codex.md').read_text()) + self.assertEqual(before,(self.target/'method-core.lock.json').read_bytes()) + def test_dirty_source_refused_and_explicit_old_revision_can_restore(self): + self.install();old=self.git('rev-parse','HEAD');self.put('shared/platform/codex.md',b'v2\n') + self.assertNotEqual(0,self.sync('--source-root',str(self.source)).returncode) + self.commit();self.install();self.assertEqual(b'v2\n',(self.target/'shared/platform/codex.md').read_bytes()) + r=self.sync('--source-root',str(self.source),'--revision',old) + self.assertEqual(0,r.returncode,r.stdout+r.stderr) + self.assertEqual(b'adapter v1\n',(self.target/'shared/platform/codex.md').read_bytes()) + def test_unowned_conflicting_file_and_symlink_are_preserved(self): + p=self.target/'scripts/project-state';p.parent.mkdir();p.write_text('user-owned') + self.assertNotEqual(0,self.sync('--source-root',str(self.source)).returncode) + self.assertEqual('user-owned',p.read_text());self.assertFalse((self.target/'method-core.lock.json').exists()) + p.unlink();outside=self.base/'outside';outside.write_text('keep');p.symlink_to(outside) + self.assertNotEqual(0,self.sync('--source-root',str(self.source)).returncode) + self.assertEqual('keep',outside.read_text()) + def test_unsafe_or_duplicate_export_refused_before_writing(self): + for exports in [['../outside'],['scripts/project-state','scripts/project-state'],['/absolute']]: + self.manifest(exports);self.commit();self.assertNotEqual(0,self.sync('--source-root',str(self.source)).returncode) + self.assertEqual([],list(self.target.iterdir())) + def test_malformed_lock_and_mode_drift_are_not_overwritten(self): + self.install();(self.target/'scripts/project-state').chmod(0o644) + self.assertNotEqual(0,self.sync('--check').returncode) + self.assertNotEqual(0,self.sync('--source-root',str(self.source)).returncode) + (self.target/'method-core.lock.json').write_text('{"files": []}') + self.assertNotEqual(0,self.sync('--check').returncode) + def test_update_adds_and_removes_only_owned_exports(self): + self.install();self.put('new.txt',b'new');self.manifest(['new.txt','scripts/project-state']);self.commit();self.install() + self.assertFalse((self.target/'shared/platform/codex.md').exists());self.assertEqual(b'new',(self.target/'new.txt').read_bytes()) + self.assertEqual(0,self.sync('--check').returncode) + def test_failed_write_restores_old_files_lock_and_permissions(self): + # A disk failure between managed writes must leave the installed package usable. + self.install();old=(self.target/'method-core.lock.json').read_bytes() + self.put('shared/platform/codex.md',b'v2\n');self.commit() + spec=importlib.util.spec_from_file_location('core_sync_under_test',ROOT/'scripts/method_core.py') + module=importlib.util.module_from_spec(spec);spec.loader.exec_module(module) + replace=os.replace;calls=0 + def fail_once(src,dst): + nonlocal calls + calls+=1 + if calls==2: raise OSError('injected write failure') + return replace(src,dst) + with patch.object(module.os,'replace',side_effect=fail_once): + with self.assertRaisesRegex(OSError,'injected'): module.synchronize(self.source,self.target) + self.assertEqual(old,(self.target/'method-core.lock.json').read_bytes()) + self.assertEqual(b'adapter v1\n',(self.target/'shared/platform/codex.md').read_bytes()) + self.assertEqual(0o755,(self.target/'scripts/project-state').stat().st_mode&0o777) + self.assertEqual(0,self.sync('--check').returncode);self.install() + @unittest.skipUnless(os.name == 'posix' and os.geteuid() != 0, 'requires enforced POSIX directory permissions') + def test_unwritable_unchanged_path_does_not_abort_prior_rollback(self): + self.install();old=(self.target/'method-core.lock.json').read_bytes() + self.put('scripts/project-state',b'updated state\n',0o755) + self.put('shared/platform/codex.md',b'updated adapter\n');self.commit() + locked=self.target/'shared/platform';locked.chmod(0o555) + try: + self.assertNotEqual(0,self.sync('--source-root',str(self.source)).returncode) + finally: locked.chmod(0o755) + self.assertEqual(b'#!/usr/bin/env python3\nprint("state")\n',(self.target/'scripts/project-state').read_bytes()) + self.assertEqual(old,(self.target/'method-core.lock.json').read_bytes()) + self.assertEqual(0,self.sync('--check').returncode);self.install() + + def test_keyboard_interrupt_restores_the_installed_version(self): + self.install();old=(self.target/'method-core.lock.json').read_bytes() + self.put('scripts/project-state',b'updated state\n',0o755);self.commit() + spec=importlib.util.spec_from_file_location('core_sync_interrupted',ROOT/'scripts/method_core.py') + module=importlib.util.module_from_spec(spec);spec.loader.exec_module(module) + replace=os.replace;calls=0 + def interrupt_once(src,dst): + nonlocal calls + calls+=1 + if calls==2: raise KeyboardInterrupt() + return replace(src,dst) + with patch.object(module.os,'replace',side_effect=interrupt_once): + with self.assertRaises(KeyboardInterrupt): module.synchronize(self.source,self.target) + self.assertEqual(old,(self.target/'method-core.lock.json').read_bytes()) + self.assertEqual(b'#!/usr/bin/env python3\nprint("state")\n',(self.target/'scripts/project-state').read_bytes()) + self.assertEqual(0,self.sync('--check').returncode) + + def crash_update(self): + script = """ +import importlib.util, os, sys +from pathlib import Path +spec=importlib.util.spec_from_file_location('sync_crash',sys.argv[1]) +m=importlib.util.module_from_spec(spec);spec.loader.exec_module(m) +replace=m.os.replace +def crash_after_write(src,dst): + replace(src,dst) + if Path(dst).name=='project-state': os._exit(23) +m.os.replace=crash_after_write +m.synchronize(Path(sys.argv[2]),Path(sys.argv[3])) +""" + result=subprocess.run([os.sys.executable,'-c',script,str(ROOT/'scripts/method_core.py'),str(self.source),str(self.target)]) + self.assertEqual(23,result.returncode) + + def test_process_death_can_recover_durable_original_files(self): + # SIGKILL/powerful termination cannot execute in-memory exception cleanup. + self.install();old=(self.target/'method-core.lock.json').read_bytes() + self.put('scripts/project-state',b'updated state\n',0o755);self.commit() + self.crash_update() + self.assertNotEqual(0,self.sync('--check').returncode) + recovery=self.sync('--recover');self.assertEqual(0,recovery.returncode,recovery.stdout+recovery.stderr) + self.assertEqual(old,(self.target/'method-core.lock.json').read_bytes()) + self.assertEqual(b'#!/usr/bin/env python3\nprint("state")\n',(self.target/'scripts/project-state').read_bytes()) + self.assertEqual(0,self.sync('--check').returncode);self.install() + + @unittest.skipUnless(os.name == 'posix' and os.geteuid() != 0, 'requires enforced POSIX directory permissions') + def test_blocked_recovery_retains_backups_until_permissions_are_fixed(self): + self.install();old=(self.target/'method-core.lock.json').read_bytes() + self.put('scripts/project-state',b'updated state\n',0o755);self.commit() + self.crash_update() + locked=self.target/'scripts';locked.chmod(0o555) + try: + recovery=self.sync('--recover') + self.assertNotEqual(0,recovery.returncode) + self.assertIn('backups retained',recovery.stdout) + self.assertTrue((self.target/'.method-core-transaction/journal.json').is_file()) + finally: locked.chmod(0o755) + self.assertEqual(0,self.sync('--recover').returncode) + self.assertEqual(old,(self.target/'method-core.lock.json').read_bytes()) + self.assertEqual(0,self.sync('--check').returncode) + + def test_an_active_transaction_cannot_be_recovered_or_overwritten(self): + self.install() + spec=importlib.util.spec_from_file_location('sync_owner',ROOT/'scripts/method_core.py') + module=importlib.util.module_from_spec(spec);spec.loader.exec_module(module) + path=self.target/'method-core.lock.json';before=path.read_bytes() + module._begin_transaction(self.target,{path:module._snapshot(path)}) + try: + self.assertNotEqual(0,self.sync('--recover').returncode) + self.assertNotEqual(0,self.sync('--source-root',str(self.source)).returncode) + self.assertEqual(before,path.read_bytes()) + finally: module._recover_transaction(self.target,owner=True) + self.assertEqual(0,self.sync('--check').returncode) + + def test_recovery_excludes_other_recovery_and_updates_until_finished(self): + self.install() + self.put('scripts/project-state',b'updated state\n',0o755);self.commit() + self.crash_update() + script = """ +import importlib.util, sys +from pathlib import Path +spec=importlib.util.spec_from_file_location('paused_recovery',sys.argv[1]) +m=importlib.util.module_from_spec(spec);spec.loader.exec_module(m) +replace=m._replace +def pause(path,*args): + print('recovery locked',flush=True) + sys.stdin.readline() + return replace(path,*args) +m._replace=pause +m.recover_transaction(Path(sys.argv[2])) +""" + child=subprocess.Popen([os.sys.executable,'-c',script,str(ROOT/'scripts/method_core.py'),str(self.target)], + stdin=subprocess.PIPE,stdout=subprocess.PIPE,stderr=subprocess.PIPE,text=True) + try: + self.assertEqual('recovery locked',child.stdout.readline().strip()) + for arguments in [('--recover',),('--source-root',str(self.source))]: + result=self.sync(*arguments) + self.assertNotEqual(0,result.returncode) + self.assertIn('already active',result.stdout) + child.stdin.write('continue\n');child.stdin.flush() + output,error=child.communicate(timeout=10) + self.assertEqual(0,child.returncode,output+error) + finally: + if child.poll() is None: child.kill();child.communicate() + self.assertEqual(0,self.sync('--check').returncode) + self.install() + self.assertEqual(b'updated state\n',(self.target/'scripts/project-state').read_bytes()) + self.assertFalse((self.target/'.method-core-transaction').exists()) + +if __name__=='__main__': unittest.main() diff --git a/tests/test_features.py b/tests/test_features.py index 110ad4e..0587c82 100644 --- a/tests/test_features.py +++ b/tests/test_features.py @@ -130,7 +130,7 @@ def test_rejects_unmarked_visible_features_when_markers_are_present(self) -> Non load_features(path) def test_rejects_visible_feature_in_a_pre_release_document_without_any_marker(self) -> None: - root = Path(__file__).resolve().parents[1] + root = Path(__file__).resolve().parent / "fixtures/legacy-project" content = (root / "FEATURES.md").read_text(encoding="utf-8") content += "\n## `F-999` Unmarked\n\n- Status: available\n- Summary: Hidden.\n" with tempfile.TemporaryDirectory() as temporary: @@ -155,7 +155,7 @@ def test_rejects_duplicate_feature_ids(self) -> None: FeatureDocument(features=(feature(), feature())) def test_current_inventory_records_verified_capabilities(self) -> None: - root = Path(__file__).resolve().parents[1] + root = Path(__file__).resolve().parent / "fixtures/legacy-project" inventory = load_features(root / "FEATURES.md") backlog = {item.id: item for item in load_backlog(root / "BACKLOG.md").items} self.assertTrue({"F-001", "F-002", "F-003", "F-004"}.issubset( diff --git a/tests/test_host_eval_runner.py b/tests/test_host_eval_runner.py index 76e08e1..940b497 100644 --- a/tests/test_host_eval_runner.py +++ b/tests/test_host_eval_runner.py @@ -314,15 +314,16 @@ def native(command, cwd, child_env, timeout): self.assertEqual('{"mcpServers":{}}', command[command.index("--mcp-config") + 1]) settings = json.loads(Path(command[command.index("--settings") + 1]).read_text()) self.assertTrue(settings["disableAllHooks"]) - (cwd / "decision.md").write_text("PDF assessment only.") + (cwd / "README.md").write_text("We receive events.\n") + (cwd / "decision.md").write_text("Focused edit assessment.") return "\n".join(map(json.dumps, [ - {"type": "assistant", "message": {"content": [{"type": "tool_use", "id": "s1", "name": "Skill", "input": {"skill": "documentation-pdf"}}]}}, - {"type": "user", "message": {"content": [{"type": "tool_result", "tool_use_id": "s1", "content": "PDF skill loaded"}]}}, - {"type": "result", "subtype": "success", "is_error": False, "structured_output": {"primary": "documentation-pdf", "supporting": []}}, + {"type": "assistant", "message": {"content": [{"type": "tool_use", "id": "s1", "name": "Edit", "input": {"file_path": "README.md"}}]}}, + {"type": "user", "message": {"content": [{"type": "tool_result", "tool_use_id": "s1", "content": "Edit completed"}]}}, + {"type": "result", "subtype": "success", "is_error": False, "structured_output": {"primary": "native-focused-edit", "supporting": []}}, ])) with patch.dict(os.environ, env, clear=True), patch("scripts.run_host_evals.execute", native): try: - code = main(["--host", "claude", "--native-auth", "--case", "documentation-pdf", "--output-dir", str(root)]) + code = main(["--host", "claude", "--native-auth", "--case", "trivial-edit", "--output-dir", str(root)]) except SystemExit as exc: code = exc.code self.assertEqual(0, code) diff --git a/tests/test_host_namespace.py b/tests/test_host_namespace.py new file mode 100644 index 0000000..54feab2 --- /dev/null +++ b/tests/test_host_namespace.py @@ -0,0 +1,19 @@ +"""Shared transcript parsing must respect the selected consumer namespace.""" +import json +from pathlib import Path +import tempfile +import unittest +from scripts.run_host_evals import parse_transcript, EvalFailure + +class HostNamespaceTests(unittest.TestCase): + def test_writing_namespace_is_accepted_only_for_its_plugin(self): + with tempfile.TemporaryDirectory() as directory: + root=Path(directory);(root/'.codex-plugin').mkdir() + (root/'.codex-plugin/plugin.json').write_text(json.dumps({'name':'writing-method'})) + (root/'skills/documentation-pdf').mkdir(parents=True) + (root/'skills/documentation-pdf/SKILL.md').write_text('PDF instructions') + events=[{'type':'assistant','message':{'content':[{'type':'tool_use','id':'s1','name':'Skill','input':{'skill':'writing-method:documentation-pdf'}}]}},{'type':'user','message':{'content':[{'type':'tool_result','tool_use_id':'s1','content':'PDF instructions'}]}},{'type':'result','subtype':'success','is_error':False,'structured_output':{'primary':'writing-method:documentation-pdf','supporting':[]}}] + transcript='\n'.join(map(json.dumps,events)) + parsed=parse_transcript('claude',transcript,plugin=root) + self.assertEqual('documentation-pdf',parsed['decision']['primary']) + with self.assertRaises(EvalFailure): parse_transcript('claude',transcript.replace('writing-method:','foreign-method:'),plugin=root) diff --git a/tests/test_method_identity.py b/tests/test_method_identity.py new file mode 100644 index 0000000..027c26c --- /dev/null +++ b/tests/test_method_identity.py @@ -0,0 +1,43 @@ +"""Method identity must survive packaging and coexistence in a single host.""" +import json +import os +from pathlib import Path +import shutil +import subprocess +import tempfile +import unittest +import zipfile +from scripts.package_plugin import build_package +ROOT=Path(__file__).resolve().parents[1] + +class MethodIdentityTests(unittest.TestCase): + def test_writing_archive_uses_committed_manifest_identity(self): + # Hardcoding engineering-method creates an unusable writing release archive. + with tempfile.TemporaryDirectory() as directory: + root=Path(directory);(root/'.codex-plugin').mkdir() + (root/'.codex-plugin/plugin.json').write_text(json.dumps({'name':'writing-method'})) + (root/'README.md').write_text('writing') + for args in [('init','-q'),('add','.'),('-c','user.name=Test','-c','user.email=test@example.invalid','commit','-qm','fixture')]: + subprocess.run(['git','-C',str(root),*args],check=True) + (root/'.codex-plugin/plugin.json').write_text(json.dumps({'name':'wrong-local-name'})) + build_package(root,root/'bundle.zip') + with zipfile.ZipFile(root/'bundle.zip') as archive: + self.assertIn('writing-method/README.md',archive.namelist()) + self.assertNotIn('wrong-local-name/README.md',archive.namelist()) + def test_both_opencode_loaders_coexist_and_uninstall_is_scoped(self): + # A fixed loader filename must not overwrite or block the second method. + with tempfile.TemporaryDirectory() as directory: + base=Path(directory);config=base/'config' + for name in ['engineering-method','writing-method']: + source=base/name + for folder in ['integrations/opencode','shared/platform','skills','.codex-plugin']: + (source/folder).mkdir(parents=True,exist_ok=True) + (source/'.codex-plugin/plugin.json').write_text(json.dumps({'name':name})) + (source/'integrations/opencode/plugin.mjs').write_text('export default async()=>({})') + (source/'shared/platform/opencode.md').write_text('adapter') + result=subprocess.run([os.sys.executable,str(ROOT/'scripts/install-opencode'),'--source-root',str(source),'--config-dir',str(config)],capture_output=True,text=True) + self.assertEqual(0,result.returncode,result.stderr) + self.assertEqual({'engineering-method.js','writing-method.js'},{p.name for p in (config/'plugins').iterdir()}) + result=subprocess.run([os.sys.executable,str(ROOT/'scripts/install-opencode'),'--source-root',str(base/'writing-method'),'--config-dir',str(config),'--uninstall'],capture_output=True,text=True) + self.assertEqual(0,result.returncode,result.stderr) + self.assertEqual({'engineering-method.js'},{p.name for p in (config/'plugins').iterdir()}) diff --git a/tests/test_orchestrated_implementation.py b/tests/test_orchestrated_implementation.py index e551b21..1d9cedd 100644 --- a/tests/test_orchestrated_implementation.py +++ b/tests/test_orchestrated_implementation.py @@ -291,9 +291,11 @@ class OrchestrationProvenanceTests(unittest.TestCase): def test_all_pinned_superpowers_inputs_have_adapted_destination_mappings(self) -> None: """An adapted orchestration mechanism without its source mapping is unauditable.""" lock = json.loads(read("third-party/sources.lock.json")) - source = next(item for item in lock["sources"] if item["id"] == "superpowers") + core_lock = json.loads(read("third-party/core-sources.lock.json")) + sources = [item for item in lock["sources"] + core_lock["sources"] if item["id"] == "superpowers"] mappings = [ - mapping for mapping in source["files"] if mapping["modification_status"] == "adapted" + mapping for source in sources for mapping in source["files"] + if mapping["modification_status"] == "adapted" ] expected_sources = { "skills/subagent-driven-development/SKILL.md", @@ -321,7 +323,7 @@ def test_all_pinned_superpowers_inputs_have_adapted_destination_mappings(self) - expected_destinations, expected_destinations & {item["destination_path"] for item in mappings}, ) - notices = read("THIRD_PARTY_NOTICES.md") + notices = read("THIRD_PARTY_NOTICES.md") + read("CORE_NOTICES.md") for destination in expected_destinations: self.assertIn(f"`{destination}`", notices) diff --git a/tests/test_release_contracts.py b/tests/test_release_contracts.py index b654405..9e091e4 100644 --- a/tests/test_release_contracts.py +++ b/tests/test_release_contracts.py @@ -29,6 +29,7 @@ def test_readme_documents_installation_boundaries_and_evidence_limits(self): def test_every_distributed_skill_is_attributed_or_explicitly_original(self): """Adding a derived skill without a mapping must not silently claim provenance.""" lock = json.loads((ROOT / "third-party/sources.lock.json").read_text()) + lock["sources"] += json.loads((ROOT / "third-party/core-sources.lock.json").read_text())["sources"] derived = {m["destination_path"] for s in lock["sources"] for m in s["files"] if m["modification_status"] == "adapted"} original = lock.get("original", {}) @@ -43,8 +44,9 @@ def test_every_distributed_skill_is_attributed_or_explicitly_original(self): def test_notices_cover_every_pinned_mapping_and_full_mit_permissions(self): """Removing a source notice, copyright or modification disclosure must fail.""" - notices = (ROOT / "THIRD_PARTY_NOTICES.md").read_text() + notices = (ROOT / "THIRD_PARTY_NOTICES.md").read_text() + (ROOT / "CORE_NOTICES.md").read_text() lock = json.loads((ROOT / "third-party/sources.lock.json").read_text()) + lock["sources"] += json.loads((ROOT / "third-party/core-sources.lock.json").read_text())["sources"] for source in lock["sources"]: self.assertIn(source["repository"], notices) self.assertIn(source["revision"], notices) diff --git a/tests/test_skill_contracts.py b/tests/test_skill_contracts.py index ab3e429..3bcd405 100644 --- a/tests/test_skill_contracts.py +++ b/tests/test_skill_contracts.py @@ -19,9 +19,6 @@ "speckit-plan", "speckit-tasks", "speckit-converge", - "documentation-planning", - "documentation-authoring", - "documentation-review", ) ENTRY_CONTROLLERS = frozenset( @@ -128,18 +125,11 @@ def test_convergence_retry_and_as_built_gate_are_explicit(self) -> None: self.assertEqual( { ("speckit-converge", "orchestrated-implementation"), - ("documentation-review", "documentation-authoring"), }, {(edge["from"], edge["to"]) for edge in retry}, ) convergence = next(edge for edge in retry if edge["from"] == "speckit-converge") self.assertEqual("actionable findings appended as new slices", convergence["condition"]) - documentation = next(edge for edge in retry if edge["from"] == "documentation-review") - self.assertEqual("actionable findings returned for affected chunks", documentation["condition"]) - self.assertTrue(documentation["preserves"]) - review = next(edge for edge in graph["edges"] if edge["from"] == "documentation-review") - self.assertEqual("verification-before-completion", review["to"]) - self.assertIn("no open Critical or Important findings", review.get("completion_guard", "")) execution = next(edge for edge in graph["edges"] if edge["from"] == "orchestrated-implementation") self.assertEqual("architecture-modeling:as-built", execution.get("required_gate")) completion = next(edge for edge in graph["edges"] if edge["from"] == "speckit-converge") @@ -165,7 +155,6 @@ def test_handoff_graph_is_acyclic_and_has_one_executor_per_lifecycle(self) -> No "bugfix": "test-driven-development", "openspec": "openspec-apply", "speckit": "orchestrated-implementation", - "documentation": "documentation-authoring", }, executors, ) @@ -270,10 +259,6 @@ def test_trigger_matrix_covers_the_required_boundaries(self) -> None: "received-review", "independent-failures", "completion-without-evidence", - "standalone-document", - "documentation-set", - "existing-documentation-plan", - "documentation-pdf", "playbook-system-requirement", "playbook-development-operation", "playbook-authoring", @@ -338,26 +323,6 @@ def test_trigger_matrix_has_exact_roles_consistent_with_skills_and_handoffs(self ["project-backlog", "verification-before-completion"], ["speckit-specify", "openspec-propose", "systematic-debugging", *DOCUMENTATION_ENTRIES], ), - "standalone-document": ( - "documentation-authoring", - ["project-backlog", "writing-procedures", "human-prose-drafting", "terminology-guard", "verification-before-completion"], - ["native-focused-edit", "systematic-debugging", "openspec-propose", "speckit-specify", "documentation-planning"], - ), - "documentation-set": ( - "documentation-planning", - ["project-backlog", "terminology-guard", "visual-placeholders", "verification-before-completion"], - ["native-focused-edit", "systematic-debugging", "openspec-propose", "speckit-specify", "documentation-authoring"], - ), - "existing-documentation-plan": ( - "documentation-authoring", - ["project-backlog", "explaining-concepts", "writing-procedures", "empathic-troubleshooting", "human-prose-drafting", "terminology-guard", "visual-placeholders"], - ["native-focused-edit", "systematic-debugging", "openspec-propose", "speckit-specify", "documentation-planning"], - ), - "documentation-pdf": ( - "documentation-pdf", - ["verification-before-completion"], - ["native-focused-edit", "documentation-authoring", "documentation-planning", "systematic-debugging", "speckit-specify", "openspec-propose"], - ), } expected.update( {'playbook-system-requirement': ('speckit-specify', @@ -409,6 +374,7 @@ def test_trigger_matrix_has_exact_roles_consistent_with_skills_and_handoffs(self case["id"]: (case["primary"], case["supporting"], case["prohibited"]) for case in matrix } + expected = {key:value for key,value in expected.items() if not value[0].startswith("documentation-")} self.assertEqual(expected, actual) graph = fenced_json("shared/policies/lifecycle-handoffs.md") @@ -416,7 +382,7 @@ def test_trigger_matrix_has_exact_roles_consistent_with_skills_and_handoffs(self known.update(path.parent.name for path in (ROOT / "skills").glob("*/SKILL.md")) for case in matrix: with self.subTest(case=case["id"]): - roles = [case["primary"], *case["supporting"], *case["prohibited"]] + roles = [case["primary"], *case["supporting"]] self.assertEqual([], sorted(set(roles) - known)) self.assertNotIn(case["primary"], case["supporting"]) self.assertNotIn(case["primary"], case["prohibited"]) @@ -499,6 +465,8 @@ def test_installed_resource_links_are_skill_relative_and_resolve(self) -> None: "skills/empathic-troubleshooting/SKILL.md": {"../../shared/writing/curse-of-knowledge-filter.md"}, } for relative, required in expected.items(): + if not (ROOT / relative).exists(): + continue # Companion-owned links are checked in writing-method. with self.subTest(skill=relative): links = markdown_links(read(relative)) self.assertEqual(required, required & links) @@ -1322,6 +1290,7 @@ def test_normal_contracts_use_only_repository_contained_provenance_facts(self) - def test_locked_destination_hashes_and_source_metadata_are_complete(self) -> None: """Changing an adapted file without its lock metadata must fail provenance.""" lock = json.loads(read("third-party/sources.lock.json")) + lock["sources"] += json.loads(read("third-party/core-sources.lock.json"))["sources"] destinations: set[str] = set() for source in lock["sources"]: for mapping in source["files"]: @@ -1340,6 +1309,7 @@ def test_locked_destination_hashes_and_source_metadata_are_complete(self) -> Non def test_delta_spec_uses_real_pinned_template_and_escalation_is_original(self) -> None: """Original escalation text must not be misattributed as an upstream adaptation.""" lock = json.loads(read("third-party/sources.lock.json")) + lock["sources"] += json.loads(read("third-party/core-sources.lock.json"))["sources"] mappings = { mapping["destination_path"]: (source["id"], mapping) for source in lock["sources"] @@ -1363,6 +1333,7 @@ def test_plan_pins_the_delta_template_source_declared_by_the_lock(self) -> None: """The approved source list must cover every newly selected OpenSpec input.""" plan = read("docs/plans/EM-003-curated-workflow-skills.md") lock = json.loads(read("third-party/sources.lock.json")) + lock["sources"] += json.loads(read("third-party/core-sources.lock.json"))["sources"] delta_mapping = next( mapping for source in lock["sources"] diff --git a/tests/test_validate_plugin.py b/tests/test_validate_plugin.py index 942ef83..34f7944 100644 --- a/tests/test_validate_plugin.py +++ b/tests/test_validate_plugin.py @@ -217,9 +217,12 @@ def test_real_repository_pins_the_required_upstream_provenance(self) -> None: lock = json.loads(lock_path.read_text(encoding="utf-8")) self.assertEqual(1, lock["schema_version"]) - sources = lock["sources"] - self.assertEqual([source["id"] for source in PROVENANCE_SOURCES], [source["id"] for source in sources]) - for expected, actual in zip(PROVENANCE_SOURCES, sources, strict=True): + sources = lock["sources"] + json.loads((root / "third-party/core-sources.lock.json").read_text())["sources"] + sources = list({source["id"]: source for source in sources}.values()) + expected_sources = [source for source in PROVENANCE_SOURCES if source["id"] != "humanizer"] + sources.sort(key=lambda source: [item["id"] for item in expected_sources].index(source["id"])) + self.assertEqual([source["id"] for source in expected_sources], [source["id"] for source in sources]) + for expected, actual in zip(expected_sources, sources, strict=True): self.assertEqual(expected["project"], actual["project"]) self.assertEqual(expected["repository"], actual["repository"]) self.assertEqual(expected["revision"], actual["revision"]) @@ -230,7 +233,7 @@ def test_real_repository_pins_the_required_upstream_provenance(self) -> None: self.assertEqual( { "source_path": "LICENSE", - "destination_path": "THIRD_PARTY_NOTICES.md", + "destination_path": actual["files"][0]["destination_path"], "source_sha256": expected["license_sha256"], "modification_status": "notice-only", }, @@ -249,13 +252,15 @@ def test_real_repository_notices_agree_with_the_source_lock(self) -> None: self.assertTrue(notice_path.is_file(), "THIRD_PARTY_NOTICES.md must exist") if not notice_path.is_file(): return - notices = notice_path.read_text(encoding="utf-8") + notices = notice_path.read_text(encoding="utf-8") + (root / "CORE_NOTICES.md").read_text() self.assertIn("This plugin adapts only the files listed below", notices) self.assertIn("## Original implementation", notices) - for source in PROVENANCE_SOURCES: + distributed = json.loads((root / "third-party/sources.lock.json").read_text())["sources"] + json.loads((root / "third-party/core-sources.lock.json").read_text())["sources"] + revisions = {source["revision"] for source in distributed} + for source in (entry for entry in PROVENANCE_SOURCES if entry["revision"] in revisions): for value in ( - source["project"], + source["id"], source["repository"], source["revision"], source["license_sha256"], diff --git a/third-party/core-sources.lock.json b/third-party/core-sources.lock.json new file mode 100644 index 0000000..17ecfcc --- /dev/null +++ b/third-party/core-sources.lock.json @@ -0,0 +1,217 @@ +{ + "schema_version": 1, + "sources": [ + { + "id": "superpowers", + "project": "Superpowers", + "repository": "https://github.com/obra/superpowers.git", + "revision": "b36e0829c6d0140e93cfef2ca599b1b07d4a7797", + "license": { + "spdx": "MIT", + "source_path": "LICENSE", + "sha256": "a37e0e9697144819e1d965176ac4ae5bc3fa02d11e7812036bbcadf6dafe2400" + }, + "copyright": "Copyright (c) 2025 Jesse Vincent", + "modification_summary": "Curated quality practices and adapted report, brief, review and recovery mechanics for cohesive slices, proportional review and protected project-state storage.", + "files": [ + { + "source_path": "LICENSE", + "destination_path": "CORE_NOTICES.md", + "source_sha256": "a37e0e9697144819e1d965176ac4ae5bc3fa02d11e7812036bbcadf6dafe2400", + "modification_status": "notice-only" + }, + { + "source_path": "skills/verification-before-completion/SKILL.md", + "destination_path": "skills/verification-before-completion/SKILL.md", + "source_sha256": "2befe7fc55bcadaa3d97dd9e8efeb633d2561c0ebe74c5a8b17c4d9e7e4520b3", + "destination_sha256": "faaf2467dbfc9d10d280d1891762ba8e3da6e2220c77f870fdc1ef0347901fa7", + "modification_status": "adapted" + }, + { + "source_path": "skills/requesting-code-review/SKILL.md", + "destination_path": "skills/requesting-code-review/SKILL.md", + "source_sha256": "d71cc01ba56d2325cf8af5f7c11837819b63ecd57de0bfdb812f7f3ff7751df8", + "destination_sha256": "197f746dcb6d5bf10e9e65c532c9b39a042e9daa7184fc27f2fafab848901c25", + "modification_status": "adapted" + }, + { + "source_path": "skills/requesting-code-review/code-reviewer.md", + "destination_path": "skills/requesting-code-review/code-reviewer.md", + "source_sha256": "5eca5fcfd48a50e0a526ce5ffd64bf625d6b81bb46d11795274dae451fe6ffd4", + "destination_sha256": "1ccb035bef48a862682a7e34557447b04d3b86992c78519b10b2a4bd77f625f2", + "modification_status": "adapted" + }, + { + "source_path": "skills/receiving-code-review/SKILL.md", + "destination_path": "skills/receiving-code-review/SKILL.md", + "source_sha256": "091df1629510af1b92fc4abd6f96732ebedb4cb2c0f3457e8f2740b0504a2438", + "destination_sha256": "0470026a2fb8d9a0faf3c7dfb43ecad2fdcbc1bd20ba888e4c01cd7c762cb957", + "modification_status": "adapted" + }, + { + "source_path": "skills/using-git-worktrees/SKILL.md", + "destination_path": "skills/using-git-worktrees/SKILL.md", + "source_sha256": "8cfb86f121269e8f7f12361e6795c4f6738828340e28964c9229d365666c9edd", + "destination_sha256": "c913860e385c45657b006097128523cfebafdf7a29c710e4755710d7c606494a", + "modification_status": "adapted" + }, + { + "source_path": "skills/dispatching-parallel-agents/SKILL.md", + "destination_path": "skills/dispatching-parallel-agents/SKILL.md", + "source_sha256": "1968923066f3b707eb01d1992cdf4c42284c3855f70253b9cd5000ff45fca13c", + "destination_sha256": "340659cce89cc6d8dad13f754f1ebe2523460d75fde4e7c998020ea2ebba37d4", + "modification_status": "adapted" + }, + { + "source_path": "skills/subagent-driven-development/implementer-prompt.md", + "destination_path": "templates/orchestration/agent-report.md", + "source_sha256": "81dd9d5a3fb0b09b96b5829f03b9796842f3199ef7591d1ba1c2db2a515f64d0", + "destination_sha256": "5f69bede77238ecfdacda598c86842478f0a51e4c2b444f292df0da08d088e73", + "modification_status": "adapted" + }, + { + "source_path": "skills/subagent-driven-development/task-reviewer-prompt.md", + "destination_path": "shared/agent-roles/reviewer.md", + "source_sha256": "eea23e33ec570c3041f40e9569fa711d61b8029f9eecf908345138aa1c6e61ab", + "destination_sha256": "8ed94cc55adc7ebbcad64c88496a9ef945e63e01cd920a390a5400c1ad6f4825", + "modification_status": "adapted" + }, + { + "source_path": "skills/subagent-driven-development/re-review-prompt.md", + "destination_path": "templates/orchestration/review-report.md", + "source_sha256": "db0d5849478bc79cbde97b9b2cf0e58b50be8b8ed18464b0252c2bf27b6440a6", + "destination_sha256": "f2dc75b25feaec24e865f79db2e510f3ce98948bfdce506655fb1eec2cfb941d", + "modification_status": "adapted" + }, + { + "source_path": "skills/subagent-driven-development/scripts/sdd-workspace", + "destination_path": "shared/policies/continuity-contract.md", + "source_sha256": "95a09d9d3983ad1aafd093ca72b4587946dea885c6e302caa02a779a2f911c31", + "destination_sha256": "81c8162402096840f5ed5ac34a4fed4c21a155ba4a2a526e91ba507a726c1641", + "modification_status": "adapted" + }, + { + "source_path": "skills/subagent-driven-development/scripts/sdd-workspace", + "destination_path": "templates/orchestration/resume.md", + "source_sha256": "95a09d9d3983ad1aafd093ca72b4587946dea885c6e302caa02a779a2f911c31", + "destination_sha256": "38c5b475852386d303c3c73108bec28b034ddeac781499bd197c383b5e170094", + "modification_status": "adapted" + } + ] + }, + { + "id": "sre-runbook-agent-skills", + "project": "sre-runbook-agent-skills", + "repository": "https://github.com/medzin/sre-runbook-agent-skills.git", + "revision": "44ab3d87293788036013098868563f82a3369b81", + "license": { + "spdx": "MIT", + "source_path": "LICENSE", + "sha256": "f114aa5869612318e5c35fb10175e322e1feec5039bddf321a1822edf2737cf6" + }, + "copyright": "Copyright (c) 2026 Adam Medzi\u0144ski", + "modification_summary": "Adapted selected playbook authoring/review and evidence rules for development and system deliverables, conditional lifecycle support and existing authority; removed incident-only and host-specific requirements.", + "files": [ + { + "source_path": "LICENSE", + "destination_path": "CORE_NOTICES.md", + "source_sha256": "f114aa5869612318e5c35fb10175e322e1feec5039bddf321a1822edf2737cf6", + "modification_status": "notice-only" + }, + { + "source_path": "skills/sre-runbook-author/SKILL.md", + "destination_path": "skills/playbook-authoring/SKILL.md", + "source_sha256": "a7c06fd658dccc671cae685a4823b82a21e1575f85ec1e0f844c7b6b9458f25c", + "destination_sha256": "9ac4be7b74cd19978c4d82eee0f092666ea6792fd18a88be36f370c972d639e8", + "modification_status": "adapted" + }, + { + "source_path": "skills/sre-runbook-author/references/runbook-template.md", + "destination_path": "templates/playbooks/playbook.md", + "source_sha256": "b9ed541c36f1f0590f074c7238380c77959cec4ec7aed0207cf31f8539a69122", + "destination_sha256": "61c414cd9a6bc95fce20945c706e2db7cb2af0b9bd8afae139963cfb3df59ebb", + "modification_status": "adapted" + }, + { + "source_path": "skills/sre-runbook-reviewer/SKILL.md", + "destination_path": "skills/playbook-review/SKILL.md", + "source_sha256": "7385abc84b1db7b8ba9fa90e65d820f6986d262893ad42773fd4ff5a25c717ca", + "destination_sha256": "a784e7986fce41b19a4220e7c98356fd9c23b71504fb4ada9ccbce519290ecd9", + "modification_status": "adapted" + }, + { + "source_path": "skills/sre-runbook-reviewer/references/review-scorecard.md", + "destination_path": "templates/playbooks/review.md", + "source_sha256": "356c3135e482ad69e082e32571422e36408bcbfa430707eca60a2d4abcc70c52", + "destination_sha256": "55eac867e0d8014de46075b113f3b51ead2debadff02cf820bf93b54f7c541c9", + "modification_status": "adapted" + } + ] + }, + { + "id": "han", + "project": "han", + "repository": "https://github.com/testdouble/han.git", + "revision": "19cb21bcb1154d29bf20d1f3c9ad4854a59580d2", + "license": { + "spdx": "MIT", + "source_path": "LICENSE", + "sha256": "9940ab927f654e997d00aedc6a8734be0600f9443377697419ee7ed4247f2d36" + }, + "copyright": "Copyright 2026 Test Double, Inc.", + "modification_summary": "Adapted selected playbook authoring/review and evidence rules for development and system deliverables, conditional lifecycle support and existing authority; removed incident-only and host-specific requirements.", + "files": [ + { + "source_path": "LICENSE", + "destination_path": "CORE_NOTICES.md", + "source_sha256": "9940ab927f654e997d00aedc6a8734be0600f9443377697419ee7ed4247f2d36", + "modification_status": "notice-only" + }, + { + "source_path": "han-documentation/skills/runbook/SKILL.md", + "destination_path": "shared/policies/playbooks.md", + "source_sha256": "1fd29933594a19177a60c77c98ae7cf776220aa67b5f11ae70d2851fc63eee37", + "destination_sha256": "a08a4344863f8dcd682c822b0164a6102042ce3e844b72bd417ff03e0ae0390d", + "modification_status": "adapted" + } + ] + } + ], + "original": { + "copyright": "Copyright (c) 2026 Peter Hense", + "license": "MIT", + "modification_status": "original", + "paths": [ + "engineering_method/**", + "shared/platform/**", + "templates/uml/**", + "tests/**", + "evals/**", + "skills/architecture-modeling/SKILL.md", + "skills/project-backlog/SKILL.md", + "shared/agent-roles/system-architect.md", + "shared/agent-roles/debugger.md", + "shared/policies/architecture-gate.md", + "shared/policies/defect-convergence.md", + "shared/policies/model-routing.md", + "shared/policies/orchestration.md", + "shared/policies/lifecycle-handoffs.md", + "templates/openspec/escalation.md", + "shared/policies/proportionality.md", + "skills/documentation-planning/SKILL.md", + "skills/documentation-authoring/SKILL.md", + "skills/documentation-review/SKILL.md", + "skills/explaining-concepts/SKILL.md", + "skills/writing-procedures/SKILL.md", + "skills/empathic-troubleshooting/SKILL.md", + "skills/terminology-guard/SKILL.md", + "skills/visual-placeholders/SKILL.md", + "shared/policies/writing-depth.md", + "shared/policies/reader-oriented-output.md", + "shared/writing/**", + "templates/documentation/**", + "skills/documentation-pdf/SKILL.md" + ], + "scope": "These paths are original implementation. All adapted destinations are enumerated separately in sources; no upstream runtime is bundled." + } +} diff --git a/third-party/sources.lock.json b/third-party/sources.lock.json index d684bc3..d1c130d 100644 --- a/third-party/sources.lock.json +++ b/third-party/sources.lock.json @@ -11,6 +11,8 @@ "source_path": "LICENSE", "sha256": "2510b446bc1f0cf9702453075d20cd88631e20e5642658edb7325d9c1eb534f7" }, + "copyright": "Copyright GitHub, Inc.", + "modification_summary": "Adapted specification, planning, task and convergence artifacts with exclusive lifecycles, host-neutral recovery, cohesive slices and append-only fix handoffs.", "files": [ { "source_path": "LICENSE", @@ -67,9 +69,7 @@ "destination_sha256": "531bcf3784a3cc17e19efbd70693e9b32123310de38fb850fcc4455e7011067b", "modification_status": "adapted" } - ], - "copyright": "Copyright GitHub, Inc.", - "modification_summary": "Adapted specification, planning, task and convergence artifacts with exclusive lifecycles, host-neutral recovery, cohesive slices and append-only fix handoffs." + ] }, { "id": "openspec", @@ -81,6 +81,8 @@ "source_path": "LICENSE", "sha256": "c3c7235bea1214ab62df643473975c2e8b8848f528901a976693f7d069713e64" }, + "copyright": "Copyright (c) 2024 OpenSpec Contributors", + "modification_summary": "Adapted bounded-change proposal, delta specification, application and archival artifacts without upstream CLI dependencies; added explicit escalation and continuity.", "files": [ { "source_path": "LICENSE", @@ -137,9 +139,7 @@ "destination_sha256": "e3e949f6217d5266367c70341a72685b2184099116118ed4a51bcfc539a4389e", "modification_status": "adapted" } - ], - "copyright": "Copyright (c) 2024 OpenSpec Contributors", - "modification_summary": "Adapted bounded-change proposal, delta specification, application and archival artifacts without upstream CLI dependencies; added explicit escalation and continuity." + ] }, { "id": "superpowers", @@ -151,6 +151,8 @@ "source_path": "LICENSE", "sha256": "a37e0e9697144819e1d965176ac4ae5bc3fa02d11e7812036bbcadf6dafe2400" }, + "copyright": "Copyright (c) 2025 Jesse Vincent", + "modification_summary": "Curated quality practices and adapted report, brief, review and recovery mechanics for cohesive slices, proportional review and protected project-state storage.", "files": [ { "source_path": "LICENSE", @@ -179,48 +181,6 @@ "destination_sha256": "2a318c4200f658492e6b0eb19cd4c5bc496f687bba1fac018fae7b09173ef8fb", "modification_status": "adapted" }, - { - "source_path": "skills/verification-before-completion/SKILL.md", - "destination_path": "skills/verification-before-completion/SKILL.md", - "source_sha256": "2befe7fc55bcadaa3d97dd9e8efeb633d2561c0ebe74c5a8b17c4d9e7e4520b3", - "destination_sha256": "faaf2467dbfc9d10d280d1891762ba8e3da6e2220c77f870fdc1ef0347901fa7", - "modification_status": "adapted" - }, - { - "source_path": "skills/requesting-code-review/SKILL.md", - "destination_path": "skills/requesting-code-review/SKILL.md", - "source_sha256": "d71cc01ba56d2325cf8af5f7c11837819b63ecd57de0bfdb812f7f3ff7751df8", - "destination_sha256": "197f746dcb6d5bf10e9e65c532c9b39a042e9daa7184fc27f2fafab848901c25", - "modification_status": "adapted" - }, - { - "source_path": "skills/requesting-code-review/code-reviewer.md", - "destination_path": "skills/requesting-code-review/code-reviewer.md", - "source_sha256": "5eca5fcfd48a50e0a526ce5ffd64bf625d6b81bb46d11795274dae451fe6ffd4", - "destination_sha256": "1ccb035bef48a862682a7e34557447b04d3b86992c78519b10b2a4bd77f625f2", - "modification_status": "adapted" - }, - { - "source_path": "skills/receiving-code-review/SKILL.md", - "destination_path": "skills/receiving-code-review/SKILL.md", - "source_sha256": "091df1629510af1b92fc4abd6f96732ebedb4cb2c0f3457e8f2740b0504a2438", - "destination_sha256": "9343de65efbe0c1b4442da8bc5001dedb5a09768a73a0d952f206bbec82576a2", - "modification_status": "adapted" - }, - { - "source_path": "skills/using-git-worktrees/SKILL.md", - "destination_path": "skills/using-git-worktrees/SKILL.md", - "source_sha256": "8cfb86f121269e8f7f12361e6795c4f6738828340e28964c9229d365666c9edd", - "destination_sha256": "c913860e385c45657b006097128523cfebafdf7a29c710e4755710d7c606494a", - "modification_status": "adapted" - }, - { - "source_path": "skills/dispatching-parallel-agents/SKILL.md", - "destination_path": "skills/dispatching-parallel-agents/SKILL.md", - "source_sha256": "1968923066f3b707eb01d1992cdf4c42284c3855f70253b9cd5000ff45fca13c", - "destination_sha256": "340659cce89cc6d8dad13f754f1ebe2523460d75fde4e7c998020ea2ebba37d4", - "modification_status": "adapted" - }, { "source_path": "skills/subagent-driven-development/SKILL.md", "destination_path": "skills/orchestrated-implementation/SKILL.md", @@ -235,13 +195,6 @@ "destination_sha256": "8ac5966a8930388c97aea4fd2a7e144364c2684a45695672366397065805a603", "modification_status": "adapted" }, - { - "source_path": "skills/subagent-driven-development/implementer-prompt.md", - "destination_path": "templates/orchestration/agent-report.md", - "source_sha256": "81dd9d5a3fb0b09b96b5829f03b9796842f3199ef7591d1ba1c2db2a515f64d0", - "destination_sha256": "5f69bede77238ecfdacda598c86842478f0a51e4c2b444f292df0da08d088e73", - "modification_status": "adapted" - }, { "source_path": "skills/subagent-driven-development/implementer-prompt.md", "destination_path": "templates/orchestration/slice-brief.md", @@ -249,20 +202,6 @@ "destination_sha256": "6df9bb6098f14efd575f69957e88f1ab325da6c6aa9adee5b3db1fcdb62058ba", "modification_status": "adapted" }, - { - "source_path": "skills/subagent-driven-development/task-reviewer-prompt.md", - "destination_path": "shared/agent-roles/reviewer.md", - "source_sha256": "eea23e33ec570c3041f40e9569fa711d61b8029f9eecf908345138aa1c6e61ab", - "destination_sha256": "8ed94cc55adc7ebbcad64c88496a9ef945e63e01cd920a390a5400c1ad6f4825", - "modification_status": "adapted" - }, - { - "source_path": "skills/subagent-driven-development/re-review-prompt.md", - "destination_path": "templates/orchestration/review-report.md", - "source_sha256": "db0d5849478bc79cbde97b9b2cf0e58b50be8b8ed18464b0252c2bf27b6440a6", - "destination_sha256": "f2dc75b25feaec24e865f79db2e510f3ce98948bfdce506655fb1eec2cfb941d", - "modification_status": "adapted" - }, { "source_path": "skills/subagent-driven-development/scripts/task-brief", "destination_path": "scripts/task-brief", @@ -276,129 +215,8 @@ "source_sha256": "fac3d4bd7f94369e8037b9ead2a8a502dca6ab333902b560b9455dbb3c450ebe", "destination_sha256": "ad5c9c25ba5fb0e07a7ba1cbcdb9d8e8dd846444e516cb4c66f014ea23cf7aed", "modification_status": "adapted" - }, - { - "source_path": "skills/subagent-driven-development/scripts/sdd-workspace", - "destination_path": "shared/policies/continuity-contract.md", - "source_sha256": "95a09d9d3983ad1aafd093ca72b4587946dea885c6e302caa02a779a2f911c31", - "destination_sha256": "81c8162402096840f5ed5ac34a4fed4c21a155ba4a2a526e91ba507a726c1641", - "modification_status": "adapted" - }, - { - "source_path": "skills/subagent-driven-development/scripts/sdd-workspace", - "destination_path": "templates/orchestration/resume.md", - "source_sha256": "95a09d9d3983ad1aafd093ca72b4587946dea885c6e302caa02a779a2f911c31", - "destination_sha256": "38c5b475852386d303c3c73108bec28b034ddeac781499bd197c383b5e170094", - "modification_status": "adapted" - } - ], - "copyright": "Copyright (c) 2025 Jesse Vincent", - "modification_summary": "Curated quality practices and adapted report, brief, review and recovery mechanics for cohesive slices, proportional review and protected project-state storage." - }, - { - "id": "humanizer", - "project": "Humanizer", - "repository": "https://github.com/blader/humanizer.git", - "revision": "9862685f575c65a8247f90369951df1b3416e3d6", - "license": { - "spdx": "MIT", - "source_path": "LICENSE", - "sha256": "4ac4810254ab36d45419141aeb8e69bf50652cfafe5b2dab947d06d44e5cbf96" - }, - "files": [ - { - "source_path": "LICENSE", - "destination_path": "THIRD_PARTY_NOTICES.md", - "source_sha256": "4ac4810254ab36d45419141aeb8e69bf50652cfafe5b2dab947d06d44e5cbf96", - "modification_status": "notice-only" - }, - { - "source_path": "SKILL.md", - "destination_path": "skills/human-prose-drafting/SKILL.md", - "source_sha256": "e8269e236bed06ed0fe4824c274112e54950b0cb46b0bafe5e1576ef7c9f93d5", - "destination_sha256": "6cd68c9a20d0bc8c2484b93692653f83cc05c8a03179173cde640758bd035def", - "modification_status": "adapted" - } - ], - "copyright": "Copyright (c) 2025 Siqi Chen", - "modification_summary": "Reframed the after-the-fact rewrite procedure as drafting-time constraints for medium and large documentation, condensed the 25 patterns into constraint groups, removed pasted-text and voice-matching modes, and added the chunk check and documentation voice rules." - }, - { - "id": "sre-runbook-agent-skills", - "project": "sre-runbook-agent-skills", - "repository": "https://github.com/medzin/sre-runbook-agent-skills.git", - "revision": "44ab3d87293788036013098868563f82a3369b81", - "license": { - "spdx": "MIT", - "source_path": "LICENSE", - "sha256": "f114aa5869612318e5c35fb10175e322e1feec5039bddf321a1822edf2737cf6" - }, - "files": [ - { - "source_path": "LICENSE", - "destination_path": "THIRD_PARTY_NOTICES.md", - "source_sha256": "f114aa5869612318e5c35fb10175e322e1feec5039bddf321a1822edf2737cf6", - "modification_status": "notice-only" - }, - { - "source_path": "skills/sre-runbook-author/SKILL.md", - "destination_path": "skills/playbook-authoring/SKILL.md", - "source_sha256": "a7c06fd658dccc671cae685a4823b82a21e1575f85ec1e0f844c7b6b9458f25c", - "destination_sha256": "4e7fae598f7ea2fcf18692638577dedeb1fe54b816f284c2b6565a6f25c6ce02", - "modification_status": "adapted" - }, - { - "source_path": "skills/sre-runbook-author/references/runbook-template.md", - "destination_path": "templates/playbooks/playbook.md", - "source_sha256": "b9ed541c36f1f0590f074c7238380c77959cec4ec7aed0207cf31f8539a69122", - "destination_sha256": "61c414cd9a6bc95fce20945c706e2db7cb2af0b9bd8afae139963cfb3df59ebb", - "modification_status": "adapted" - }, - { - "source_path": "skills/sre-runbook-reviewer/SKILL.md", - "destination_path": "skills/playbook-review/SKILL.md", - "source_sha256": "7385abc84b1db7b8ba9fa90e65d820f6986d262893ad42773fd4ff5a25c717ca", - "destination_sha256": "532c142f7883342de3dc1dd236740ff6dba590fbac1d667a893de9bf0314b8e2", - "modification_status": "adapted" - }, - { - "source_path": "skills/sre-runbook-reviewer/references/review-scorecard.md", - "destination_path": "templates/playbooks/review.md", - "source_sha256": "356c3135e482ad69e082e32571422e36408bcbfa430707eca60a2d4abcc70c52", - "destination_sha256": "55eac867e0d8014de46075b113f3b51ead2debadff02cf820bf93b54f7c541c9", - "modification_status": "adapted" - } - ], - "copyright": "Copyright (c) 2026 Adam Medzi\u0144ski", - "modification_summary": "Adapted selected playbook authoring/review and evidence rules for development and system deliverables, conditional lifecycle support and existing authority; removed incident-only and host-specific requirements." - }, - { - "id": "han", - "project": "han", - "repository": "https://github.com/testdouble/han.git", - "revision": "19cb21bcb1154d29bf20d1f3c9ad4854a59580d2", - "license": { - "spdx": "MIT", - "source_path": "LICENSE", - "sha256": "9940ab927f654e997d00aedc6a8734be0600f9443377697419ee7ed4247f2d36" - }, - "files": [ - { - "source_path": "LICENSE", - "destination_path": "THIRD_PARTY_NOTICES.md", - "source_sha256": "9940ab927f654e997d00aedc6a8734be0600f9443377697419ee7ed4247f2d36", - "modification_status": "notice-only" - }, - { - "source_path": "han-documentation/skills/runbook/SKILL.md", - "destination_path": "shared/policies/playbooks.md", - "source_sha256": "1fd29933594a19177a60c77c98ae7cf776220aa67b5f11ae70d2851fc63eee37", - "destination_sha256": "0dcfd4048834914dbc30b1352f8c27d215818cae2726a00de1bd70e671019681", - "modification_status": "adapted" } - ], - "copyright": "Copyright 2026 Test Double, Inc.", - "modification_summary": "Adapted selected playbook authoring/review and evidence rules for development and system deliverables, conditional lifecycle support and existing authority; removed incident-only and host-specific requirements." + ] } ], "original": {