P8: Protocol Kernel & Runtime Retirement#56
Merged
Conversation
current_handoff: remove 4 runtime provenance fields from top-level properties; plan_id non-null string. plan_md_sections: prefixItems for ordered section validation. active_plan: plan_id naming convention documented. plan_receipt: receipt_id logical ID clarified. history_receipt: parsed-structure-not-raw-markdown clarified.
§2: plan.md unique semantic entry + 3-tier progressive disclosure + 8 required sections + receipts conditional. §6: Verifier read-only contract (MUST NOT write state/plan/blueprint) + EAR [RETIRED in P8]. §8: replaced Deep Host runtime protocol with Host Protocol Entry Contract (request admission, 4-step read order, read budget, receipts latest-only, write-back boundary, fail-open, 2-file state index). Added Reader Contract (3-line audience targeting).
Add host-prompt-protocol-entry.md: content spec for P8-aware host prompt (request admission, 4-step entry, read budget, writer boundary, fail-open, forbidden surfaces). Update protocol.md Reader Contract wording (tooling author, on-demand reading). Check off W1.1/W1.2/W1.3 tasks in tasks.md.
W1.4: plan_snapshot schema description clarified (not independent carrier, not machine truth, does not override plan.md body or receipts). 3-tier plan package, 8 required sections, receipts conditional rules already in protocol.md §2 (W1.2). W1.5: _registry.yaml [DEPRECATED by P8] added to protocol.md §8.9 with compliance smoke MUST fail rule. design.md §4.3 already records deletion rationale.
…rement ADR-013: add P8 Scope Clarification (authorization narrowing, EAR retirement, convergence chain update; title unchanged). ADR-017: EAR [SUPERSEDED by P8] on title + status + body + ✅ line. design.md: convergence chain authorize→record evidence; Core State Files 6→2 + legacy mapping; persistence red-line active 2-file + legacy mapping; 对外承诺分层 EAR retired; 外部消费面 EAR + gate_receipt retired; 宿主能力治理 hard disclaimer; Validator wording narrowed (2 locations); Convention/Runtime mode legacy markers. protocol.md: §3 Runtime mode column [RETIRED in P8] + 6 cells struck through; §6 header EAR removed from normative exception; 统一出口表 receipt→过程审计回执; §3/§4/§5 Validator prose updated to compliance smoke + sopify_writer. tasks.md: W1.5b checkboxes synced.
…sk expansion Add W2.0a/W2.0b/W2.2b/W2.3b/W2.3c pre-flight tasks before runtime deletion. New §9b in design.md: catalog relocation decision, payload resource positioning, file migration table, field cleanup (runtime_entry/entry_kind/supports_routes). Update §9 keep-list/migration-list and §14 risk table with 3 new risks.
Export 4 registry entries (1 deferred, 1 completed, 2 archived) to assets/registry-lifecycle-snapshot.md. Includes human-readable table, summary, and original field schema reference.
Migrate builtin skill catalog from runtime/ to skills/catalog/: - YAML sources: runtime/builtin_skill_packages/ → skills/catalog/<id>/skill.yaml - Generated JSON: runtime/ → skills/catalog/builtin_catalog.generated.json - Schema: runtime/skill_schema.py → sopify_contracts/skill_schema.py - YAML loader: runtime/_yaml.py → scripts/_yaml_subset.py (load only, no dump) - Generator: runtime-free imports + new paths - Remove runtime_entry, entry_kind, supports_routes from schema + JSON + YAML - Narrow SKILL_MODES to (advisory, workflow) and SKILL_PERMISSION_MODES to (default, host) - Update CI drift check (ci.yml + release-preflight.sh) paths - Update header templates: new path + remove runtime engine language - Update golden-snapshots.json hashes for changed header templates
…source - sopify_bundle.py: remove runtime directory/scripts/manifest import; rename sync_runtime_bundle→sync_payload_bundle; inline manifest writer with capabilities field; add catalog file copy from skills/catalog/ - payload.py: rename _install_versioned_runtime_bundle→_install_versioned_payload_bundle; remove runtime_gate/runtime_entry_guard capabilities; .sopify-runtime→.sopify-payload; catalog_path in payload-manifest.json uses payload_root-relative path - validate.py: remove 4 runtime paths from expected_bundle_paths; add catalog - bootstrap_workspace.py: remove 4 runtime files from _REQUIRED_BUNDLE_FILES; add catalog; .sopify-runtime→.sopify-payload in ignore entries and fallback defaults - models.py: remove FeatureId.RUNTIME_GATE, PREFERENCES_PRELOAD, SMOKE_VERIFIED - hosts/codex+claude: remove retired features from declared/verified; clean doctor_checks - inspection.py: remove preferences_preload from dataclass+all construction sites; _inspect_smoke always returns CHECK_SKIP; doctor_checks() no longer includes smoke - install_sopify.py: remove run_bundle_smoke_check import and invocation - test_installer.py: rename function+patch targets to match W2.2 renames - Plan docs: W2.2+W2.2b marked done; blueprint focus→P8; registry entry added; preferences_preload retirement note in design.md persistence red-line
- git mv canonical_writer/ → sopify_writer/ (6 files) - __init__.py: remove StateStore/SESSIONS_DIRNAME/normalize_session_id from public __all__; only iso_now remains as public export; docstring updated to "the writer for Sopify protocol state and receipts" - store.py: observability string "canonical_writer" → "sopify_writer" (2 sites) - All runtime/ imports (14 files): StateStore → sopify_writer.store; iso_now stays at sopify_writer top level - installer/: _DIRECTORY_ASSETS, expected_bundle_paths, _REQUIRED_BUNDLE_FILES all updated to sopify_writer - scripts/ + tests/: imports and string literals updated - sopify_contracts/__init__.py: docstring reference updated - Plan docs: W2.3 marked done with Note on StateStore demotion; W2.3b wording fixed; snapshot updated to W2.3b next
CI hard gate now uses an explicit non-runtime test set (84 tests) until W2.7 reclassifies runtime-coupled tests. - Rename runtime-tests → protocol-tests job - Replace check-bundle-smoke + check-prompt-runtime-gate-smoke steps with sopify_protocol_check (3 scenarios) - Switch from marker-based to explicit test file list - Rewrite payload smoke: runtime entry assertions → catalog_path check - Sync release-preflight.sh with CI structure - Roll back header version to 2026-05-31.142150 + update golden snapshots Context-Checkpoint: A
…ocol-first Replace runtime gate / sopify_runtime / go_plan_runtime references in tracked source templates (zh + en) with protocol-first entry language: request admission, 4-step entry order, sopify_writer write boundary. - Header templates: 3 runtime-first notes → protocol-first (zh + en) - Design rules: runtime helper boundary section → protocol entry boundary - Analyze/Design/Develop/KB skill files: remove runtime routing refs - Golden snapshots regenerated for updated managed block - tasks.md: sopify_protocol_check scoped as CI/preflight, not host prompt
sopify_writer now only writes active_plan.json and current_handoff.json. All legacy state file writers (current_run, current_plan, current_clarification, current_decision, current_archive_receipt, last_route) removed. - store.py: rewrite to 2-file model, constructor takes Path not RuntimeConfig, session-scoped writes removed - handoff.py: RuntimeHandoff aligned with P8 schema — route_name, run_id, handoff_kind, resolution_id removed from top-level fields - invariants.py: legacy validators removed, only InvariantViolationError retained - __init__.py: docstring updated — StateStore is P8 protocol writer, not temporary runtime shim Runtime code is now broken at import level (expected, A-lite). W2.7/W2.10 will clean up runtime code and tests.
Clarification and decision state no longer need separate state files. They are expressed via current_handoff.json: - required_host_action=answer_questions + artifacts.questions - required_host_action=confirm_decision + artifacts.decision_options - protocol_check: add artifact convention validation with isinstance guard for non-dict artifacts (fail-closed, no crash) - Add clarification_pending and decision_pending compliance fixtures - Wire both fixtures into CI and release-preflight protocol smoke steps - tasks.md: W2.5 marked complete; plan.md snapshot updated Context-Checkpoint: A
… registry
The plan registry (_registry.yaml + runtime/plan/registry.py) served as a
machine-readable plan index/priority table. P8 replaces it with the 2-file
protocol state model (active_plan.json + current_handoff.json).
Deleted:
- .sopify-skills/plan/_registry.yaml (data file, 5 entries)
- runtime/plan/registry.py (955 lines)
- tests/test_runtime_plan_registry.py (301 lines)
Cleaned:
- runtime/engine.py: removed registry import, _registry_file_should_be_reported
- runtime/_planning.py: removed upsert_plan_entry, simplified _created_plan_notes
- runtime/output.py: removed _priority_note helper and 2 call sites
- runtime/archive_lifecycle.py: removed remove_plan_entry, registry_updated/notes
- runtime/manifest.py: removed plan_registry capability flags
- runtime/_yaml.py: removed dump_yaml/is_yaml_scalar/yaml_scalar (registry-only)
- tests/runtime_test_support.py: removed 7 registry re-exports
- tests/test_runtime_engine.py: removed 2 capability assertions
- installer/bootstrap_workspace.py: removed _registry.yaml from ignore entries
- docs/how-sopify-works.md/.en.md: removed _registry.yaml from tree + description
- skills/{zh,en}/header.md.template: removed _registry.yaml from tree
- .gitignore: removed _registry.yaml ignore rule
- .sopify-skills/project.md: removed registry cleanup instruction
Retained: sopify_protocol_check.py _registry.yaml forbidden guard (P8 gate).
…er/installer Delete 20 runtime behavior-mirror tests (~11.2K LOC) and runtime_test_support.py import hub. Surgically fix test_installer.py (remove runtime imports, switch gate-first assertions to protocol-first, retire runtime_gate capability), test_installer_status_doctor.py (bundle loops → protocol-kernel assets only, retire smoke_verified/preferences_preload), test_release_hooks.py (fixture paths → installer/payload.py + sopify_contracts/__init__.py, governance scope for checkpoint tests, legacy state → current_handoff.json). Delete test_installer_validate.py (bundle smoke only), conftest.py (implementation_mirror marker retired), fixtures/p4d_smoke/ + sample_invariant_gate_matrix.yaml. Add tests/test_sopify_writer.py (12 tests): StateStore 2-file invariants, handoff round-trip + observability injection, retired state file guard. 163 passed / 0 failed. rg runtime imports in tests/ → 0 hits. Context-Checkpoint: C
…c references Delete scripts/runtime_gate.py, scripts/sopify_runtime.py, scripts/check-prompt-runtime-gate-smoke.py, scripts/check-bundle-smoke.sh. Clean installer/validate.py: remove run_bundle_smoke_check() + 5 private helpers + smoke-only imports (os/shlex/subprocess). Fix handoff-first label in distribution.py and inspection.py from runtime to protocol. Replace CONTRIBUTING.md/CN Runtime Bundle sections with Payload Bundle sections and swap validation commands to protocol/payload smoke. Update skill-standards-refactor.md runtime-first to protocol-first. Keep installer/sopify_bundle.py (now protocol-kernel syncer, imported by payload.py). Keep check-install-payload-bundle-smoke.py (payload smoke, CI). 163 passed / 0 failed. Protocol smoke PASS. Payload smoke PASS. Context-Checkpoint: C
…ERIFIED
Rename SupportTier.DEEP_VERIFIED to PROTOCOL_VERIFIED across 5 files:
installer/models.py (enum), installer/hosts/{codex,claude}.py (tier ref),
scripts/check-enhancement-declaration.py (governance expectations + warning),
tests/test_installer_status_doctor.py (assertion strings).
Preserve Codex/Claude adapters, 5 verified_features, 3 declared_enhancements.
PROTOCOL_VERIFIED covers protocol entry + payload + bootstrap + handoff-first;
does not imply receipt/finalize write API (W2.9b/W3 scope).
Rewrite plan.md/tasks.md W2.9 section: "Remove Deep Host Adapters" →
"Reclassify Protocol-Verified Hosts" with boundary note.
163 passed / 0 failed. rg deep_verified in installer/scripts/tests → 0 hits.
Remove entire runtime/ directory — the pre-P8 runtime kernel is no longer needed after protocol-kernel cutover (sopify_writer + sopify_contracts). Fix CONTRIBUTING.md/CN: remove dead runtime/builtin_skill_packages/ path, replace runtime/skill_schema.py with sopify_contracts/skill_schema.py, remove "unless runtime explicitly enforces" wording. Fix sopify_writer/_resume.py docstring: "stays in runtime" → "retired with runtime/". Add W3.6 governance residual tracking: Plan A checkpoint scope cleanup, pre-commit dead patterns, CONTRIBUTING hook description. 163 passed / 0 failed. Protocol smoke PASS. runtime/ confirmed absent. Context-Checkpoint: C
Rename StateStore → ProtocolStore(sopify_root): unified write entry for protocol state, receipts, and finalize operations under .sopify-skills/. New API (all keyword-only): - write_plan_receipt: receipt_id pattern validation, plan_id/receipt_id conflict detection, auto-injects timestamp + provenance - write_history_receipt: Markdown rendering, outcome/summary/key_decisions validation, defaults month to current UTC YYYY-MM - finalize_plan: writes receipts/final.json + history receipt.md + clears active_plan/current_handoff state Boundary validation added: - set_active_plan rejects empty plan_id - write_plan_receipt rejects empty plan_id - key_decisions rejects any empty item (all non-empty, not just any) Export ProtocolStore + InvariantViolationError from sopify_writer package. 33 writer tests (30 + 3 boundary). 184 passed / 0 failed full suite. Protocol smoke 3 scenarios PASS.
Wave 2 Gate: 5/5 checks passed (runtime absent, registry absent, no active runtime imports, protocol 3 scenarios PASS, 184 tests green). Update plan/tasks status: W2 complete, W3 Qoder Host Proof next. Fix W2.11 test counts (33 writer / 184 total after boundary fixes). Update blueprint README focus line to reflect Gate passed. Add lightweight audit note: independent audit accepted, residuals assigned to W3.5/W3.6.
…n, rewrite project.md Phase 0 of P8 Wave 3: eliminate contradictions between post-P8 2-file state model and residual pre-P8 artifacts before Qoder host proof. State cleanup: delete 4 legacy state files + sessions/ directory (121 entries). Only current_handoff.json remains; active_plan.json pending next managed plan creation. Dead governance chain removal (atomic): delete check-context-checkpoints.py + test_context_checkpoints.py; clean references from .githooks/commit-msg, .github/workflows/ci.yml, scripts/release-preflight.sh, tests/test_release_hooks.py, CONTRIBUTING.md, CONTRIBUTING_CN.md. project.md rewrite: §Runtime 实现与测试约定 → §Protocol Kernel 实现与测试约定; Develop 质量约定 updated (develop_callback_runtime.py retired). Plan package docs reconciliation: design.md §9 delete-list corrected (sopify_bundle.py + codex/claude adapters kept), §10 Host Proof updated, §11 rewritten (Qoder PROTOCOL_VERIFIED home-scope hybrid, 5-point full-capability criteria). plan.md Wave 3 restructured with Phase 0 + updated W3.1-W3.3 + Key Decisions #19-23. tasks.md Phase 0 P0.1-P0.6 added and completed, Wave 3 Gate updated to 5+2 criteria. Tests: 180 passed / 0 failed. Protocol smoke: 3/3 PASS.
Register Qoder as the 4th official PROTOCOL_VERIFIED host alongside
Codex and Claude. Home-scope hybrid adapter installs to ~/.qoder/
(AGENTS.md + sopify/ payload), with bare --target qoder support via
default_language="zh-CN".
New files:
- installer/hosts/qoder.py (adapter + capability declaration)
Modified:
- installer/hosts/__init__.py: register QODER_HOST
- skills/hosts.yaml: add Qoder metadata
- installer/distribution.py: add Qoder display name
- installer/inspection.py: _recommend_target helper for bare/explicit
--target in doctor/status recommendations
- skills/{zh,en}/header.md.template: add Qoder column to tool mapping
- tests/golden-snapshots.json: regenerated (shared template change)
- tests/test_installer_status_doctor.py: host set 3→4 + qoder
capability contract test (PROTOCOL_VERIFIED, 5 features,
3 enhancements, adapter properties)
Plan package: Phase 0 + W3.1 status reconciliation.
181 passed / 0 failed. Protocol smoke: 3/3 PASS.
…ranscript W3.2 (installed payload capability proof): - sopify_writer importable from ~/.qoder/sopify/bundles/0.0.0-dev/ - ProtocolStore API writes active_plan + handoff + receipts + finalize - No repo-local sys.path hack, no thin wrapper needed W3.3 (durable end-to-end proof transcript): - scripts/w33_qoder_proof.py: reproducible proof script (15/15 PASS) - assets/w33-proof-transcript.md: persistent audit artifact - Session A → Session B → Finalize full chain verified - Scope: writer-level proof; LLM behavioral proof out of scope Plan package: W3.4 canonical root rename (.sopify-skills → .sopify) added with 6 sub-tasks + two-layer gate. Key Decision #24.
…oved Hard cutover from .sopify-skills to .sopify as the single canonical protocol root directory. No dual-path compatibility, no migration shim, no fallback to old directory name. Key decisions: - Canonical root = .sopify (fixed, not configurable) - plan.directory config field removed from sopify_contracts/core.py RuntimeConfig; runtime_root now hardcodes ".sopify" - plan.directory removed from all public surfaces: README (en/zh), header templates (en/zh), copilot-instructions.md, examples config - .gitignore patterns updated Changes: ~481 replacements across ~64 files - Implementation layer: installer/, scripts/, sopify_writer/ (51) - Test layer: tests/, fixtures (37) - Protocol + prompt + skill assets (171) - User docs path rename only, no narrative rewrite (26) - Physical directory: git mv .sopify-skills .sopify - Plan package + blueprint + assets self-update (196) Verification: - 181 passed / 0 failed - Protocol smoke 3/3 PASS - Engineering gate: 0 .sopify-skills hits - Consumption gate: 0 .sopify-skills hits - plan.directory grep: 0 hits in all active surfaces - install.sh --target qoder: success - Lightweight continuation check: PASS History: directory rename applied; historical content not rewritten. Reports: unchanged (historical records). W3.3 transcript: annotated with pre-rename execution note.
… aligned User-facing docs rewritten for clarity: - README intro: "protocol layer" → "saves your AI development process" - Architecture section: 4 bullets in plain language, no jargon - Host support matrix: Codex/Claude/Qoder = PROTOCOL_VERIFIED, Copilot = BASELINE_SUPPORTED - Directory structure: removed runtime/, added sopify_writer/ + sopify_contracts/ Architecture SVG regenerated (fireworks-tech-graph): - 4 clean layers: Host → Protocol → Workflow → Knowledge - User-friendly labels (Work Request, not ActionProposal) - Qoder added to host layer - Protocol State row with 2-file model + fail-open explanation How-sopify-works (EN/ZH): - Full rewrite: Core Value + Protocol Entry (4-step read chain) + 2-file state model - "Runtime retired; workflow retained" narrative - Harness PNG retirement note moved before image - Fail-open behavior documented Getting-started.md: - Removed retired capabilities from sopify.json example - state/ description: "protocol state, 2 files only" - Qoder added to requirements Supplementary fixes: - README resume promise: "persist in git" not "auto-resume" - Chinese README synchronized throughout - Workflow SVGs: Runtime Gate → Protocol Entry, Checkpoint-gated → Checkpoint-based 181 passed / 0 failed.
W3.4 rename missed tests/fixtures/clarification_pending/ and tests/fixtures/decision_pending/. Both still used .sopify-skills/ causing protocol smoke continuation scenario to fail with "Missing state/active_plan.json". 181 passed / 0 failed. Protocol smoke all scenarios PASS.
Blueprint (design.md): - Product positioning: "开发过程协议层" (development process protocol layer) - 4-layer table: 用户层/产品层/能力层/架构层 - Convergence chain: produce→verify→record evidence→settle (final) - Three-layer positioning: Protocol Kernel + Default Workflow + Host Adapters - Core pipeline: Validator → protocol admission - Runtime 五层架构: [RETIRED by P8] - 宿主能力治理: full rewrite (convention_only / payload_capable / protocol_verified) - 削减预算表: P8 Final with completion markers - Hard constraints: updated to post-P8 terms - Core contracts: Checkpoint/Archive/Runtime state scope → post-P8 ADR-013: P8 scope clarification → final ADR-017: SUPERSEDED → RETIRED (all instances) Protocol.md: P8 terminology mapping note, SUPERSEDED → RETIRED Product docs: - README: "development process protocol layer", tracked vs gitignored distinction - README.zh-CN: synchronized - Architecture SVG: regenerated with user-friendly labels, product slogans Active governance: - install.sh: "runtime" → "protocol kernel" - .githooks/pre-commit: runtime/* → sopify_writer/* + sopify_contracts/* Blueprint tasks.md: - Runtime retirement Phase 2 marked done - Protocol prose cleanup recorded as explicit future item - Product direction principle updated P8 plan package: W3.6 + Wave 3 Gate marked complete, status → Finalize 181 passed / 0 failed. Protocol smoke 3/3 PASS.
Finalize:
- F0: sopify.json — removed runtime_gate, workspace_kind → external
- F1: receipts/final.json — full evidence (6 keys)
- F2: Plan package archived to history/2026-06/, receipt.md enhanced,
state cleared, history/index.md + blueprint/README.md updated
- F3: CHANGELOG.md entry under [Unreleased]
Protocol prose de-ambiguation (release polish):
- §2: state/ "runtime管理" → "sopify_writer管理, 2文件"
- §3/§4: Validator → protocol admission
- §6: EAR unified to [RETIRED by P8], Validator退场说明
- §7: Subject Identity消费方更新, Runtime消费边界标RETIRED,
P8术语说明覆盖Validator MUST规则
- 非目标: runtime引用更新, state schema归sopify_writer
- 权限边界: Validator/runtime退场说明
Post-fix: docs/getting-started.md sopify.json expected output aligned
181 passed / 0 failed. Protocol smoke 3/3 PASS.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
P8 retires the Sopify runtime and establishes the protocol kernel as the sole truth source.
sopify_writer+sopify_contracts+protocol.md) is now the sole truth source.sopify-skills→.sopify(~481 replacements);plan.directoryconfigurable root removedactive_plan.json+current_handoff.json), both gitignoredPROTOCOL_VERIFIEDhost;DEEP_VERIFIED→PROTOCOL_VERIFIEDfor Codex/Claudereceipts/*.json+history/receipt.mdPartially addresses #55 — lays the protocol foundation (minimum contract, compliance smoke, non-deep host proof, tier boundaries) but does not yet deliver a third-party host self-serve quickstart. Remaining:
docs/host-onboarding.md, rewriteexamples/external-repo-quickstart, full LLM behavioral proof.Test Plan
pytest tests/ -q→ 181 passed, 26 subtests passedsopify_protocol_check3 scenarios → all PASSKey Decisions
.sopify;plan.directoryconfig removed--target qoder)Net Impact