From 631cfe6e80944730742e74a90644134a6b9dbb15 Mon Sep 17 00:00:00 2001 From: idevlab Date: Wed, 2 Sep 2026 18:50:16 +0800 Subject: [PATCH 1/2] Adopt schema-3 four-stage SDLC with mandatory approval gates. Replace legacy change.md bundles with intent/spec/plan/verification stages, add devflow CLI and checker enforcement, and migrate historical change records. Co-authored-by: Cursor --- .github/pull_request_template.md | 19 +- AGENTS.md | 11 +- docs/README.md | 2 +- docs/catalog.json | 27 +- .../2026-08-26-plugin-hot-reload/change.md | 95 -- .../2026-08-26-plugin-hot-reload/intent.md | 51 + .../2026-08-26-plugin-hot-reload/plan.md | 51 + .../2026-08-26-plugin-hot-reload/spec.md | 54 ++ .../verification.md | 91 ++ .../change.md | 104 -- .../intent.md | 52 + .../plan.md | 54 ++ .../spec.md | 60 ++ .../verification.md | 95 ++ .../change.md | 104 -- .../intent.md | 52 + .../plan.md | 54 ++ .../spec.md | 57 ++ .../verification.md | 100 ++ .../change.md | 99 -- .../intent.md | 51 + .../plan.md | 54 ++ .../spec.md | 54 ++ .../verification.md | 99 ++ .../change.md | 99 -- .../intent.md | 51 + .../plan.md | 53 + .../spec.md | 56 ++ .../verification.md | 97 ++ .../change.md | 102 -- .../intent.md | 51 + .../2026-08-29-semantic-radius-floor/plan.md | 53 + .../2026-08-29-semantic-radius-floor/spec.md | 57 ++ .../verification.md | 100 ++ .../change.md | 116 --- .../intent.md | 52 + .../plan.md | 56 ++ .../spec.md | 61 ++ .../verification.md | 112 +++ .../change.md | 129 --- .../intent.md | 62 ++ .../plan.md | 62 ++ .../spec.md | 68 ++ .../verification.md | 109 +++ .../change.md | 151 --- .../intent.md | 59 ++ .../plan.md | 61 ++ .../spec.md | 71 ++ .../verification.md | 136 +++ .../change.md | 105 -- .../intent.md | 50 + .../plan.md | 54 ++ .../spec.md | 54 ++ .../verification.md | 109 +++ .../change.md | 102 -- .../intent.md | 50 + .../plan.md | 52 + .../spec.md | 54 ++ .../verification.md | 108 +++ .../change.md | 159 --- .../intent.md | 54 ++ .../plan.md | 62 ++ .../spec.md | 73 ++ .../verification.md | 158 +++ .../change.md | 142 --- .../intent.md | 55 ++ .../plan.md | 68 ++ .../spec.md | 70 ++ .../verification.md | 119 +++ .../2026-08-30-feishu-realtime-sync/change.md | 170 ---- .../2026-08-30-feishu-realtime-sync/intent.md | 58 ++ .../2026-08-30-feishu-realtime-sync/plan.md | 72 ++ .../2026-08-30-feishu-realtime-sync/spec.md | 76 ++ .../verification.md | 147 +++ .../2026-08-30-flat-task-sections/change.md | 167 ---- .../2026-08-30-flat-task-sections/intent.md | 65 ++ .../2026-08-30-flat-task-sections/plan.md | 68 ++ .../2026-08-30-flat-task-sections/spec.md | 79 ++ .../verification.md | 136 +++ .../intent.md | 53 + .../plan.md | 56 ++ .../spec.md | 63 ++ .../{change.md => verification.md} | 127 ++- .../2026-08-30-plugin-connectors/change.md | 208 ---- .../2026-08-30-plugin-connectors/intent.md | 53 + .../2026-08-30-plugin-connectors/plan.md | 78 ++ .../2026-08-30-plugin-connectors/spec.md | 78 ++ .../verification.md | 217 +++++ .../intent.md | 54 ++ .../plan.md | 60 ++ .../spec.md | 65 ++ .../{change.md => verification.md} | 129 ++- .../change.md | 112 --- .../intent.md | 55 ++ .../plan.md | 57 ++ .../spec.md | 59 ++ .../verification.md | 101 ++ .../change.md | 155 --- .../intent.md | 68 ++ .../plan.md | 73 ++ .../spec.md | 81 ++ .../verification.md | 117 +++ .../2026-08-31-codex-design-system/change.md | 125 --- .../2026-08-31-codex-design-system/intent.md | 57 ++ .../2026-08-31-codex-design-system/plan.md | 58 ++ .../2026-08-31-codex-design-system/spec.md | 68 ++ .../verification.md | 101 ++ .../2026-08-31-codex-display-name/change.md | 105 -- .../2026-08-31-codex-display-name/intent.md | 54 ++ .../2026-08-31-codex-display-name/plan.md | 56 ++ .../2026-08-31-codex-display-name/spec.md | 57 ++ .../verification.md | 95 ++ .../change.md | 165 ---- .../intent.md | 71 ++ .../plan.md | 62 ++ .../spec.md | 83 ++ .../verification.md | 133 +++ .../change.md | 150 --- .../intent.md | 69 ++ .../plan.md | 71 ++ .../spec.md | 77 ++ .../verification.md | 118 +++ .../intent.md | 63 ++ .../plan.md | 81 ++ .../spec.md | 79 ++ .../{change.md => verification.md} | 229 ++--- .../change.md | 139 --- .../intent.md | 64 ++ .../plan.md | 64 ++ .../spec.md | 72 ++ .../verification.md | 129 +++ .../change.md | 171 ---- .../intent.md | 60 ++ .../plan.md | 67 ++ .../spec.md | 78 ++ .../verification.md | 157 +++ .../change.md | 108 --- .../intent.md | 52 + .../plan.md | 55 ++ .../spec.md | 57 ++ .../verification.md | 112 +++ .../change.md | 156 --- .../intent.md | 60 ++ .../plan.md | 67 ++ .../spec.md | 76 ++ .../verification.md | 134 +++ .../2026-08-31-normalize-all-docs/change.md | 175 ---- .../2026-08-31-normalize-all-docs/intent.md | 71 ++ .../2026-08-31-normalize-all-docs/plan.md | 95 ++ .../2026-08-31-normalize-all-docs/spec.md | 84 ++ .../verification.md | 112 +++ .../2026-08-31-organize-change-docs/change.md | 150 --- .../2026-08-31-organize-change-docs/intent.md | 69 ++ .../2026-08-31-organize-change-docs/plan.md | 81 ++ .../2026-08-31-organize-change-docs/spec.md | 77 ++ .../verification.md | 103 ++ .../2026-08-31-organize-scripts/change.md | 124 --- .../2026-08-31-organize-scripts/intent.md | 53 + .../2026-08-31-organize-scripts/plan.md | 71 ++ .../2026-08-31-organize-scripts/spec.md | 62 ++ .../verification.md | 94 ++ .../change.md | 140 --- .../intent.md | 60 ++ .../plan.md | 69 ++ .../spec.md | 68 ++ .../verification.md | 114 +++ .../change.md | 206 ---- .../intent.md | 77 ++ .../plan.md | 92 ++ .../spec.md | 100 ++ .../verification.md | 164 ++++ .../change.md | 185 ---- .../intent.md | 66 ++ .../plan.md | 68 ++ .../spec.md | 89 ++ .../verification.md | 156 +++ .../2026-08-31-radius-compliance/change.md | 155 --- .../2026-08-31-radius-compliance/intent.md | 66 ++ .../2026-08-31-radius-compliance/plan.md | 72 ++ .../2026-08-31-radius-compliance/spec.md | 72 ++ .../verification.md | 126 +++ .../2026-08-31-remove-liquid-gooey/change.md | 140 --- .../2026-08-31-remove-liquid-gooey/intent.md | 60 ++ .../2026-08-31-remove-liquid-gooey/plan.md | 65 ++ .../2026-08-31-remove-liquid-gooey/spec.md | 67 ++ .../verification.md | 124 +++ .../2026-08-31-remove-turn-feedback/change.md | 119 --- .../2026-08-31-remove-turn-feedback/intent.md | 55 ++ .../2026-08-31-remove-turn-feedback/plan.md | 59 ++ .../2026-08-31-remove-turn-feedback/spec.md | 59 ++ .../verification.md | 111 +++ .../change.md | 142 --- .../intent.md | 63 ++ .../plan.md | 69 ++ .../spec.md | 68 ++ .../verification.md | 112 +++ .../intent.md | 63 ++ .../plan.md | 87 ++ .../spec.md | 95 ++ .../{change.md => verification.md} | 259 +++-- .../change.md | 209 ---- .../intent.md | 65 ++ .../plan.md | 77 ++ .../spec.md | 97 ++ .../verification.md | 164 ++++ .../2026-08-31-simplify-docs-tree/change.md | 115 --- .../2026-08-31-simplify-docs-tree/intent.md | 53 + .../2026-08-31-simplify-docs-tree/plan.md | 69 ++ .../2026-08-31-simplify-docs-tree/spec.md | 60 ++ .../verification.md | 84 ++ .../change.md | 111 --- .../intent.md | 55 ++ .../plan.md | 62 ++ .../spec.md | 59 ++ .../verification.md | 93 ++ .../2026-08-31-strict-sdlc-v2/change.md | 145 --- .../2026-08-31-strict-sdlc-v2/intent.md | 67 ++ .../changes/2026-08-31-strict-sdlc-v2/plan.md | 71 ++ .../changes/2026-08-31-strict-sdlc-v2/spec.md | 75 ++ .../2026-08-31-strict-sdlc-v2/verification.md | 112 +++ .../2026-08-31-website-dual-theme/change.md | 201 ---- .../2026-08-31-website-dual-theme/intent.md | 69 ++ .../2026-08-31-website-dual-theme/plan.md | 73 ++ .../2026-08-31-website-dual-theme/spec.md | 86 ++ .../verification.md | 179 ++++ .../change.md | 206 ---- .../intent.md | 64 ++ .../plan.md | 79 ++ .../spec.md | 85 ++ .../verification.md | 179 ++++ .../change.md | 232 ----- .../intent.md | 69 ++ .../plan.md | 90 ++ .../spec.md | 103 ++ .../verification.md | 178 ++++ .../change.md | 166 ---- .../intent.md | 63 ++ .../plan.md | 67 ++ .../spec.md | 80 ++ .../verification.md | 137 +++ .../2026-09-02-four-stage-sdlc/intent.md | 56 ++ .../2026-09-02-four-stage-sdlc/plan.md | 54 ++ .../2026-09-02-four-stage-sdlc/spec.md | 59 ++ .../verification.md | 61 ++ .../intent.md | 58 ++ .../plan.md | 59 ++ .../spec.md | 60 ++ .../verification.md | 74 ++ docs/sdlc/development-workflow.md | 175 ++++ docs/sdlc/evals/ai-native-sdlc-gates.md | 6 +- docs/sdlc/references/artifact-contracts.md | 152 +++ docs/sdlc/templates/change.md | 90 -- docs/sdlc/templates/intent.md | 46 + docs/sdlc/templates/plan.md | 47 + docs/sdlc/templates/spec.md | 46 + docs/sdlc/templates/verification.md | 54 ++ docs/sdlc/workflow.md | 113 ++- script/README.md | 3 + script/devflow | 3 + script/devflow.test.ts | 57 ++ script/devflow.ts | 325 +++++++ script/sdlc/migrate-bundles.ts | 330 +++++++ script/verify/artifact-parse.ts | 222 +++++ script/verify/checks.test.ts | 298 +++--- script/verify/docs.ts | 6 +- script/verify/sdlc.ts | 903 ++++-------------- script/verify/stage-bundle.ts | 346 +++++++ 267 files changed, 18059 insertions(+), 7750 deletions(-) delete mode 100644 docs/sdlc/changes/2026-08-26-plugin-hot-reload/change.md create mode 100644 docs/sdlc/changes/2026-08-26-plugin-hot-reload/intent.md create mode 100644 docs/sdlc/changes/2026-08-26-plugin-hot-reload/plan.md create mode 100644 docs/sdlc/changes/2026-08-26-plugin-hot-reload/spec.md create mode 100644 docs/sdlc/changes/2026-08-26-plugin-hot-reload/verification.md delete mode 100644 docs/sdlc/changes/2026-08-29-appearance-settings-layout/change.md create mode 100644 docs/sdlc/changes/2026-08-29-appearance-settings-layout/intent.md create mode 100644 docs/sdlc/changes/2026-08-29-appearance-settings-layout/plan.md create mode 100644 docs/sdlc/changes/2026-08-29-appearance-settings-layout/spec.md create mode 100644 docs/sdlc/changes/2026-08-29-appearance-settings-layout/verification.md delete mode 100644 docs/sdlc/changes/2026-08-29-composer-surface-geometry/change.md create mode 100644 docs/sdlc/changes/2026-08-29-composer-surface-geometry/intent.md create mode 100644 docs/sdlc/changes/2026-08-29-composer-surface-geometry/plan.md create mode 100644 docs/sdlc/changes/2026-08-29-composer-surface-geometry/spec.md create mode 100644 docs/sdlc/changes/2026-08-29-composer-surface-geometry/verification.md delete mode 100644 docs/sdlc/changes/2026-08-29-empty-session-titlebar-divider/change.md create mode 100644 docs/sdlc/changes/2026-08-29-empty-session-titlebar-divider/intent.md create mode 100644 docs/sdlc/changes/2026-08-29-empty-session-titlebar-divider/plan.md create mode 100644 docs/sdlc/changes/2026-08-29-empty-session-titlebar-divider/spec.md create mode 100644 docs/sdlc/changes/2026-08-29-empty-session-titlebar-divider/verification.md delete mode 100644 docs/sdlc/changes/2026-08-29-pets-settings-surface-and-scroll/change.md create mode 100644 docs/sdlc/changes/2026-08-29-pets-settings-surface-and-scroll/intent.md create mode 100644 docs/sdlc/changes/2026-08-29-pets-settings-surface-and-scroll/plan.md create mode 100644 docs/sdlc/changes/2026-08-29-pets-settings-surface-and-scroll/spec.md create mode 100644 docs/sdlc/changes/2026-08-29-pets-settings-surface-and-scroll/verification.md delete mode 100644 docs/sdlc/changes/2026-08-29-semantic-radius-floor/change.md create mode 100644 docs/sdlc/changes/2026-08-29-semantic-radius-floor/intent.md create mode 100644 docs/sdlc/changes/2026-08-29-semantic-radius-floor/plan.md create mode 100644 docs/sdlc/changes/2026-08-29-semantic-radius-floor/spec.md create mode 100644 docs/sdlc/changes/2026-08-29-semantic-radius-floor/verification.md delete mode 100644 docs/sdlc/changes/2026-08-29-session-header-toolbar-unification/change.md create mode 100644 docs/sdlc/changes/2026-08-29-session-header-toolbar-unification/intent.md create mode 100644 docs/sdlc/changes/2026-08-29-session-header-toolbar-unification/plan.md create mode 100644 docs/sdlc/changes/2026-08-29-session-header-toolbar-unification/spec.md create mode 100644 docs/sdlc/changes/2026-08-29-session-header-toolbar-unification/verification.md delete mode 100644 docs/sdlc/changes/2026-08-30-ai-native-sdlc-learning-loop/change.md create mode 100644 docs/sdlc/changes/2026-08-30-ai-native-sdlc-learning-loop/intent.md create mode 100644 docs/sdlc/changes/2026-08-30-ai-native-sdlc-learning-loop/plan.md create mode 100644 docs/sdlc/changes/2026-08-30-ai-native-sdlc-learning-loop/spec.md create mode 100644 docs/sdlc/changes/2026-08-30-ai-native-sdlc-learning-loop/verification.md delete mode 100644 docs/sdlc/changes/2026-08-30-ai-native-sdlc-migration/change.md create mode 100644 docs/sdlc/changes/2026-08-30-ai-native-sdlc-migration/intent.md create mode 100644 docs/sdlc/changes/2026-08-30-ai-native-sdlc-migration/plan.md create mode 100644 docs/sdlc/changes/2026-08-30-ai-native-sdlc-migration/spec.md create mode 100644 docs/sdlc/changes/2026-08-30-ai-native-sdlc-migration/verification.md delete mode 100644 docs/sdlc/changes/2026-08-30-desktop-pet-pointer-interaction/change.md create mode 100644 docs/sdlc/changes/2026-08-30-desktop-pet-pointer-interaction/intent.md create mode 100644 docs/sdlc/changes/2026-08-30-desktop-pet-pointer-interaction/plan.md create mode 100644 docs/sdlc/changes/2026-08-30-desktop-pet-pointer-interaction/spec.md create mode 100644 docs/sdlc/changes/2026-08-30-desktop-pet-pointer-interaction/verification.md delete mode 100644 docs/sdlc/changes/2026-08-30-desktop-pet-remove-voice-control/change.md create mode 100644 docs/sdlc/changes/2026-08-30-desktop-pet-remove-voice-control/intent.md create mode 100644 docs/sdlc/changes/2026-08-30-desktop-pet-remove-voice-control/plan.md create mode 100644 docs/sdlc/changes/2026-08-30-desktop-pet-remove-voice-control/spec.md create mode 100644 docs/sdlc/changes/2026-08-30-desktop-pet-remove-voice-control/verification.md delete mode 100644 docs/sdlc/changes/2026-08-30-feishu-document-component/change.md create mode 100644 docs/sdlc/changes/2026-08-30-feishu-document-component/intent.md create mode 100644 docs/sdlc/changes/2026-08-30-feishu-document-component/plan.md create mode 100644 docs/sdlc/changes/2026-08-30-feishu-document-component/spec.md create mode 100644 docs/sdlc/changes/2026-08-30-feishu-document-component/verification.md delete mode 100644 docs/sdlc/changes/2026-08-30-feishu-document-markdown/change.md create mode 100644 docs/sdlc/changes/2026-08-30-feishu-document-markdown/intent.md create mode 100644 docs/sdlc/changes/2026-08-30-feishu-document-markdown/plan.md create mode 100644 docs/sdlc/changes/2026-08-30-feishu-document-markdown/spec.md create mode 100644 docs/sdlc/changes/2026-08-30-feishu-document-markdown/verification.md delete mode 100644 docs/sdlc/changes/2026-08-30-feishu-realtime-sync/change.md create mode 100644 docs/sdlc/changes/2026-08-30-feishu-realtime-sync/intent.md create mode 100644 docs/sdlc/changes/2026-08-30-feishu-realtime-sync/plan.md create mode 100644 docs/sdlc/changes/2026-08-30-feishu-realtime-sync/spec.md create mode 100644 docs/sdlc/changes/2026-08-30-feishu-realtime-sync/verification.md delete mode 100644 docs/sdlc/changes/2026-08-30-flat-task-sections/change.md create mode 100644 docs/sdlc/changes/2026-08-30-flat-task-sections/intent.md create mode 100644 docs/sdlc/changes/2026-08-30-flat-task-sections/plan.md create mode 100644 docs/sdlc/changes/2026-08-30-flat-task-sections/spec.md create mode 100644 docs/sdlc/changes/2026-08-30-flat-task-sections/verification.md create mode 100644 docs/sdlc/changes/2026-08-30-memory-settings-redesign/intent.md create mode 100644 docs/sdlc/changes/2026-08-30-memory-settings-redesign/plan.md create mode 100644 docs/sdlc/changes/2026-08-30-memory-settings-redesign/spec.md rename docs/sdlc/changes/2026-08-30-memory-settings-redesign/{change.md => verification.md} (50%) delete mode 100644 docs/sdlc/changes/2026-08-30-plugin-connectors/change.md create mode 100644 docs/sdlc/changes/2026-08-30-plugin-connectors/intent.md create mode 100644 docs/sdlc/changes/2026-08-30-plugin-connectors/plan.md create mode 100644 docs/sdlc/changes/2026-08-30-plugin-connectors/spec.md create mode 100644 docs/sdlc/changes/2026-08-30-plugin-connectors/verification.md create mode 100644 docs/sdlc/changes/2026-08-30-quiet-session-rail-items/intent.md create mode 100644 docs/sdlc/changes/2026-08-30-quiet-session-rail-items/plan.md create mode 100644 docs/sdlc/changes/2026-08-30-quiet-session-rail-items/spec.md rename docs/sdlc/changes/2026-08-30-quiet-session-rail-items/{change.md => verification.md} (50%) delete mode 100644 docs/sdlc/changes/2026-08-31-align-selectable-row-icons/change.md create mode 100644 docs/sdlc/changes/2026-08-31-align-selectable-row-icons/intent.md create mode 100644 docs/sdlc/changes/2026-08-31-align-selectable-row-icons/plan.md create mode 100644 docs/sdlc/changes/2026-08-31-align-selectable-row-icons/spec.md create mode 100644 docs/sdlc/changes/2026-08-31-align-selectable-row-icons/verification.md delete mode 100644 docs/sdlc/changes/2026-08-31-codex-appearance-controls/change.md create mode 100644 docs/sdlc/changes/2026-08-31-codex-appearance-controls/intent.md create mode 100644 docs/sdlc/changes/2026-08-31-codex-appearance-controls/plan.md create mode 100644 docs/sdlc/changes/2026-08-31-codex-appearance-controls/spec.md create mode 100644 docs/sdlc/changes/2026-08-31-codex-appearance-controls/verification.md delete mode 100644 docs/sdlc/changes/2026-08-31-codex-design-system/change.md create mode 100644 docs/sdlc/changes/2026-08-31-codex-design-system/intent.md create mode 100644 docs/sdlc/changes/2026-08-31-codex-design-system/plan.md create mode 100644 docs/sdlc/changes/2026-08-31-codex-design-system/spec.md create mode 100644 docs/sdlc/changes/2026-08-31-codex-design-system/verification.md delete mode 100644 docs/sdlc/changes/2026-08-31-codex-display-name/change.md create mode 100644 docs/sdlc/changes/2026-08-31-codex-display-name/intent.md create mode 100644 docs/sdlc/changes/2026-08-31-codex-display-name/plan.md create mode 100644 docs/sdlc/changes/2026-08-31-codex-display-name/spec.md create mode 100644 docs/sdlc/changes/2026-08-31-codex-display-name/verification.md delete mode 100644 docs/sdlc/changes/2026-08-31-desktop-motion-and-performance/change.md create mode 100644 docs/sdlc/changes/2026-08-31-desktop-motion-and-performance/intent.md create mode 100644 docs/sdlc/changes/2026-08-31-desktop-motion-and-performance/plan.md create mode 100644 docs/sdlc/changes/2026-08-31-desktop-motion-and-performance/spec.md create mode 100644 docs/sdlc/changes/2026-08-31-desktop-motion-and-performance/verification.md delete mode 100644 docs/sdlc/changes/2026-08-31-desktop-pet-conversation-bubble/change.md create mode 100644 docs/sdlc/changes/2026-08-31-desktop-pet-conversation-bubble/intent.md create mode 100644 docs/sdlc/changes/2026-08-31-desktop-pet-conversation-bubble/plan.md create mode 100644 docs/sdlc/changes/2026-08-31-desktop-pet-conversation-bubble/spec.md create mode 100644 docs/sdlc/changes/2026-08-31-desktop-pet-conversation-bubble/verification.md create mode 100644 docs/sdlc/changes/2026-08-31-device-connections-navigation/intent.md create mode 100644 docs/sdlc/changes/2026-08-31-device-connections-navigation/plan.md create mode 100644 docs/sdlc/changes/2026-08-31-device-connections-navigation/spec.md rename docs/sdlc/changes/2026-08-31-device-connections-navigation/{change.md => verification.md} (51%) delete mode 100644 docs/sdlc/changes/2026-08-31-fix-dock-tab-indicator-alignment/change.md create mode 100644 docs/sdlc/changes/2026-08-31-fix-dock-tab-indicator-alignment/intent.md create mode 100644 docs/sdlc/changes/2026-08-31-fix-dock-tab-indicator-alignment/plan.md create mode 100644 docs/sdlc/changes/2026-08-31-fix-dock-tab-indicator-alignment/spec.md create mode 100644 docs/sdlc/changes/2026-08-31-fix-dock-tab-indicator-alignment/verification.md delete mode 100644 docs/sdlc/changes/2026-08-31-group-session-toolbar-actions/change.md create mode 100644 docs/sdlc/changes/2026-08-31-group-session-toolbar-actions/intent.md create mode 100644 docs/sdlc/changes/2026-08-31-group-session-toolbar-actions/plan.md create mode 100644 docs/sdlc/changes/2026-08-31-group-session-toolbar-actions/spec.md create mode 100644 docs/sdlc/changes/2026-08-31-group-session-toolbar-actions/verification.md delete mode 100644 docs/sdlc/changes/2026-08-31-instant-session-tab-switching/change.md create mode 100644 docs/sdlc/changes/2026-08-31-instant-session-tab-switching/intent.md create mode 100644 docs/sdlc/changes/2026-08-31-instant-session-tab-switching/plan.md create mode 100644 docs/sdlc/changes/2026-08-31-instant-session-tab-switching/spec.md create mode 100644 docs/sdlc/changes/2026-08-31-instant-session-tab-switching/verification.md delete mode 100644 docs/sdlc/changes/2026-08-31-macos-titlebar-window-behavior/change.md create mode 100644 docs/sdlc/changes/2026-08-31-macos-titlebar-window-behavior/intent.md create mode 100644 docs/sdlc/changes/2026-08-31-macos-titlebar-window-behavior/plan.md create mode 100644 docs/sdlc/changes/2026-08-31-macos-titlebar-window-behavior/spec.md create mode 100644 docs/sdlc/changes/2026-08-31-macos-titlebar-window-behavior/verification.md delete mode 100644 docs/sdlc/changes/2026-08-31-normalize-all-docs/change.md create mode 100644 docs/sdlc/changes/2026-08-31-normalize-all-docs/intent.md create mode 100644 docs/sdlc/changes/2026-08-31-normalize-all-docs/plan.md create mode 100644 docs/sdlc/changes/2026-08-31-normalize-all-docs/spec.md create mode 100644 docs/sdlc/changes/2026-08-31-normalize-all-docs/verification.md delete mode 100644 docs/sdlc/changes/2026-08-31-organize-change-docs/change.md create mode 100644 docs/sdlc/changes/2026-08-31-organize-change-docs/intent.md create mode 100644 docs/sdlc/changes/2026-08-31-organize-change-docs/plan.md create mode 100644 docs/sdlc/changes/2026-08-31-organize-change-docs/spec.md create mode 100644 docs/sdlc/changes/2026-08-31-organize-change-docs/verification.md delete mode 100644 docs/sdlc/changes/2026-08-31-organize-scripts/change.md create mode 100644 docs/sdlc/changes/2026-08-31-organize-scripts/intent.md create mode 100644 docs/sdlc/changes/2026-08-31-organize-scripts/plan.md create mode 100644 docs/sdlc/changes/2026-08-31-organize-scripts/spec.md create mode 100644 docs/sdlc/changes/2026-08-31-organize-scripts/verification.md delete mode 100644 docs/sdlc/changes/2026-08-31-panel-window-controls-safe-area/change.md create mode 100644 docs/sdlc/changes/2026-08-31-panel-window-controls-safe-area/intent.md create mode 100644 docs/sdlc/changes/2026-08-31-panel-window-controls-safe-area/plan.md create mode 100644 docs/sdlc/changes/2026-08-31-panel-window-controls-safe-area/spec.md create mode 100644 docs/sdlc/changes/2026-08-31-panel-window-controls-safe-area/verification.md delete mode 100644 docs/sdlc/changes/2026-08-31-prevent-list-header-tab-overflow/change.md create mode 100644 docs/sdlc/changes/2026-08-31-prevent-list-header-tab-overflow/intent.md create mode 100644 docs/sdlc/changes/2026-08-31-prevent-list-header-tab-overflow/plan.md create mode 100644 docs/sdlc/changes/2026-08-31-prevent-list-header-tab-overflow/spec.md create mode 100644 docs/sdlc/changes/2026-08-31-prevent-list-header-tab-overflow/verification.md delete mode 100644 docs/sdlc/changes/2026-08-31-provider-runtime-and-model-management/change.md create mode 100644 docs/sdlc/changes/2026-08-31-provider-runtime-and-model-management/intent.md create mode 100644 docs/sdlc/changes/2026-08-31-provider-runtime-and-model-management/plan.md create mode 100644 docs/sdlc/changes/2026-08-31-provider-runtime-and-model-management/spec.md create mode 100644 docs/sdlc/changes/2026-08-31-provider-runtime-and-model-management/verification.md delete mode 100644 docs/sdlc/changes/2026-08-31-radius-compliance/change.md create mode 100644 docs/sdlc/changes/2026-08-31-radius-compliance/intent.md create mode 100644 docs/sdlc/changes/2026-08-31-radius-compliance/plan.md create mode 100644 docs/sdlc/changes/2026-08-31-radius-compliance/spec.md create mode 100644 docs/sdlc/changes/2026-08-31-radius-compliance/verification.md delete mode 100644 docs/sdlc/changes/2026-08-31-remove-liquid-gooey/change.md create mode 100644 docs/sdlc/changes/2026-08-31-remove-liquid-gooey/intent.md create mode 100644 docs/sdlc/changes/2026-08-31-remove-liquid-gooey/plan.md create mode 100644 docs/sdlc/changes/2026-08-31-remove-liquid-gooey/spec.md create mode 100644 docs/sdlc/changes/2026-08-31-remove-liquid-gooey/verification.md delete mode 100644 docs/sdlc/changes/2026-08-31-remove-turn-feedback/change.md create mode 100644 docs/sdlc/changes/2026-08-31-remove-turn-feedback/intent.md create mode 100644 docs/sdlc/changes/2026-08-31-remove-turn-feedback/plan.md create mode 100644 docs/sdlc/changes/2026-08-31-remove-turn-feedback/spec.md create mode 100644 docs/sdlc/changes/2026-08-31-remove-turn-feedback/verification.md delete mode 100644 docs/sdlc/changes/2026-08-31-replace-design-checker-with-lint/change.md create mode 100644 docs/sdlc/changes/2026-08-31-replace-design-checker-with-lint/intent.md create mode 100644 docs/sdlc/changes/2026-08-31-replace-design-checker-with-lint/plan.md create mode 100644 docs/sdlc/changes/2026-08-31-replace-design-checker-with-lint/spec.md create mode 100644 docs/sdlc/changes/2026-08-31-replace-design-checker-with-lint/verification.md create mode 100644 docs/sdlc/changes/2026-08-31-separate-quick-and-side-chat/intent.md create mode 100644 docs/sdlc/changes/2026-08-31-separate-quick-and-side-chat/plan.md create mode 100644 docs/sdlc/changes/2026-08-31-separate-quick-and-side-chat/spec.md rename docs/sdlc/changes/2026-08-31-separate-quick-and-side-chat/{change.md => verification.md} (50%) delete mode 100644 docs/sdlc/changes/2026-08-31-sidebar-organization-git-status/change.md create mode 100644 docs/sdlc/changes/2026-08-31-sidebar-organization-git-status/intent.md create mode 100644 docs/sdlc/changes/2026-08-31-sidebar-organization-git-status/plan.md create mode 100644 docs/sdlc/changes/2026-08-31-sidebar-organization-git-status/spec.md create mode 100644 docs/sdlc/changes/2026-08-31-sidebar-organization-git-status/verification.md delete mode 100644 docs/sdlc/changes/2026-08-31-simplify-docs-tree/change.md create mode 100644 docs/sdlc/changes/2026-08-31-simplify-docs-tree/intent.md create mode 100644 docs/sdlc/changes/2026-08-31-simplify-docs-tree/plan.md create mode 100644 docs/sdlc/changes/2026-08-31-simplify-docs-tree/spec.md create mode 100644 docs/sdlc/changes/2026-08-31-simplify-docs-tree/verification.md delete mode 100644 docs/sdlc/changes/2026-08-31-stabilize-desktop-dom-harness/change.md create mode 100644 docs/sdlc/changes/2026-08-31-stabilize-desktop-dom-harness/intent.md create mode 100644 docs/sdlc/changes/2026-08-31-stabilize-desktop-dom-harness/plan.md create mode 100644 docs/sdlc/changes/2026-08-31-stabilize-desktop-dom-harness/spec.md create mode 100644 docs/sdlc/changes/2026-08-31-stabilize-desktop-dom-harness/verification.md delete mode 100644 docs/sdlc/changes/2026-08-31-strict-sdlc-v2/change.md create mode 100644 docs/sdlc/changes/2026-08-31-strict-sdlc-v2/intent.md create mode 100644 docs/sdlc/changes/2026-08-31-strict-sdlc-v2/plan.md create mode 100644 docs/sdlc/changes/2026-08-31-strict-sdlc-v2/spec.md create mode 100644 docs/sdlc/changes/2026-08-31-strict-sdlc-v2/verification.md delete mode 100644 docs/sdlc/changes/2026-08-31-website-dual-theme/change.md create mode 100644 docs/sdlc/changes/2026-08-31-website-dual-theme/intent.md create mode 100644 docs/sdlc/changes/2026-08-31-website-dual-theme/plan.md create mode 100644 docs/sdlc/changes/2026-08-31-website-dual-theme/spec.md create mode 100644 docs/sdlc/changes/2026-08-31-website-dual-theme/verification.md delete mode 100644 docs/sdlc/changes/2026-08-31-website-landing-light-dark/change.md create mode 100644 docs/sdlc/changes/2026-08-31-website-landing-light-dark/intent.md create mode 100644 docs/sdlc/changes/2026-08-31-website-landing-light-dark/plan.md create mode 100644 docs/sdlc/changes/2026-08-31-website-landing-light-dark/spec.md create mode 100644 docs/sdlc/changes/2026-08-31-website-landing-light-dark/verification.md delete mode 100644 docs/sdlc/changes/2026-08-31-website-terminal-motion/change.md create mode 100644 docs/sdlc/changes/2026-08-31-website-terminal-motion/intent.md create mode 100644 docs/sdlc/changes/2026-08-31-website-terminal-motion/plan.md create mode 100644 docs/sdlc/changes/2026-08-31-website-terminal-motion/spec.md create mode 100644 docs/sdlc/changes/2026-08-31-website-terminal-motion/verification.md delete mode 100644 docs/sdlc/changes/2026-08-31-website-ui-detail-polish/change.md create mode 100644 docs/sdlc/changes/2026-08-31-website-ui-detail-polish/intent.md create mode 100644 docs/sdlc/changes/2026-08-31-website-ui-detail-polish/plan.md create mode 100644 docs/sdlc/changes/2026-08-31-website-ui-detail-polish/spec.md create mode 100644 docs/sdlc/changes/2026-08-31-website-ui-detail-polish/verification.md create mode 100644 docs/sdlc/changes/2026-09-02-four-stage-sdlc/intent.md create mode 100644 docs/sdlc/changes/2026-09-02-four-stage-sdlc/plan.md create mode 100644 docs/sdlc/changes/2026-09-02-four-stage-sdlc/spec.md create mode 100644 docs/sdlc/changes/2026-09-02-four-stage-sdlc/verification.md create mode 100644 docs/sdlc/changes/2026-09-02-sdlc-devflow-and-skill-integration/intent.md create mode 100644 docs/sdlc/changes/2026-09-02-sdlc-devflow-and-skill-integration/plan.md create mode 100644 docs/sdlc/changes/2026-09-02-sdlc-devflow-and-skill-integration/spec.md create mode 100644 docs/sdlc/changes/2026-09-02-sdlc-devflow-and-skill-integration/verification.md create mode 100644 docs/sdlc/development-workflow.md create mode 100644 docs/sdlc/references/artifact-contracts.md delete mode 100644 docs/sdlc/templates/change.md create mode 100644 docs/sdlc/templates/intent.md create mode 100644 docs/sdlc/templates/plan.md create mode 100644 docs/sdlc/templates/spec.md create mode 100644 docs/sdlc/templates/verification.md create mode 100755 script/devflow create mode 100644 script/devflow.test.ts create mode 100644 script/devflow.ts create mode 100644 script/sdlc/migrate-bundles.ts create mode 100644 script/verify/artifact-parse.ts create mode 100644 script/verify/stage-bundle.ts diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index f9ee9e1f..e65976be 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,12 +1,13 @@ -## Canonical change Artifact +## Canonical change bundle -Link the canonical `docs/sdlc/changes/-/change.md`: +Link the canonical `docs/sdlc/changes/-/` bundle: -- Change: -- Schema: -- Lifecycle status: -- Intent/Spec approval: -- Risk and scope: +- Bundle: +- Schema: +- Intent approval: +- Spec approval: +- Plan approval: +- Verification status: ## Outcome @@ -14,8 +15,8 @@ Describe the observable product or repository result, not the implementation dia ## Verification -- [ ] Every `AC-N` acceptance criterion is mapped to one actual command or linked evidence item. -- [ ] The Artifact records `Verdict:` and `Residual risk:` consistently with its status. +- [ ] Every `AC-N` acceptance criterion is mapped to one actual command or linked evidence item in `verification.md`. +- [ ] `verification.md` records `Verdict:` and residual risk consistently with its status. - [ ] Verification mode, verifier, and date match the risk lane; high/critical verification is independent. - [ ] Relevant Rust, desktop, documentation, packaging, or runtime checks passed. - [ ] User-visible UI changes include real light, dark, and narrow evidence where applicable. diff --git a/AGENTS.md b/AGENTS.md index 620a25b8..8ac51232 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,6 +8,11 @@ checkout. [`docs/sdlc/workflow.md`](docs/sdlc/workflow.md) is the single source of truth for material change Artifacts, lifecycle states, Gates, verification evidence, release handoff, Incidents, and Evals. +Use [`docs/sdlc/development-workflow.md`](docs/sdlc/development-workflow.md) and +[`./script/devflow`](script/devflow) for daily change creation, approval recording, and validation. +Install the external [`sdlc-skill`](https://github.com/IchenDEV/sdlc-skill) `ai-native-sdlc` skill +when Bootstrap, audit, or incident-to-improvement guidance is needed; the repository checker remains +the enforcement source. - A direct user implementation request may approve Intent. Record its source, constraints, named approver, and observable acceptance in one change Artifact, then move it to `executing` before @@ -19,8 +24,10 @@ Artifacts, lifecycle states, Gates, verification evidence, release handoff, Inci always run `bun script/verify/docs.ts`, `bun script/verify/sdlc.ts`, and `bun script/verify/sdlc.ts --worktree`. A PR that changes repository files must change or add a schema-2 canonical - `docs/sdlc/changes/-/change.md`; implementation differences require that Artifact to - be `executing` or later and every changed path to fall under its explicit scope. + `docs/sdlc/changes/-/` with schema-3 stage files (`intent.md`, `spec.md`, + `plan.md`, `verification.md`); implementation differences require that bundle's + `intent.md`, `spec.md`, and `plan.md` to be `accepted` and every changed path to fall under its + explicit `plan.md` scope. - Do not create `docs/superpowers`, a parallel specs/plans tree, or another lifecycle registry. - Every file under `docs/` must match exactly one rule in `docs/catalog.json`; dated research and completed plans belong under `docs/archive/`, and every documentation image must be referenced. diff --git a/docs/README.md b/docs/README.md index 8bf4796c..4ab3e2bd 100644 --- a/docs/README.md +++ b/docs/README.md @@ -10,7 +10,7 @@ The top level is organized by purpose. Start with the directory that matches the | [`design/`](design/README.md) | Current design system plus accepted future product designs | | [`adr/`](adr/0001-scenes-v2-dynamic-task-orchestration.md) | Accepted architecture decisions | | [`screenshots/`](screenshots/README.md) | Images used by the README and published documentation | -| [`sdlc/`](sdlc/workflow.md) | Development workflow, change records, templates, and Evals | +| [`sdlc/`](sdlc/workflow.md) | Development workflow, change records, templates, Evals, and [`development-workflow.md`](sdlc/development-workflow.md) operator guide | | [`archive/`](archive/README.md) | Historical research, completed plans, and old visual evidence | The public user guide lives under [`../website`](../website/). Archived material is non-normative diff --git a/docs/catalog.json b/docs/catalog.json index cc456477..1415fa1b 100644 --- a/docs/catalog.json +++ b/docs/catalog.json @@ -50,16 +50,35 @@ "authority": "current", "paths": [ "docs/sdlc/workflow.md", - "docs/sdlc/templates/change.md", + "docs/sdlc/development-workflow.md", + "docs/sdlc/references/artifact-contracts.md", + "docs/sdlc/templates/intent.md", + "docs/sdlc/templates/spec.md", + "docs/sdlc/templates/plan.md", + "docs/sdlc/templates/verification.md", "docs/sdlc/templates/eval.md", - "docs/sdlc/templates/incident.md", - "docs/sdlc/evals/ai-native-sdlc-gates.md" + "docs/sdlc/templates/incident.md" ] }, + { + "classification": "incident-record-flat", + "authority": "historical-state", + "pattern": "^docs/sdlc/incidents/[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*\\.md$" + }, + { + "classification": "eval-record", + "authority": "historical-state", + "pattern": "^docs/sdlc/evals/[a-z0-9-]+\\.md$" + }, { "classification": "change-record", "authority": "historical-state", - "pattern": "^docs/sdlc/changes/[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*/change\\.md$" + "pattern": "^docs/sdlc/changes/[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*\/intent\\.md$" + }, + { + "classification": "change-stage", + "authority": "historical-state", + "pattern": "^docs/sdlc/changes/[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*\/(spec|plan|verification)\\.md$" }, { "classification": "change-evidence", diff --git a/docs/sdlc/changes/2026-08-26-plugin-hot-reload/change.md b/docs/sdlc/changes/2026-08-26-plugin-hot-reload/change.md deleted file mode 100644 index d1757887..00000000 --- a/docs/sdlc/changes/2026-08-26-plugin-hot-reload/change.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -id: change-2026-08-26-plugin-hot-reload -kind: change -schema: 2 -status: closed -risk: low -owner: repository maintainers -approvers: "#decision-and-gates" -approved_at: 2026-08-26 -created: 2026-08-26 -updated: 2026-08-31 -source: "#intent" -inputs: "#spec" -outputs: "#build" -scope: crates/plugins, apps/desktop, docs/reference/plugins.md -next_trigger: new plugin-development feedback or regression -verification_mode: human -verified_by: PR #110 reviewers -verified_at: 2026-08-29 ---- - -# Plugin hot reload and developer tools - -## Intent - -Plugin authors needed an opt-in way to reload an installed Bundle while developing it without -restarting C2 or disturbing unrelated plugin runtimes. The original source artifacts were the -retired `docs/superpowers/specs` and `docs/superpowers/plans` files preserved in Git history at -commits `59ed917` and `289e6f0`. - -## Spec - -The accepted design required a persisted global developer-mode switch, a native watcher over the -installed Bundle directory, debounced reload of only affected Bundle runtimes, explicit status and -manual reload commands, and a quiet accessible Developer settings surface. Native Rust plugins -remain on the rebuild-and-restart path. - -### Acceptance criteria - -- [x] AC-1: Targeted reload replaces the affected Bundle runtime without replacing an unrelated runtime. -- [x] AC-2: Developer mode persists, starts/stops watching, and leaves manual reload available. -- [x] AC-3: Desktop bridge and settings expose status, reload, error, and WebView DevTools behavior. -- [x] AC-4: The installed-directory and native-plugin boundaries are documented. - -## Decision and gates - -The design and implementation were accepted through GitHub PR #110. Trust remains an execution -Gate for installed process runtimes, and this developer switch does not expand bundle permissions. - -## Plan - -The implementation was split across targeted runtime reload, watcher/commands, desktop event and -bridge wiring, Developer settings, documentation, and focused Rust/Bun verification. - -## Build - -Implementation commit `dc177195221760f56b7ce6ddfc57708ea862c6ac` added the feature. Later Core -boundary refactors moved shared composition to `crates/plugins` without introducing a second -plugin-development path. Current behavior is documented in [`docs/reference/plugins.md`](../../../reference/plugins.md#developing-an-installed-bundle). - -## Verification - -The implementation contains targeted reload and developer-mode integration coverage in -`crates/plugins/tests/project_bundle_runtime.rs`, plus bridge and rendered settings tests under -`apps/desktop/tests`. On 2026-08-29, focused desktop coverage passed 4 tests with 46 assertions. -The Rust reload/developer tests were attempted but did not start because the unchanged -`libghostty-vt-sys` build failed first with Zig's `use of undeclared identifier 'INFINITY'` error. -[PR #178's SDLC run](https://github.com/IchenDEV/codeTwo/actions/runs/33198244379) separately passed -the repository contract and base-diff Gate. - -Verdict: verified. - -### Acceptance evidence - -- AC-1: PASS — [`project_bundle_runtime.rs`](../../../../crates/plugins/tests/project_bundle_runtime.rs) retains targeted runtime-reload coverage. -- AC-2: PASS — `bun test` focused desktop coverage passed 4 tests with 46 assertions on 2026-08-29. -- AC-3: PASS — [`apps/desktop/tests`](../../../../apps/desktop/tests) retains bridge and rendered settings coverage. -- AC-4: PASS — [`plugins.md`](../../../reference/plugins.md#developing-an-installed-bundle) documents the installed-directory and native-plugin boundaries. - -Residual risk: focused Rust behavior remains unverified because of the recorded Ghostty/Zig build -blocker; repository integration evidence does not prove public product release. - -## Review and release - -PR #110 merged the implementation to `main` in commit `310b309`. This is repository integration -evidence, not a claim that the feature shipped in a notarized public C2 release. - -No release: the historical change is closed as merged repository work without a versioned or -notarized product release claim. - -## Feedback - -The unchecked retired Plan was misleading after merge and referenced the old `superpowers:*` -execution system. This closed record replaces both legacy files while retaining their source -commits and current implementation evidence. diff --git a/docs/sdlc/changes/2026-08-26-plugin-hot-reload/intent.md b/docs/sdlc/changes/2026-08-26-plugin-hot-reload/intent.md new file mode 100644 index 00000000..aaa8d588 --- /dev/null +++ b/docs/sdlc/changes/2026-08-26-plugin-hot-reload/intent.md @@ -0,0 +1,51 @@ +--- +id: "2026-08-26-plugin-hot-reload" +stage: intent +schema: 3 +status: accepted +owner: repository maintainers +created: 2026-08-26 +source: #intent +risk: low +approved_by: "#decision-and-gates" +approved_at: "2026-08-26" +--- + +# Intent: Plugin hot reload and developer tools + +## Problem + +Plugin authors needed an opt-in way to reload an installed Bundle while developing it without +restarting C2 or disturbing unrelated plugin runtimes. The original source artifacts were the +retired `docs/superpowers/specs` and `docs/superpowers/plans` files preserved in Git history at +commits `59ed917` and `289e6f0`. + +## Proposed outcome + +Plugin authors needed an opt-in way to reload an installed Bundle while developing it without + +## Affected users and systems + +Migrated from legacy change.md. + +## Constraints + +The design and implementation were accepted through GitHub PR #110. Trust remains an execution +Gate for installed process runtimes, and this developer switch does not expand bundle permissions. + +## Out of scope + +Not recorded in the legacy single-file Artifact. + +## Success signals + +See Spec acceptance criteria. + +## Open questions + +None recorded in migration. + +## Decision + +The design and implementation were accepted through GitHub PR #110. Trust remains an execution +Gate for installed process runtimes, and this developer switch does not expand bundle permissions. diff --git a/docs/sdlc/changes/2026-08-26-plugin-hot-reload/plan.md b/docs/sdlc/changes/2026-08-26-plugin-hot-reload/plan.md new file mode 100644 index 00000000..ac2a5647 --- /dev/null +++ b/docs/sdlc/changes/2026-08-26-plugin-hot-reload/plan.md @@ -0,0 +1,51 @@ +--- +id: "2026-08-26-plugin-hot-reload" +stage: plan +schema: 3 +status: accepted +owner: repository maintainers +created: 2026-08-26 +based_on: spec.md +risk: low +scope: crates/plugins, apps/desktop, docs/reference/plugins.md +approved_by: "#decision-and-gates" +approved_at: "2026-08-26" +--- + +# Plan: Plugin hot reload and developer tools + +## Files and ownership + +crates/plugins, apps/desktop, docs/reference/plugins.md + +## Order of work + +The implementation was split across targeted runtime reload, watcher/commands, desktop event and +bridge wiring, Developer settings, documentation, and focused Rust/Bun verification. + +## Test-first proof + +See legacy Verification section. + +## Visual or integration proof + +See legacy Verification section. + +## Risks and mitigations + +See legacy Decision and gates. + +## Rollback + +See legacy Review and release. + +## Deviations + +Implementation commit `dc177195221760f56b7ce6ddfc57708ea862c6ac` added the feature. Later Core +boundary refactors moved shared composition to `crates/plugins` without introducing a second +plugin-development path. Current behavior is documented in [`docs/reference/plugins.md`](../../../reference/plugins.md#developing-an-installed-bundle). + +## Decision + +The design and implementation were accepted through GitHub PR #110. Trust remains an execution +Gate for installed process runtimes, and this developer switch does not expand bundle permissions. diff --git a/docs/sdlc/changes/2026-08-26-plugin-hot-reload/spec.md b/docs/sdlc/changes/2026-08-26-plugin-hot-reload/spec.md new file mode 100644 index 00000000..4fde6e2b --- /dev/null +++ b/docs/sdlc/changes/2026-08-26-plugin-hot-reload/spec.md @@ -0,0 +1,54 @@ +--- +id: "2026-08-26-plugin-hot-reload" +stage: spec +schema: 3 +status: accepted +owner: repository maintainers +created: 2026-08-26 +based_on: intent.md +risk: low +approved_by: "#decision-and-gates" +approved_at: "2026-08-26" +--- + +# Spec: Plugin hot reload and developer tools + +## Requirements + +The accepted design required a persisted global developer-mode switch, a native watcher over the +installed Bundle directory, debounced reload of only affected Bundle runtimes, explicit status and +manual reload commands, and a quiet accessible Developer settings surface. Native Rust plugins +remain on the rebuild-and-restart path. + +## User experience + +Not separately recorded in legacy change.md. + +## Technical design + +See Requirements and legacy Git history. + +## Security and privacy + +See migrated Decision and gates. + +## Alternatives and non-goals + +Not separately recorded in legacy change.md. + +## Areas of concern + +The design and implementation were accepted through GitHub PR #110. Trust remains an execution +Gate for installed process runtimes, and this developer switch does not expand bundle permissions. + +## Acceptance criteria + +- [x] AC-1: Targeted reload replaces the affected Bundle runtime without replacing an unrelated runtime. +- [x] AC-2: Developer mode persists, starts/stops watching, and leaves manual reload available. +- [x] AC-3: Desktop bridge and settings expose status, reload, error, and WebView DevTools behavior. +- [x] AC-4: The installed-directory and native-plugin boundaries are documented. + +## Decision + +The design and implementation were accepted through GitHub PR #110. Trust remains an execution +Gate for installed process runtimes, and this developer switch does not expand bundle permissions. diff --git a/docs/sdlc/changes/2026-08-26-plugin-hot-reload/verification.md b/docs/sdlc/changes/2026-08-26-plugin-hot-reload/verification.md new file mode 100644 index 00000000..9bfa46c1 --- /dev/null +++ b/docs/sdlc/changes/2026-08-26-plugin-hot-reload/verification.md @@ -0,0 +1,91 @@ +--- +id: "2026-08-26-plugin-hot-reload" +stage: verification +schema: 3 +status: passed +owner: repository maintainers +created: 2026-08-26 +based_on: plan.md +commit: "" +verification_mode: human +verified_by: "PR #110 reviewers" +verified_at: "2026-08-29" +release_target: none +release_identity: "" +--- + +# Verification: Plugin hot reload and developer tools + +## Automated checks + +The implementation contains targeted reload and developer-mode integration coverage in +`crates/plugins/tests/project_bundle_runtime.rs`, plus bridge and rendered settings tests under +`apps/desktop/tests`. On 2026-08-29, focused desktop coverage passed 4 tests with 46 assertions. +The Rust reload/developer tests were attempted but did not start because the unchanged +`libghostty-vt-sys` build failed first with Zig's `use of undeclared identifier 'INFINITY'` error. +[PR #178's SDLC run](https://github.com/IchenDEV/codeTwo/actions/runs/33198244379) separately passed +the repository contract and base-diff Gate. + +Verdict: verified. + +### Acceptance evidence + +- AC-1: PASS — [`project_bundle_runtime.rs`](../../../../crates/plugins/tests/project_bundle_runtime.rs) retains targeted runtime-reload coverage. +- AC-2: PASS — `bun test` focused desktop coverage passed 4 tests with 46 assertions on 2026-08-29. +- AC-3: PASS — [`apps/desktop/tests`](../../../../apps/desktop/tests) retains bridge and rendered settings coverage. +- AC-4: PASS — [`plugins.md`](../../../reference/plugins.md#developing-an-installed-bundle) documents the installed-directory and native-plugin boundaries. + +Residual risk: focused Rust behavior remains unverified because of the recorded Ghostty/Zig build +blocker; repository integration evidence does not prove public product release. + +## Behavioral evidence + +The implementation contains targeted reload and developer-mode integration coverage in +`crates/plugins/tests/project_bundle_runtime.rs`, plus bridge and rendered settings tests under +`apps/desktop/tests`. On 2026-08-29, focused desktop coverage passed 4 tests with 46 assertions. +The Rust reload/developer tests were attempted but did not start because the unchanged +`libghostty-vt-sys` build failed first with Zig's `use of undeclared identifier 'INFINITY'` error. +[PR #178's SDLC run](https://github.com/IchenDEV/codeTwo/actions/runs/33198244379) separately passed +the repository contract and base-diff Gate. + +Verdict: verified. + +### Acceptance evidence + +- AC-1: PASS — [`project_bundle_runtime.rs`](../../../../crates/plugins/tests/project_bundle_runtime.rs) retains targeted runtime-reload coverage. +- AC-2: PASS — `bun test` focused desktop coverage passed 4 tests with 46 assertions on 2026-08-29. +- AC-3: PASS — [`apps/desktop/tests`](../../../../apps/desktop/tests) retains bridge and rendered settings coverage. +- AC-4: PASS — [`plugins.md`](../../../reference/plugins.md#developing-an-installed-bundle) documents the installed-directory and native-plugin boundaries. + +Residual risk: focused Rust behavior remains unverified because of the recorded Ghostty/Zig build +blocker; repository integration evidence does not prove public product release. + +## Visual evidence + +See bundle evidence/ when present. + +## Security and privacy evidence + +Not separately recorded unless present in legacy Verification. + +## Deviations and residual risk + +Residual risk: focused Rust behavior remains unverified because of the recorded Ghostty/Zig build + +## Verdict + +Verdict: verified.. + +## Review and release + +PR #110 merged the implementation to `main` in commit `310b309`. This is repository integration +evidence, not a claim that the feature shipped in a notarized public C2 release. + +No release: the historical change is closed as merged repository work without a versioned or +notarized product release claim. + +## Feedback + +The unchecked retired Plan was misleading after merge and referenced the old `superpowers:*` +execution system. This closed record replaces both legacy files while retaining their source +commits and current implementation evidence. diff --git a/docs/sdlc/changes/2026-08-29-appearance-settings-layout/change.md b/docs/sdlc/changes/2026-08-29-appearance-settings-layout/change.md deleted file mode 100644 index 493abeb2..00000000 --- a/docs/sdlc/changes/2026-08-29-appearance-settings-layout/change.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -id: change-2026-08-29-appearance-settings-layout -kind: change -schema: 2 -status: verified -risk: low -owner: codex -approvers: "#decision-and-gates" -approved_at: 2026-08-29 -created: 2026-08-29 -updated: 2026-08-31 -source: "#intent" -inputs: "#spec" -outputs: "#build" -scope: apps/desktop, docs/design/system.md -next_trigger: human product review -verification_mode: owner -verified_by: codex -verified_at: 2026-08-29 ---- - -# Refine the Appearance settings layout - -## Intent - -The user reported from the rendered Appearance page that its layout, spacing, overall visual -language, and especially its shadows do not match the rest of CodeTwo. The page currently places -five major sections with no vertical gap and gives scheme options, theme choices, and setting rows -the same elevated-card treatment. The desired result is a calmer macOS settings hierarchy with -clear section rhythm, aligned actions, flat choice tiles, and elevation reserved for real controls. - -## Spec - -Keep the existing 768px settings content column. Use the repository's 32px page-section token -between major sections and 12px surface-inset token between each heading and its content. Preserve -three scheme and theme columns and two palette columns at standard width; at a 608px content -container, themes become two columns and palettes one. Scheme and theme choice tiles use tonal -surfaces without elevation; their selected state keeps the semantic accent ring. Palette and -setting rows become coherent grouped surfaces with internal separators and no row-by-row shadow. -Input fields retain the shared input elevation. - -### Acceptance criteria - -- [x] AC-1: Major Appearance sections have 32px gaps and section headings have 12px content gaps. -- [x] AC-2: Scheme previews, theme choices, preview chrome, and swatches no longer use surface elevation. -- [x] AC-3: Theme editor, Typography, and Surfaces read as grouped modules rather than loose cards. -- [x] AC-4: Standard and compact grids stay aligned without clipping or awkward action wrapping. -- [x] AC-5: Scheme selection, theme selection, create/import/export, palette inputs, selects, and sliders - retain their existing accessible behavior. -- [x] AC-6: Dark, light, focused tests, design, SDLC, diff, screenshot, and console checks pass. - -## Decision and gates - -Intent and visual acceptance come directly from the user's 2026-08-29 screenshot feedback. No -permission to create a PR, merge, publish, or release is implied. - -## Plan - -Update the existing desktop layout specification, style the current Appearance component rather -than introducing a parallel page, group related setting rows, remove decorative elevation, add a -narrow layout contract, then verify the running renderer at standard and constrained widths in both -appearances. Rollback is the inverse source change. - -## Build - -The existing Appearance page now uses one explicit section rhythm, flat tonal choice tiles, and -three grouped settings modules. The repository layout contract owns the standard and compact grid -counts, including a narrow horizontal scheme treatment that avoids oversized previews. Existing -selection and editing controls were preserved. - -## Verification - -- `bun test tests/appearanceSettings.test.tsx tests/settingsLayoutContract.test.ts` — 23 passed, - 0 failed. The existing Base UI test harness still emits non-failing `act(...)` warnings. -- `bun run build:renderer` — passed design-source checks, TypeScript, the Vite production build, - and the generated-design check. The existing bundle-size advisory remains non-failing. -- In-app Browser at `http://localhost:1420/` — verified the page at 1280px, 840px, and 780px - viewport widths in dark and light appearances. Observed 32px section gaps, 3/3/2 standard grids, - 3/2/1 compact grids, 1/1/1 auxiliary grids, zero horizontal overflow, and no console errors. -- Scheme changes (`Light` then `System`) and theme changes (`Ocean` then `C2`) updated checked and - pressed state and were restored after verification. -- `bun script/verify/sdlc.ts` — passed; task-scoped `git diff --check` — passed. - -Verdict: verified. - -### Acceptance evidence - -- AC-1: PASS — the recorded `http://localhost:1420/` inspection measured 32px section and 12px heading-to-content gaps. -- AC-2: PASS — the recorded renderer inspection computed the applicable choice and preview shadows as removed. Evidence: `Verification record above`. -- AC-3: PASS — the recorded dark/light screenshots show Theme editor, Typography, and Surfaces as grouped modules. Evidence: `Verification record above`. -- AC-4: PASS — the `http://localhost:1420/` viewport matrix verified 3/3/2 standard and 3/2/1 compact grids with zero overflow. -- AC-5: PASS — `bun test tests/appearanceSettings.test.tsx tests/settingsLayoutContract.test.ts` preserved the existing controls and accessibility behavior. -- AC-6: PASS — the focused tests, `bun run build:renderer`, `bun script/verify/sdlc.ts`, console inspection, and `git diff --check` passed. - -Residual risk: existing Base UI `act(...)` warnings and the bundle-size advisory remain; no product -release was reviewed or authorized. - -## Review and release - -No PR, merge, or release requested. Human product review remains the next lifecycle trigger. - -## Feedback - -No additional layout, overflow, or interaction defects were observed in the rendered review. diff --git a/docs/sdlc/changes/2026-08-29-appearance-settings-layout/intent.md b/docs/sdlc/changes/2026-08-29-appearance-settings-layout/intent.md new file mode 100644 index 00000000..d49b6ecd --- /dev/null +++ b/docs/sdlc/changes/2026-08-29-appearance-settings-layout/intent.md @@ -0,0 +1,52 @@ +--- +id: "2026-08-29-appearance-settings-layout" +stage: intent +schema: 3 +status: accepted +owner: codex +created: 2026-08-29 +source: #intent +risk: low +approved_by: "#decision-and-gates" +approved_at: "2026-08-29" +--- + +# Intent: Refine the Appearance settings layout + +## Problem + +The user reported from the rendered Appearance page that its layout, spacing, overall visual +language, and especially its shadows do not match the rest of CodeTwo. The page currently places +five major sections with no vertical gap and gives scheme options, theme choices, and setting rows +the same elevated-card treatment. The desired result is a calmer macOS settings hierarchy with +clear section rhythm, aligned actions, flat choice tiles, and elevation reserved for real controls. + +## Proposed outcome + +The user reported from the rendered Appearance page that its layout, spacing, overall visual + +## Affected users and systems + +Migrated from legacy change.md. + +## Constraints + +Intent and visual acceptance come directly from the user's 2026-08-29 screenshot feedback. No +permission to create a PR, merge, publish, or release is implied. + +## Out of scope + +Not recorded in the legacy single-file Artifact. + +## Success signals + +See Spec acceptance criteria. + +## Open questions + +None recorded in migration. + +## Decision + +Intent and visual acceptance come directly from the user's 2026-08-29 screenshot feedback. No +permission to create a PR, merge, publish, or release is implied. diff --git a/docs/sdlc/changes/2026-08-29-appearance-settings-layout/plan.md b/docs/sdlc/changes/2026-08-29-appearance-settings-layout/plan.md new file mode 100644 index 00000000..a7c1f115 --- /dev/null +++ b/docs/sdlc/changes/2026-08-29-appearance-settings-layout/plan.md @@ -0,0 +1,54 @@ +--- +id: "2026-08-29-appearance-settings-layout" +stage: plan +schema: 3 +status: accepted +owner: codex +created: 2026-08-29 +based_on: spec.md +risk: low +scope: apps/desktop, docs/design/system.md +approved_by: "#decision-and-gates" +approved_at: "2026-08-29" +--- + +# Plan: Refine the Appearance settings layout + +## Files and ownership + +apps/desktop, docs/design/system.md + +## Order of work + +Update the existing desktop layout specification, style the current Appearance component rather +than introducing a parallel page, group related setting rows, remove decorative elevation, add a +narrow layout contract, then verify the running renderer at standard and constrained widths in both +appearances. Rollback is the inverse source change. + +## Test-first proof + +See legacy Verification section. + +## Visual or integration proof + +See legacy Verification section. + +## Risks and mitigations + +See legacy Decision and gates. + +## Rollback + +See legacy Review and release. + +## Deviations + +The existing Appearance page now uses one explicit section rhythm, flat tonal choice tiles, and +three grouped settings modules. The repository layout contract owns the standard and compact grid +counts, including a narrow horizontal scheme treatment that avoids oversized previews. Existing +selection and editing controls were preserved. + +## Decision + +Intent and visual acceptance come directly from the user's 2026-08-29 screenshot feedback. No +permission to create a PR, merge, publish, or release is implied. diff --git a/docs/sdlc/changes/2026-08-29-appearance-settings-layout/spec.md b/docs/sdlc/changes/2026-08-29-appearance-settings-layout/spec.md new file mode 100644 index 00000000..3463ba60 --- /dev/null +++ b/docs/sdlc/changes/2026-08-29-appearance-settings-layout/spec.md @@ -0,0 +1,60 @@ +--- +id: "2026-08-29-appearance-settings-layout" +stage: spec +schema: 3 +status: accepted +owner: codex +created: 2026-08-29 +based_on: intent.md +risk: low +approved_by: "#decision-and-gates" +approved_at: "2026-08-29" +--- + +# Spec: Refine the Appearance settings layout + +## Requirements + +Keep the existing 768px settings content column. Use the repository's 32px page-section token +between major sections and 12px surface-inset token between each heading and its content. Preserve +three scheme and theme columns and two palette columns at standard width; at a 608px content +container, themes become two columns and palettes one. Scheme and theme choice tiles use tonal +surfaces without elevation; their selected state keeps the semantic accent ring. Palette and +setting rows become coherent grouped surfaces with internal separators and no row-by-row shadow. +Input fields retain the shared input elevation. + +## User experience + +Not separately recorded in legacy change.md. + +## Technical design + +See Requirements and legacy Git history. + +## Security and privacy + +See migrated Decision and gates. + +## Alternatives and non-goals + +Not separately recorded in legacy change.md. + +## Areas of concern + +Intent and visual acceptance come directly from the user's 2026-08-29 screenshot feedback. No +permission to create a PR, merge, publish, or release is implied. + +## Acceptance criteria + +- [x] AC-1: Major Appearance sections have 32px gaps and section headings have 12px content gaps. +- [x] AC-2: Scheme previews, theme choices, preview chrome, and swatches no longer use surface elevation. +- [x] AC-3: Theme editor, Typography, and Surfaces read as grouped modules rather than loose cards. +- [x] AC-4: Standard and compact grids stay aligned without clipping or awkward action wrapping. +- [x] AC-5: Scheme selection, theme selection, create/import/export, palette inputs, selects, and sliders + retain their existing accessible behavior. +- [x] AC-6: Dark, light, focused tests, design, SDLC, diff, screenshot, and console checks pass. + +## Decision + +Intent and visual acceptance come directly from the user's 2026-08-29 screenshot feedback. No +permission to create a PR, merge, publish, or release is implied. diff --git a/docs/sdlc/changes/2026-08-29-appearance-settings-layout/verification.md b/docs/sdlc/changes/2026-08-29-appearance-settings-layout/verification.md new file mode 100644 index 00000000..6b39a394 --- /dev/null +++ b/docs/sdlc/changes/2026-08-29-appearance-settings-layout/verification.md @@ -0,0 +1,95 @@ +--- +id: "2026-08-29-appearance-settings-layout" +stage: verification +schema: 3 +status: passed +owner: codex +created: 2026-08-29 +based_on: plan.md +commit: "" +verification_mode: owner +verified_by: "codex" +verified_at: "2026-08-29" +release_target: none +release_identity: "" +--- + +# Verification: Refine the Appearance settings layout + +## Automated checks + +- `bun test tests/appearanceSettings.test.tsx tests/settingsLayoutContract.test.ts` — 23 passed, + 0 failed. The existing Base UI test harness still emits non-failing `act(...)` warnings. +- `bun run build:renderer` — passed design-source checks, TypeScript, the Vite production build, + and the generated-design check. The existing bundle-size advisory remains non-failing. +- In-app Browser at `http://localhost:1420/` — verified the page at 1280px, 840px, and 780px + viewport widths in dark and light appearances. Observed 32px section gaps, 3/3/2 standard grids, + 3/2/1 compact grids, 1/1/1 auxiliary grids, zero horizontal overflow, and no console errors. +- Scheme changes (`Light` then `System`) and theme changes (`Ocean` then `C2`) updated checked and + pressed state and were restored after verification. +- `bun script/verify/sdlc.ts` — passed; task-scoped `git diff --check` — passed. + +Verdict: verified. + +### Acceptance evidence + +- AC-1: PASS — the recorded `http://localhost:1420/` inspection measured 32px section and 12px heading-to-content gaps. +- AC-2: PASS — the recorded renderer inspection computed the applicable choice and preview shadows as removed. Evidence: `Verification record above`. +- AC-3: PASS — the recorded dark/light screenshots show Theme editor, Typography, and Surfaces as grouped modules. Evidence: `Verification record above`. +- AC-4: PASS — the `http://localhost:1420/` viewport matrix verified 3/3/2 standard and 3/2/1 compact grids with zero overflow. +- AC-5: PASS — `bun test tests/appearanceSettings.test.tsx tests/settingsLayoutContract.test.ts` preserved the existing controls and accessibility behavior. +- AC-6: PASS — the focused tests, `bun run build:renderer`, `bun script/verify/sdlc.ts`, console inspection, and `git diff --check` passed. + +Residual risk: existing Base UI `act(...)` warnings and the bundle-size advisory remain; no product +release was reviewed or authorized. + +## Behavioral evidence + +- `bun test tests/appearanceSettings.test.tsx tests/settingsLayoutContract.test.ts` — 23 passed, + 0 failed. The existing Base UI test harness still emits non-failing `act(...)` warnings. +- `bun run build:renderer` — passed design-source checks, TypeScript, the Vite production build, + and the generated-design check. The existing bundle-size advisory remains non-failing. +- In-app Browser at `http://localhost:1420/` — verified the page at 1280px, 840px, and 780px + viewport widths in dark and light appearances. Observed 32px section gaps, 3/3/2 standard grids, + 3/2/1 compact grids, 1/1/1 auxiliary grids, zero horizontal overflow, and no console errors. +- Scheme changes (`Light` then `System`) and theme changes (`Ocean` then `C2`) updated checked and + pressed state and were restored after verification. +- `bun script/verify/sdlc.ts` — passed; task-scoped `git diff --check` — passed. + +Verdict: verified. + +### Acceptance evidence + +- AC-1: PASS — the recorded `http://localhost:1420/` inspection measured 32px section and 12px heading-to-content gaps. +- AC-2: PASS — the recorded renderer inspection computed the applicable choice and preview shadows as removed. Evidence: `Verification record above`. +- AC-3: PASS — the recorded dark/light screenshots show Theme editor, Typography, and Surfaces as grouped modules. Evidence: `Verification record above`. +- AC-4: PASS — the `http://localhost:1420/` viewport matrix verified 3/3/2 standard and 3/2/1 compact grids with zero overflow. +- AC-5: PASS — `bun test tests/appearanceSettings.test.tsx tests/settingsLayoutContract.test.ts` preserved the existing controls and accessibility behavior. +- AC-6: PASS — the focused tests, `bun run build:renderer`, `bun script/verify/sdlc.ts`, console inspection, and `git diff --check` passed. + +Residual risk: existing Base UI `act(...)` warnings and the bundle-size advisory remain; no product +release was reviewed or authorized. + +## Visual evidence + +See bundle evidence/ when present. + +## Security and privacy evidence + +Not separately recorded unless present in legacy Verification. + +## Deviations and residual risk + +Residual risk: existing Base UI `act(...)` warnings and the bundle-size advisory remain; no product + +## Verdict + +Verdict: verified.. + +## Review and release + +No PR, merge, or release requested. Human product review remains the next lifecycle trigger. + +## Feedback + +No additional layout, overflow, or interaction defects were observed in the rendered review. diff --git a/docs/sdlc/changes/2026-08-29-composer-surface-geometry/change.md b/docs/sdlc/changes/2026-08-29-composer-surface-geometry/change.md deleted file mode 100644 index 3de7e160..00000000 --- a/docs/sdlc/changes/2026-08-29-composer-surface-geometry/change.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -id: change-2026-08-29-composer-surface-geometry -kind: change -schema: 2 -status: verified -risk: low -owner: codex -approvers: "#decision-and-gates" -approved_at: 2026-08-29 -created: 2026-08-29 -updated: 2026-08-31 -source: "#intent" -inputs: "#spec" -outputs: "#build" -scope: apps/desktop, docs/design/system.md -next_trigger: human review accepts the rendered interaction and release risk -verification_mode: owner -verified_by: codex -verified_at: 2026-08-29 ---- - -# Keep the composer surface aligned with its editor - -## Intent - -The user reported the new-task composer from a live macOS window with its typed text outside the -painted input surface and followed up that the surface corner radius had grown into an oversized -pill. The desired outcome is a stable Mac-sized card whose background, focus treatment, editor, and controls -share one geometry at every supported height. This change is limited to the main prompt composer; -the small send and stop button effects are not part of the defect. - -## Spec - -The compact composer must use the existing semantic composer radius and paint its background, -shadow, and focus ring on the same DOM card that contains the editor and controls. Expanding or -collapsing the document must not leave a decorative silhouette behind. The expanded document -continues to use the workspace surface without card chrome. - -### Acceptance criteria - -- [x] AC-1: In compact mode, typed text, controls, background, and focus treatment remain inside the same - card at the default and a tall-content state; verify with rendered bounding boxes and screenshots. -- [x] AC-2: The compact card keeps the semantic 24px composer radius instead of scaling the radius with - height; verify from computed style at desktop and narrow widths. -- [x] AC-3: Expanding and collapsing preserves the draft and does not leave a stale surface; verify by - typing, toggling both ways, and reading the draft after each transition. -- [x] AC-4: The focused regression test, renderer build, SDLC check, and relevant console check pass. - -## Decision and gates - -Intent and UX acceptance are supplied directly by the user's 2026-08-29 screenshot and follow-up -message. No permission to publish, merge, or release is implied. - -## Plan - -Remove the separately observed liquid silhouette from the main composer, restore the existing -card-owned semantic background, shadow, and focus treatment, and update the geometry contract. Keep liquid motion -on the isolated circular actions. Validate with the narrowest relevant automated checks and a -real rendered interaction loop. Rollback is the inverse source change. - -## Build - -The compact Composer now paints its semantic card background, shadow, and focus treatment on the -same DOM card that contains BlockNote and its controls. The separate liquid SVG backdrop was -removed from the main input while the isolated circular action effects remain. The geometry -contract rejects reintroducing that second surface. - -## Verification - -- `bun test tests/composerGeometryContract.test.ts`: 3 passed, 0 failed, 24 assertions. -- `bun run build:renderer`: passed TypeScript, Vite production build, source design check, and - built-CSS design check; 0 new design violations and 35 semantic selectors generated. -- Browser-rendered checks at 811x998 and 1280x800 in both light and dark appearance kept the compact - radius at 24px. With `q`, the editor bounds remained within the 203px card. A 12-line draft grew - the card to 282px and kept its 191px scrollport inside the card while exposing 419px of scroll - content. -- Expanding changed `data-composer-mode` to `document`; collapsing restored `compact`; the `q` - draft survived both transitions. -- Safari WebKit accessibility readback confirmed the same prompt accepted `q` and preserved it - across expand and collapse. Safari's web-content screenshot capture returned a blank protected - surface, so exact visual geometry comes from the four Browser screenshots and computed styles. -- `bun script/verify/sdlc.ts` and `git diff --check`: passed. The existing C2 Core process and its - data directory were not restarted or shared during validation. - -Verdict: verified. - -### Acceptance evidence - -- AC-1: PASS — recorded Browser bounding boxes at default and 12-line states kept editor and controls inside the compact card. Evidence: `Verification record above`. -- AC-2: PASS — computed styles at 811px and 1280px retained the semantic `24px` compact radius. -- AC-3: PASS — the recorded expand/collapse interaction preserved the `q` draft in both directions. -- AC-4: PASS — `bun test tests/composerGeometryContract.test.ts`, `bun run build:renderer`, `bun script/verify/sdlc.ts`, console inspection, and `git diff --check` passed. - -Residual risk: Safari protected-surface screenshot capture was unavailable, so visual geometry -relies on the recorded Browser screenshots, accessibility readback, and computed styles. - -## Review and release - -No PR, merge, or release requested. Human product review remains the next lifecycle trigger. - -## Feedback - -The user's follow-up radius annotations were implemented separately through the shared semantic -radius contract in `change-2026-08-29-semantic-radius-floor`. diff --git a/docs/sdlc/changes/2026-08-29-composer-surface-geometry/intent.md b/docs/sdlc/changes/2026-08-29-composer-surface-geometry/intent.md new file mode 100644 index 00000000..a39902c0 --- /dev/null +++ b/docs/sdlc/changes/2026-08-29-composer-surface-geometry/intent.md @@ -0,0 +1,52 @@ +--- +id: "2026-08-29-composer-surface-geometry" +stage: intent +schema: 3 +status: accepted +owner: codex +created: 2026-08-29 +source: #intent +risk: low +approved_by: "#decision-and-gates" +approved_at: "2026-08-29" +--- + +# Intent: Keep the composer surface aligned with its editor + +## Problem + +The user reported the new-task composer from a live macOS window with its typed text outside the +painted input surface and followed up that the surface corner radius had grown into an oversized +pill. The desired outcome is a stable Mac-sized card whose background, focus treatment, editor, and controls +share one geometry at every supported height. This change is limited to the main prompt composer; +the small send and stop button effects are not part of the defect. + +## Proposed outcome + +The user reported the new-task composer from a live macOS window with its typed text outside the + +## Affected users and systems + +Migrated from legacy change.md. + +## Constraints + +Intent and UX acceptance are supplied directly by the user's 2026-08-29 screenshot and follow-up +message. No permission to publish, merge, or release is implied. + +## Out of scope + +Not recorded in the legacy single-file Artifact. + +## Success signals + +See Spec acceptance criteria. + +## Open questions + +None recorded in migration. + +## Decision + +Intent and UX acceptance are supplied directly by the user's 2026-08-29 screenshot and follow-up +message. No permission to publish, merge, or release is implied. diff --git a/docs/sdlc/changes/2026-08-29-composer-surface-geometry/plan.md b/docs/sdlc/changes/2026-08-29-composer-surface-geometry/plan.md new file mode 100644 index 00000000..f2e276db --- /dev/null +++ b/docs/sdlc/changes/2026-08-29-composer-surface-geometry/plan.md @@ -0,0 +1,54 @@ +--- +id: "2026-08-29-composer-surface-geometry" +stage: plan +schema: 3 +status: accepted +owner: codex +created: 2026-08-29 +based_on: spec.md +risk: low +scope: apps/desktop, docs/design/system.md +approved_by: "#decision-and-gates" +approved_at: "2026-08-29" +--- + +# Plan: Keep the composer surface aligned with its editor + +## Files and ownership + +apps/desktop, docs/design/system.md + +## Order of work + +Remove the separately observed liquid silhouette from the main composer, restore the existing +card-owned semantic background, shadow, and focus treatment, and update the geometry contract. Keep liquid motion +on the isolated circular actions. Validate with the narrowest relevant automated checks and a +real rendered interaction loop. Rollback is the inverse source change. + +## Test-first proof + +See legacy Verification section. + +## Visual or integration proof + +See legacy Verification section. + +## Risks and mitigations + +See legacy Decision and gates. + +## Rollback + +See legacy Review and release. + +## Deviations + +The compact Composer now paints its semantic card background, shadow, and focus treatment on the +same DOM card that contains BlockNote and its controls. The separate liquid SVG backdrop was +removed from the main input while the isolated circular action effects remain. The geometry +contract rejects reintroducing that second surface. + +## Decision + +Intent and UX acceptance are supplied directly by the user's 2026-08-29 screenshot and follow-up +message. No permission to publish, merge, or release is implied. diff --git a/docs/sdlc/changes/2026-08-29-composer-surface-geometry/spec.md b/docs/sdlc/changes/2026-08-29-composer-surface-geometry/spec.md new file mode 100644 index 00000000..a4935fbf --- /dev/null +++ b/docs/sdlc/changes/2026-08-29-composer-surface-geometry/spec.md @@ -0,0 +1,57 @@ +--- +id: "2026-08-29-composer-surface-geometry" +stage: spec +schema: 3 +status: accepted +owner: codex +created: 2026-08-29 +based_on: intent.md +risk: low +approved_by: "#decision-and-gates" +approved_at: "2026-08-29" +--- + +# Spec: Keep the composer surface aligned with its editor + +## Requirements + +The compact composer must use the existing semantic composer radius and paint its background, +shadow, and focus ring on the same DOM card that contains the editor and controls. Expanding or +collapsing the document must not leave a decorative silhouette behind. The expanded document +continues to use the workspace surface without card chrome. + +## User experience + +Not separately recorded in legacy change.md. + +## Technical design + +See Requirements and legacy Git history. + +## Security and privacy + +See migrated Decision and gates. + +## Alternatives and non-goals + +Not separately recorded in legacy change.md. + +## Areas of concern + +Intent and UX acceptance are supplied directly by the user's 2026-08-29 screenshot and follow-up +message. No permission to publish, merge, or release is implied. + +## Acceptance criteria + +- [x] AC-1: In compact mode, typed text, controls, background, and focus treatment remain inside the same + card at the default and a tall-content state; verify with rendered bounding boxes and screenshots. +- [x] AC-2: The compact card keeps the semantic 24px composer radius instead of scaling the radius with + height; verify from computed style at desktop and narrow widths. +- [x] AC-3: Expanding and collapsing preserves the draft and does not leave a stale surface; verify by + typing, toggling both ways, and reading the draft after each transition. +- [x] AC-4: The focused regression test, renderer build, SDLC check, and relevant console check pass. + +## Decision + +Intent and UX acceptance are supplied directly by the user's 2026-08-29 screenshot and follow-up +message. No permission to publish, merge, or release is implied. diff --git a/docs/sdlc/changes/2026-08-29-composer-surface-geometry/verification.md b/docs/sdlc/changes/2026-08-29-composer-surface-geometry/verification.md new file mode 100644 index 00000000..d7a5db0a --- /dev/null +++ b/docs/sdlc/changes/2026-08-29-composer-surface-geometry/verification.md @@ -0,0 +1,100 @@ +--- +id: "2026-08-29-composer-surface-geometry" +stage: verification +schema: 3 +status: passed +owner: codex +created: 2026-08-29 +based_on: plan.md +commit: "" +verification_mode: owner +verified_by: "codex" +verified_at: "2026-08-29" +release_target: none +release_identity: "" +--- + +# Verification: Keep the composer surface aligned with its editor + +## Automated checks + +- `bun test tests/composerGeometryContract.test.ts`: 3 passed, 0 failed, 24 assertions. +- `bun run build:renderer`: passed TypeScript, Vite production build, source design check, and + built-CSS design check; 0 new design violations and 35 semantic selectors generated. +- Browser-rendered checks at 811x998 and 1280x800 in both light and dark appearance kept the compact + radius at 24px. With `q`, the editor bounds remained within the 203px card. A 12-line draft grew + the card to 282px and kept its 191px scrollport inside the card while exposing 419px of scroll + content. +- Expanding changed `data-composer-mode` to `document`; collapsing restored `compact`; the `q` + draft survived both transitions. +- Safari WebKit accessibility readback confirmed the same prompt accepted `q` and preserved it + across expand and collapse. Safari's web-content screenshot capture returned a blank protected + surface, so exact visual geometry comes from the four Browser screenshots and computed styles. +- `bun script/verify/sdlc.ts` and `git diff --check`: passed. The existing C2 Core process and its + data directory were not restarted or shared during validation. + +Verdict: verified. + +### Acceptance evidence + +- AC-1: PASS — recorded Browser bounding boxes at default and 12-line states kept editor and controls inside the compact card. Evidence: `Verification record above`. +- AC-2: PASS — computed styles at 811px and 1280px retained the semantic `24px` compact radius. +- AC-3: PASS — the recorded expand/collapse interaction preserved the `q` draft in both directions. +- AC-4: PASS — `bun test tests/composerGeometryContract.test.ts`, `bun run build:renderer`, `bun script/verify/sdlc.ts`, console inspection, and `git diff --check` passed. + +Residual risk: Safari protected-surface screenshot capture was unavailable, so visual geometry +relies on the recorded Browser screenshots, accessibility readback, and computed styles. + +## Behavioral evidence + +- `bun test tests/composerGeometryContract.test.ts`: 3 passed, 0 failed, 24 assertions. +- `bun run build:renderer`: passed TypeScript, Vite production build, source design check, and + built-CSS design check; 0 new design violations and 35 semantic selectors generated. +- Browser-rendered checks at 811x998 and 1280x800 in both light and dark appearance kept the compact + radius at 24px. With `q`, the editor bounds remained within the 203px card. A 12-line draft grew + the card to 282px and kept its 191px scrollport inside the card while exposing 419px of scroll + content. +- Expanding changed `data-composer-mode` to `document`; collapsing restored `compact`; the `q` + draft survived both transitions. +- Safari WebKit accessibility readback confirmed the same prompt accepted `q` and preserved it + across expand and collapse. Safari's web-content screenshot capture returned a blank protected + surface, so exact visual geometry comes from the four Browser screenshots and computed styles. +- `bun script/verify/sdlc.ts` and `git diff --check`: passed. The existing C2 Core process and its + data directory were not restarted or shared during validation. + +Verdict: verified. + +### Acceptance evidence + +- AC-1: PASS — recorded Browser bounding boxes at default and 12-line states kept editor and controls inside the compact card. Evidence: `Verification record above`. +- AC-2: PASS — computed styles at 811px and 1280px retained the semantic `24px` compact radius. +- AC-3: PASS — the recorded expand/collapse interaction preserved the `q` draft in both directions. +- AC-4: PASS — `bun test tests/composerGeometryContract.test.ts`, `bun run build:renderer`, `bun script/verify/sdlc.ts`, console inspection, and `git diff --check` passed. + +Residual risk: Safari protected-surface screenshot capture was unavailable, so visual geometry +relies on the recorded Browser screenshots, accessibility readback, and computed styles. + +## Visual evidence + +See bundle evidence/ when present. + +## Security and privacy evidence + +Not separately recorded unless present in legacy Verification. + +## Deviations and residual risk + +Residual risk: Safari protected-surface screenshot capture was unavailable, so visual geometry + +## Verdict + +Verdict: verified.. + +## Review and release + +No PR, merge, or release requested. Human product review remains the next lifecycle trigger. + +## Feedback + +The user's follow-up radius annotations were implemented separately through the shared semantic +radius contract in `change-2026-08-29-semantic-radius-floor`. diff --git a/docs/sdlc/changes/2026-08-29-empty-session-titlebar-divider/change.md b/docs/sdlc/changes/2026-08-29-empty-session-titlebar-divider/change.md deleted file mode 100644 index 12aee50d..00000000 --- a/docs/sdlc/changes/2026-08-29-empty-session-titlebar-divider/change.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -id: change-2026-08-29-empty-session-titlebar-divider -kind: change -schema: 2 -status: verified -risk: low -owner: codex -approvers: "#decision-and-gates" -approved_at: 2026-08-29 -created: 2026-08-29 -updated: 2026-08-31 -source: "#intent" -inputs: "#spec" -outputs: "#build" -scope: apps/desktop, docs/design/system.md -next_trigger: human review accepts the rendered interaction and release risk -verification_mode: owner -verified_by: codex -verified_at: 2026-08-29 ---- - -# Hide the empty-session titlebar divider - -## Intent - -The user reported that the separator below the session titlebar should not appear on the empty home -screen. It should return only when the pane has conversation content that reads or scrolls beneath -the titlebar. This change is limited to the session workspace titlebar; rail and dock titlebars keep -their existing boundaries. - -## Spec - -Use the same state that mounts the transcript surface to control the session titlebar divider. An -empty pane with no turns, active run, or transcript load has no divider. A pane with persisted turns, -an active run, or a loading transcript restores the existing semantic hairline. The rule is -state-based and does not depend on viewport width or appearance. - -### Acceptance criteria - -- [x] AC-1: An empty new-task pane has no visible or computed titlebar divider. -- [x] AC-2: Persisted, running, and loading conversation states use the existing semantic hairline. -- [x] AC-3: Rail and dock titlebar separators are unchanged. -- [x] AC-4: Dark, light, constrained-width, focused test, design, SDLC, diff, and console checks pass. - -## Decision and gates - -Intent and design acceptance come directly from the user's 2026-08-29 rendered-page feedback. No -permission to create a PR, merge, publish, or release is implied. - -## Plan - -Name the existing transcript-presence condition once per pane, expose it on the session header, -override only that header's box shadow, add a narrow contract assertion and design-law sentence, -then verify both divider states in the running renderer. Rollback is the inverse source change. - -## Build - -Each pane now names the existing transcript-presence condition once and exposes it through -`data-has-conversation` on the session header. The session header removes the global titlebar -shadow by default and restores the exact existing semantic hairline only for that content state. -The transcript and full-page transcript toggle consume the same condition. Other window titlebars -still use the global titlebar rule. - -## Verification - -- The two focused window-chrome contract tests passed with 12 unrelated cases filtered out. They - cover the shared titlebar baseline, unchanged global separator, session state binding, empty - override, and conversation-state hairline. -- `bun run check:design` from `apps/desktop`: passed with 0 new violations, 659 tracked legacy - occurrences, and all contrast checks passing. -- In the live renderer at `http://localhost:1420/`, the empty pane had zero transcript turns, no - `data-has-conversation` attribute, and computed `box-shadow: none`; the saved screenshot showed - no line between the titlebar and workspace. The same result held in light appearance and at a - 620px constrained session-header width. -- The loaded stylesheet contained the conversation-state selector with the original semantic - hairline. In the same renderer, rail and dock titlebars retained their computed half-pixel inset - shadows while the session header had none. -- The side panel and appearance settings were restored, and browser warning/error output was empty. -- `bun script/verify/sdlc.ts` and the task-scoped `git diff --check`: passed. - -Verdict: verified. - -### Acceptance evidence - -- AC-1: PASS — the recorded `http://localhost:1420/` empty-state inspection computed `box-shadow: none` and captured no divider. -- AC-2: PASS — focused window-chrome contract tests retained the conversation-state semantic hairline. Evidence: `Verification record above`. -- AC-3: PASS — the live inspection confirmed rail and dock titlebars retained their half-pixel inset shadows. Evidence: `Verification record above`. -- AC-4: PASS — focused tests, `bun run check:design`, `bun script/verify/sdlc.ts`, dark/light/narrow inspection, console review, and `git diff --check` passed. - -Residual risk: live evidence covered the empty state; the non-empty conversation state is retained -by focused contract coverage and the unchanged semantic selector. - -## Review and release - -No PR, merge, or release requested. Human product review remains the next lifecycle trigger. - -## Feedback - -No additional defect observed during the dark, light, constrained, and restored empty states. diff --git a/docs/sdlc/changes/2026-08-29-empty-session-titlebar-divider/intent.md b/docs/sdlc/changes/2026-08-29-empty-session-titlebar-divider/intent.md new file mode 100644 index 00000000..d3c327f2 --- /dev/null +++ b/docs/sdlc/changes/2026-08-29-empty-session-titlebar-divider/intent.md @@ -0,0 +1,51 @@ +--- +id: "2026-08-29-empty-session-titlebar-divider" +stage: intent +schema: 3 +status: accepted +owner: codex +created: 2026-08-29 +source: #intent +risk: low +approved_by: "#decision-and-gates" +approved_at: "2026-08-29" +--- + +# Intent: Hide the empty-session titlebar divider + +## Problem + +The user reported that the separator below the session titlebar should not appear on the empty home +screen. It should return only when the pane has conversation content that reads or scrolls beneath +the titlebar. This change is limited to the session workspace titlebar; rail and dock titlebars keep +their existing boundaries. + +## Proposed outcome + +The user reported that the separator below the session titlebar should not appear on the empty home + +## Affected users and systems + +Migrated from legacy change.md. + +## Constraints + +Intent and design acceptance come directly from the user's 2026-08-29 rendered-page feedback. No +permission to create a PR, merge, publish, or release is implied. + +## Out of scope + +Not recorded in the legacy single-file Artifact. + +## Success signals + +See Spec acceptance criteria. + +## Open questions + +None recorded in migration. + +## Decision + +Intent and design acceptance come directly from the user's 2026-08-29 rendered-page feedback. No +permission to create a PR, merge, publish, or release is implied. diff --git a/docs/sdlc/changes/2026-08-29-empty-session-titlebar-divider/plan.md b/docs/sdlc/changes/2026-08-29-empty-session-titlebar-divider/plan.md new file mode 100644 index 00000000..bc1e4d38 --- /dev/null +++ b/docs/sdlc/changes/2026-08-29-empty-session-titlebar-divider/plan.md @@ -0,0 +1,54 @@ +--- +id: "2026-08-29-empty-session-titlebar-divider" +stage: plan +schema: 3 +status: accepted +owner: codex +created: 2026-08-29 +based_on: spec.md +risk: low +scope: apps/desktop, docs/design/system.md +approved_by: "#decision-and-gates" +approved_at: "2026-08-29" +--- + +# Plan: Hide the empty-session titlebar divider + +## Files and ownership + +apps/desktop, docs/design/system.md + +## Order of work + +Name the existing transcript-presence condition once per pane, expose it on the session header, +override only that header's box shadow, add a narrow contract assertion and design-law sentence, +then verify both divider states in the running renderer. Rollback is the inverse source change. + +## Test-first proof + +See legacy Verification section. + +## Visual or integration proof + +See legacy Verification section. + +## Risks and mitigations + +See legacy Decision and gates. + +## Rollback + +See legacy Review and release. + +## Deviations + +Each pane now names the existing transcript-presence condition once and exposes it through +`data-has-conversation` on the session header. The session header removes the global titlebar +shadow by default and restores the exact existing semantic hairline only for that content state. +The transcript and full-page transcript toggle consume the same condition. Other window titlebars +still use the global titlebar rule. + +## Decision + +Intent and design acceptance come directly from the user's 2026-08-29 rendered-page feedback. No +permission to create a PR, merge, publish, or release is implied. diff --git a/docs/sdlc/changes/2026-08-29-empty-session-titlebar-divider/spec.md b/docs/sdlc/changes/2026-08-29-empty-session-titlebar-divider/spec.md new file mode 100644 index 00000000..35b3b3d5 --- /dev/null +++ b/docs/sdlc/changes/2026-08-29-empty-session-titlebar-divider/spec.md @@ -0,0 +1,54 @@ +--- +id: "2026-08-29-empty-session-titlebar-divider" +stage: spec +schema: 3 +status: accepted +owner: codex +created: 2026-08-29 +based_on: intent.md +risk: low +approved_by: "#decision-and-gates" +approved_at: "2026-08-29" +--- + +# Spec: Hide the empty-session titlebar divider + +## Requirements + +Use the same state that mounts the transcript surface to control the session titlebar divider. An +empty pane with no turns, active run, or transcript load has no divider. A pane with persisted turns, +an active run, or a loading transcript restores the existing semantic hairline. The rule is +state-based and does not depend on viewport width or appearance. + +## User experience + +Not separately recorded in legacy change.md. + +## Technical design + +See Requirements and legacy Git history. + +## Security and privacy + +See migrated Decision and gates. + +## Alternatives and non-goals + +Not separately recorded in legacy change.md. + +## Areas of concern + +Intent and design acceptance come directly from the user's 2026-08-29 rendered-page feedback. No +permission to create a PR, merge, publish, or release is implied. + +## Acceptance criteria + +- [x] AC-1: An empty new-task pane has no visible or computed titlebar divider. +- [x] AC-2: Persisted, running, and loading conversation states use the existing semantic hairline. +- [x] AC-3: Rail and dock titlebar separators are unchanged. +- [x] AC-4: Dark, light, constrained-width, focused test, design, SDLC, diff, and console checks pass. + +## Decision + +Intent and design acceptance come directly from the user's 2026-08-29 rendered-page feedback. No +permission to create a PR, merge, publish, or release is implied. diff --git a/docs/sdlc/changes/2026-08-29-empty-session-titlebar-divider/verification.md b/docs/sdlc/changes/2026-08-29-empty-session-titlebar-divider/verification.md new file mode 100644 index 00000000..c8e454cc --- /dev/null +++ b/docs/sdlc/changes/2026-08-29-empty-session-titlebar-divider/verification.md @@ -0,0 +1,99 @@ +--- +id: "2026-08-29-empty-session-titlebar-divider" +stage: verification +schema: 3 +status: passed +owner: codex +created: 2026-08-29 +based_on: plan.md +commit: "" +verification_mode: owner +verified_by: "codex" +verified_at: "2026-08-29" +release_target: none +release_identity: "" +--- + +# Verification: Hide the empty-session titlebar divider + +## Automated checks + +- The two focused window-chrome contract tests passed with 12 unrelated cases filtered out. They + cover the shared titlebar baseline, unchanged global separator, session state binding, empty + override, and conversation-state hairline. +- `bun run check:design` from `apps/desktop`: passed with 0 new violations, 659 tracked legacy + occurrences, and all contrast checks passing. +- In the live renderer at `http://localhost:1420/`, the empty pane had zero transcript turns, no + `data-has-conversation` attribute, and computed `box-shadow: none`; the saved screenshot showed + no line between the titlebar and workspace. The same result held in light appearance and at a + 620px constrained session-header width. +- The loaded stylesheet contained the conversation-state selector with the original semantic + hairline. In the same renderer, rail and dock titlebars retained their computed half-pixel inset + shadows while the session header had none. +- The side panel and appearance settings were restored, and browser warning/error output was empty. +- `bun script/verify/sdlc.ts` and the task-scoped `git diff --check`: passed. + +Verdict: verified. + +### Acceptance evidence + +- AC-1: PASS — the recorded `http://localhost:1420/` empty-state inspection computed `box-shadow: none` and captured no divider. +- AC-2: PASS — focused window-chrome contract tests retained the conversation-state semantic hairline. Evidence: `Verification record above`. +- AC-3: PASS — the live inspection confirmed rail and dock titlebars retained their half-pixel inset shadows. Evidence: `Verification record above`. +- AC-4: PASS — focused tests, `bun run check:design`, `bun script/verify/sdlc.ts`, dark/light/narrow inspection, console review, and `git diff --check` passed. + +Residual risk: live evidence covered the empty state; the non-empty conversation state is retained +by focused contract coverage and the unchanged semantic selector. + +## Behavioral evidence + +- The two focused window-chrome contract tests passed with 12 unrelated cases filtered out. They + cover the shared titlebar baseline, unchanged global separator, session state binding, empty + override, and conversation-state hairline. +- `bun run check:design` from `apps/desktop`: passed with 0 new violations, 659 tracked legacy + occurrences, and all contrast checks passing. +- In the live renderer at `http://localhost:1420/`, the empty pane had zero transcript turns, no + `data-has-conversation` attribute, and computed `box-shadow: none`; the saved screenshot showed + no line between the titlebar and workspace. The same result held in light appearance and at a + 620px constrained session-header width. +- The loaded stylesheet contained the conversation-state selector with the original semantic + hairline. In the same renderer, rail and dock titlebars retained their computed half-pixel inset + shadows while the session header had none. +- The side panel and appearance settings were restored, and browser warning/error output was empty. +- `bun script/verify/sdlc.ts` and the task-scoped `git diff --check`: passed. + +Verdict: verified. + +### Acceptance evidence + +- AC-1: PASS — the recorded `http://localhost:1420/` empty-state inspection computed `box-shadow: none` and captured no divider. +- AC-2: PASS — focused window-chrome contract tests retained the conversation-state semantic hairline. Evidence: `Verification record above`. +- AC-3: PASS — the live inspection confirmed rail and dock titlebars retained their half-pixel inset shadows. Evidence: `Verification record above`. +- AC-4: PASS — focused tests, `bun run check:design`, `bun script/verify/sdlc.ts`, dark/light/narrow inspection, console review, and `git diff --check` passed. + +Residual risk: live evidence covered the empty state; the non-empty conversation state is retained +by focused contract coverage and the unchanged semantic selector. + +## Visual evidence + +See bundle evidence/ when present. + +## Security and privacy evidence + +Not separately recorded unless present in legacy Verification. + +## Deviations and residual risk + +Residual risk: live evidence covered the empty state; the non-empty conversation state is retained + +## Verdict + +Verdict: verified.. + +## Review and release + +No PR, merge, or release requested. Human product review remains the next lifecycle trigger. + +## Feedback + +No additional defect observed during the dark, light, constrained, and restored empty states. diff --git a/docs/sdlc/changes/2026-08-29-pets-settings-surface-and-scroll/change.md b/docs/sdlc/changes/2026-08-29-pets-settings-surface-and-scroll/change.md deleted file mode 100644 index bb57b9c2..00000000 --- a/docs/sdlc/changes/2026-08-29-pets-settings-surface-and-scroll/change.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -id: change-2026-08-29-pets-settings-surface-and-scroll -kind: change -schema: 2 -status: verified -risk: low -owner: codex -approvers: "#decision-and-gates" -approved_at: 2026-08-29 -created: 2026-08-29 -updated: 2026-08-31 -source: "#intent" -inputs: "#spec" -outputs: "#build" -scope: apps/desktop, docs/design/system.md -next_trigger: human product review -verification_mode: owner -verified_by: codex -verified_at: 2026-08-29 ---- - -# Align Pets settings surfaces and scrolling - -## Intent - -The user's rendered Pets settings review identified two inconsistent elevated behavior rows and a -missing bottom inset when the settings viewport reaches its scroll limit. Pet catalog rows should -also reuse the same setting-row anatomy as the rest of Settings instead of maintaining a parallel -custom row layout. - -## Spec - -Render every pet catalog entry through the shared `SettingRow` and shared `Button`. Keep the catalog -and Session behavior as flat grouped surfaces with internal semantic hairlines, without outer rings -or per-row surface elevation. Make the settings page itself own an 80px semantic page-end inset so -the last section clears the bottom of the scroll viewport on every tab. - -### Acceptance criteria - -- [x] AC-1: Pet catalog entries use the shared setting-row anatomy and preserve list semantics. -- [x] AC-2: Catalog and Session behavior surfaces have no decorative surface elevation. -- [x] AC-3: Existing pet preview, selection, mood, visibility, activity, and size behavior remains intact. -- [x] AC-4: At the scroll limit, the last Pets section has an 80px bottom inset. -- [x] AC-5: Desktop and compact layouts remain readable in light and dark appearances. -- [x] AC-6: Focused tests, design, type, SDLC, diff, screenshot, and console checks pass. - -## Decision and gates - -Intent and acceptance come directly from the user's 2026-08-29 browser annotation. No permission to -create a PR, merge, publish, or release is implied. - -## Plan - -Reuse the existing business primitives, remove only decorative elevation, move page-end spacing to -the settings page's CSS contract, add focused assertions, and verify the running renderer at the -bottom scroll boundary. Rollback is the inverse source change. - -## Build - -Pet catalog entries now compose the shared `SettingRow`, `Button`, and `Spinner` primitives inside a -semantic list. The catalog and Session behavior each use one flat grouped surface with internal -hairlines. The settings page owns its semantic page-end inset at both regular and compact widths, -so responsive overrides cannot reset the scroll clearance to zero. - -## Verification - -- `bun test tests/petSettings.test.tsx tests/settingsLayoutContract.test.ts` — 23 passed, 0 failed. - The existing Base UI test harness still emits non-failing `act(...)` warnings. -- `bunx tsc --noEmit` — passed. -- `bun run check:design` — passed with 0 new violations; legacy debt remains 657. -- In-app Browser at `http://localhost:1420/` — verified meaningful Pets content with no framework - overlay at 1280×720, 800×600, and 600×600 in dark and light appearances. Catalog and behavior - shadows computed to `none`, horizontal overflow was zero, and the final section retained 80px - clearance at the scroll limit. -- Selected Bill Gates and then restored Naiwa; the selected row updated correctly both times. -- Browser console reported no warnings or errors after the final reload. -- `bun script/verify/sdlc.ts` — passed; task-scoped `git diff --check` — passed. - -Verdict: verified. - -### Acceptance evidence - -- AC-1: PASS — `bun test tests/petSettings.test.tsx tests/settingsLayoutContract.test.ts` covered the shared setting-row and list behavior. -- AC-2: PASS — recorded renderer inspection computed catalog and Session behavior shadows as `none`. -- AC-3: PASS — focused pet tests and the recorded selection restore preserved preview, selection, mood, visibility, activity, and size behavior. Evidence: `Verification record above`. -- AC-4: PASS — the `http://localhost:1420/` scroll-limit inspection measured an `80px` final-section inset. -- AC-5: PASS — the recorded 1280x720, 800x600, and 600x600 light/dark matrix had zero horizontal overflow. Evidence: `Verification record above`. -- AC-6: PASS — focused tests, `bunx tsc --noEmit`, `bun run check:design`, `bun script/verify/sdlc.ts`, screenshots, console inspection, and `git diff --check` passed. - -Residual risk: the existing non-failing React `act(...)` warnings remain; no product release was -reviewed or authorized. - -## Review and release - -No PR, merge, or release requested. Human product review remains the next lifecycle trigger. - -## Feedback - -No additional layout, overflow, interaction, or scroll-boundary defects were observed. diff --git a/docs/sdlc/changes/2026-08-29-pets-settings-surface-and-scroll/intent.md b/docs/sdlc/changes/2026-08-29-pets-settings-surface-and-scroll/intent.md new file mode 100644 index 00000000..ab5c486d --- /dev/null +++ b/docs/sdlc/changes/2026-08-29-pets-settings-surface-and-scroll/intent.md @@ -0,0 +1,51 @@ +--- +id: "2026-08-29-pets-settings-surface-and-scroll" +stage: intent +schema: 3 +status: accepted +owner: codex +created: 2026-08-29 +source: #intent +risk: low +approved_by: "#decision-and-gates" +approved_at: "2026-08-29" +--- + +# Intent: Align Pets settings surfaces and scrolling + +## Problem + +The user's rendered Pets settings review identified two inconsistent elevated behavior rows and a +missing bottom inset when the settings viewport reaches its scroll limit. Pet catalog rows should +also reuse the same setting-row anatomy as the rest of Settings instead of maintaining a parallel +custom row layout. + +## Proposed outcome + +The user's rendered Pets settings review identified two inconsistent elevated behavior rows and a + +## Affected users and systems + +Migrated from legacy change.md. + +## Constraints + +Intent and acceptance come directly from the user's 2026-08-29 browser annotation. No permission to +create a PR, merge, publish, or release is implied. + +## Out of scope + +Not recorded in the legacy single-file Artifact. + +## Success signals + +See Spec acceptance criteria. + +## Open questions + +None recorded in migration. + +## Decision + +Intent and acceptance come directly from the user's 2026-08-29 browser annotation. No permission to +create a PR, merge, publish, or release is implied. diff --git a/docs/sdlc/changes/2026-08-29-pets-settings-surface-and-scroll/plan.md b/docs/sdlc/changes/2026-08-29-pets-settings-surface-and-scroll/plan.md new file mode 100644 index 00000000..5db683f5 --- /dev/null +++ b/docs/sdlc/changes/2026-08-29-pets-settings-surface-and-scroll/plan.md @@ -0,0 +1,53 @@ +--- +id: "2026-08-29-pets-settings-surface-and-scroll" +stage: plan +schema: 3 +status: accepted +owner: codex +created: 2026-08-29 +based_on: spec.md +risk: low +scope: apps/desktop, docs/design/system.md +approved_by: "#decision-and-gates" +approved_at: "2026-08-29" +--- + +# Plan: Align Pets settings surfaces and scrolling + +## Files and ownership + +apps/desktop, docs/design/system.md + +## Order of work + +Reuse the existing business primitives, remove only decorative elevation, move page-end spacing to +the settings page's CSS contract, add focused assertions, and verify the running renderer at the +bottom scroll boundary. Rollback is the inverse source change. + +## Test-first proof + +See legacy Verification section. + +## Visual or integration proof + +See legacy Verification section. + +## Risks and mitigations + +See legacy Decision and gates. + +## Rollback + +See legacy Review and release. + +## Deviations + +Pet catalog entries now compose the shared `SettingRow`, `Button`, and `Spinner` primitives inside a +semantic list. The catalog and Session behavior each use one flat grouped surface with internal +hairlines. The settings page owns its semantic page-end inset at both regular and compact widths, +so responsive overrides cannot reset the scroll clearance to zero. + +## Decision + +Intent and acceptance come directly from the user's 2026-08-29 browser annotation. No permission to +create a PR, merge, publish, or release is implied. diff --git a/docs/sdlc/changes/2026-08-29-pets-settings-surface-and-scroll/spec.md b/docs/sdlc/changes/2026-08-29-pets-settings-surface-and-scroll/spec.md new file mode 100644 index 00000000..ad889557 --- /dev/null +++ b/docs/sdlc/changes/2026-08-29-pets-settings-surface-and-scroll/spec.md @@ -0,0 +1,56 @@ +--- +id: "2026-08-29-pets-settings-surface-and-scroll" +stage: spec +schema: 3 +status: accepted +owner: codex +created: 2026-08-29 +based_on: intent.md +risk: low +approved_by: "#decision-and-gates" +approved_at: "2026-08-29" +--- + +# Spec: Align Pets settings surfaces and scrolling + +## Requirements + +Render every pet catalog entry through the shared `SettingRow` and shared `Button`. Keep the catalog +and Session behavior as flat grouped surfaces with internal semantic hairlines, without outer rings +or per-row surface elevation. Make the settings page itself own an 80px semantic page-end inset so +the last section clears the bottom of the scroll viewport on every tab. + +## User experience + +Not separately recorded in legacy change.md. + +## Technical design + +See Requirements and legacy Git history. + +## Security and privacy + +See migrated Decision and gates. + +## Alternatives and non-goals + +Not separately recorded in legacy change.md. + +## Areas of concern + +Intent and acceptance come directly from the user's 2026-08-29 browser annotation. No permission to +create a PR, merge, publish, or release is implied. + +## Acceptance criteria + +- [x] AC-1: Pet catalog entries use the shared setting-row anatomy and preserve list semantics. +- [x] AC-2: Catalog and Session behavior surfaces have no decorative surface elevation. +- [x] AC-3: Existing pet preview, selection, mood, visibility, activity, and size behavior remains intact. +- [x] AC-4: At the scroll limit, the last Pets section has an 80px bottom inset. +- [x] AC-5: Desktop and compact layouts remain readable in light and dark appearances. +- [x] AC-6: Focused tests, design, type, SDLC, diff, screenshot, and console checks pass. + +## Decision + +Intent and acceptance come directly from the user's 2026-08-29 browser annotation. No permission to +create a PR, merge, publish, or release is implied. diff --git a/docs/sdlc/changes/2026-08-29-pets-settings-surface-and-scroll/verification.md b/docs/sdlc/changes/2026-08-29-pets-settings-surface-and-scroll/verification.md new file mode 100644 index 00000000..8a2521aa --- /dev/null +++ b/docs/sdlc/changes/2026-08-29-pets-settings-surface-and-scroll/verification.md @@ -0,0 +1,97 @@ +--- +id: "2026-08-29-pets-settings-surface-and-scroll" +stage: verification +schema: 3 +status: passed +owner: codex +created: 2026-08-29 +based_on: plan.md +commit: "" +verification_mode: owner +verified_by: "codex" +verified_at: "2026-08-29" +release_target: none +release_identity: "" +--- + +# Verification: Align Pets settings surfaces and scrolling + +## Automated checks + +- `bun test tests/petSettings.test.tsx tests/settingsLayoutContract.test.ts` — 23 passed, 0 failed. + The existing Base UI test harness still emits non-failing `act(...)` warnings. +- `bunx tsc --noEmit` — passed. +- `bun run check:design` — passed with 0 new violations; legacy debt remains 657. +- In-app Browser at `http://localhost:1420/` — verified meaningful Pets content with no framework + overlay at 1280×720, 800×600, and 600×600 in dark and light appearances. Catalog and behavior + shadows computed to `none`, horizontal overflow was zero, and the final section retained 80px + clearance at the scroll limit. +- Selected Bill Gates and then restored Naiwa; the selected row updated correctly both times. +- Browser console reported no warnings or errors after the final reload. +- `bun script/verify/sdlc.ts` — passed; task-scoped `git diff --check` — passed. + +Verdict: verified. + +### Acceptance evidence + +- AC-1: PASS — `bun test tests/petSettings.test.tsx tests/settingsLayoutContract.test.ts` covered the shared setting-row and list behavior. +- AC-2: PASS — recorded renderer inspection computed catalog and Session behavior shadows as `none`. +- AC-3: PASS — focused pet tests and the recorded selection restore preserved preview, selection, mood, visibility, activity, and size behavior. Evidence: `Verification record above`. +- AC-4: PASS — the `http://localhost:1420/` scroll-limit inspection measured an `80px` final-section inset. +- AC-5: PASS — the recorded 1280x720, 800x600, and 600x600 light/dark matrix had zero horizontal overflow. Evidence: `Verification record above`. +- AC-6: PASS — focused tests, `bunx tsc --noEmit`, `bun run check:design`, `bun script/verify/sdlc.ts`, screenshots, console inspection, and `git diff --check` passed. + +Residual risk: the existing non-failing React `act(...)` warnings remain; no product release was +reviewed or authorized. + +## Behavioral evidence + +- `bun test tests/petSettings.test.tsx tests/settingsLayoutContract.test.ts` — 23 passed, 0 failed. + The existing Base UI test harness still emits non-failing `act(...)` warnings. +- `bunx tsc --noEmit` — passed. +- `bun run check:design` — passed with 0 new violations; legacy debt remains 657. +- In-app Browser at `http://localhost:1420/` — verified meaningful Pets content with no framework + overlay at 1280×720, 800×600, and 600×600 in dark and light appearances. Catalog and behavior + shadows computed to `none`, horizontal overflow was zero, and the final section retained 80px + clearance at the scroll limit. +- Selected Bill Gates and then restored Naiwa; the selected row updated correctly both times. +- Browser console reported no warnings or errors after the final reload. +- `bun script/verify/sdlc.ts` — passed; task-scoped `git diff --check` — passed. + +Verdict: verified. + +### Acceptance evidence + +- AC-1: PASS — `bun test tests/petSettings.test.tsx tests/settingsLayoutContract.test.ts` covered the shared setting-row and list behavior. +- AC-2: PASS — recorded renderer inspection computed catalog and Session behavior shadows as `none`. +- AC-3: PASS — focused pet tests and the recorded selection restore preserved preview, selection, mood, visibility, activity, and size behavior. Evidence: `Verification record above`. +- AC-4: PASS — the `http://localhost:1420/` scroll-limit inspection measured an `80px` final-section inset. +- AC-5: PASS — the recorded 1280x720, 800x600, and 600x600 light/dark matrix had zero horizontal overflow. Evidence: `Verification record above`. +- AC-6: PASS — focused tests, `bunx tsc --noEmit`, `bun run check:design`, `bun script/verify/sdlc.ts`, screenshots, console inspection, and `git diff --check` passed. + +Residual risk: the existing non-failing React `act(...)` warnings remain; no product release was +reviewed or authorized. + +## Visual evidence + +See bundle evidence/ when present. + +## Security and privacy evidence + +Not separately recorded unless present in legacy Verification. + +## Deviations and residual risk + +Residual risk: the existing non-failing React `act(...)` warnings remain; no product release was + +## Verdict + +Verdict: verified.. + +## Review and release + +No PR, merge, or release requested. Human product review remains the next lifecycle trigger. + +## Feedback + +No additional layout, overflow, interaction, or scroll-boundary defects were observed. diff --git a/docs/sdlc/changes/2026-08-29-semantic-radius-floor/change.md b/docs/sdlc/changes/2026-08-29-semantic-radius-floor/change.md deleted file mode 100644 index 43e89bb9..00000000 --- a/docs/sdlc/changes/2026-08-29-semantic-radius-floor/change.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -id: change-2026-08-29-semantic-radius-floor -kind: change -schema: 2 -status: verified -risk: low -owner: codex -approvers: "#decision-and-gates" -approved_at: 2026-08-29 -created: 2026-08-29 -updated: 2026-08-31 -source: "#intent" -inputs: "#spec" -outputs: "#build" -scope: apps/desktop, docs/design/system.md -next_trigger: human review accepts the rendered geometry and release risk -verification_mode: fresh-context -verified_by: Sol independent review -verified_at: 2026-08-29 ---- - -# Raise the semantic radius floor - -## Intent - -The user requested one consistent radius increase across the desktop UI and annotated the new-task -surface with exact target values. The smallest visible semantic radius must be 12px. Module -containers that previously used 12px must move to 16px, while the repaired Composer remains at its -existing fixed 24px radius. - -## Spec - -Change the semantic geometry tokens rather than adding local overrides. Map both micro and control -radii to 12px, and both module and modal radii to 16px. Preserve fully round geometry for -intrinsically circular controls and preserve the 24px Composer radius. - -### Acceptance criteria - -- [x] AC-1: No visible semantic role resolves below 12px; verify with the token contract test. -- [x] AC-2: Add action, Run, and Scene controls resolve to 12px. -- [x] AC-3: The split Open control resolves to 12px on each exposed outer edge and keeps the joined edge - square. -- [x] AC-4: Project health and Project checkout resolve to 16px. -- [x] AC-5: The Composer remains 24px and its editor stays inside the painted card. -- [x] AC-6: The annotated surface is checked at narrow and standard widths in light and dark appearance. -- [x] AC-7: The focused regression tests, renderer build, design-system check, and SDLC check pass. - -## Decision and gates - -Intent and exact geometry are supplied directly by the user's 2026-08-29 browser annotations. No -permission to publish, merge, or release is implied. - -## Plan - -Update the semantic token mappings, the design-system preview labels, and the design law. Validate -the exact computed radii from the real callers and keep the change at the shared-token boundary. -Rollback is the inverse token mapping. - -## Build - -The semantic token source now maps micro and control to 12px and module and modal to 16px. A -compatibility bridge gives the remaining legacy `rounded`, `rounded-sm`, `rounded-md`, and -`rounded-lg` utilities the same 12px floor without changing joined-edge `rounded-*-none` behavior. -The design preview and design law show the new values. - -## Verification - -- Sol's minimal independent review ran `bun test tests/composerGeometryContract.test.ts` with 3 - passes, then `bun test tests/designSystem.test.ts -t "radii|radius"` with 2 passes and 12 - assertions. `git diff --check` also passed. -- At 811x998 in both light and dark appearance, computed corners were Add action 12px, Run 12px, - Scene 12px, Open `12/0/0/12`, Open More `0/12/12/0`, Project health 16px, Project checkout 16px, - and Composer 24px. The previously unannotated Split right control also moved from 4px to 12px. -- At 1280x800 in both light and dark appearance, the audited visible controls had no non-zero - corner below 12px and the typed editor stayed within the Composer card. -- `bun run build:renderer`: passed TypeScript, Vite production build, source design check, and - built-CSS design check; 0 new design violations and 35 semantic selectors generated. -- `bun script/verify/sdlc.ts` and `git diff --check`: passed. - -Verdict: verified. - -### Acceptance evidence - -- AC-1: PASS — `bun test tests/designSystem.test.ts -t "radii|radius"` verified the 12px semantic floor. -- AC-2: PASS — recorded 811x998 computed styles measured Add, Run, and Scene controls at `12px`. -- AC-3: PASS — the same inspection measured split Open corners as `12/0/0/12` and `0/12/12/0`. -- AC-4: PASS — recorded computed styles measured Project health and checkout modules at `16px`. -- AC-5: PASS — `bun test tests/composerGeometryContract.test.ts` and rendered inspection retained the 24px Composer and contained editor. -- AC-6: PASS — recorded light/dark screenshots covered 811x998 and 1280x800 viewports. Evidence: `Verification record above`. -- AC-7: PASS — the two focused test commands, `bun run build:renderer`, `bun script/verify/sdlc.ts`, and `git diff --check` passed. - -Residual risk: visual evidence sampled the recorded viewport and appearance matrix rather than -every platform font/rasterization combination. - -## Review and release - -No PR, merge, or release requested. Human product review remains the next lifecycle trigger. - -## Feedback - -The exact Browser annotations are the accepted geometry source; no viewport-only overrides or -preview attributes were copied into production code. diff --git a/docs/sdlc/changes/2026-08-29-semantic-radius-floor/intent.md b/docs/sdlc/changes/2026-08-29-semantic-radius-floor/intent.md new file mode 100644 index 00000000..2bf574a8 --- /dev/null +++ b/docs/sdlc/changes/2026-08-29-semantic-radius-floor/intent.md @@ -0,0 +1,51 @@ +--- +id: "2026-08-29-semantic-radius-floor" +stage: intent +schema: 3 +status: accepted +owner: codex +created: 2026-08-29 +source: #intent +risk: low +approved_by: "#decision-and-gates" +approved_at: "2026-08-29" +--- + +# Intent: Raise the semantic radius floor + +## Problem + +The user requested one consistent radius increase across the desktop UI and annotated the new-task +surface with exact target values. The smallest visible semantic radius must be 12px. Module +containers that previously used 12px must move to 16px, while the repaired Composer remains at its +existing fixed 24px radius. + +## Proposed outcome + +The user requested one consistent radius increase across the desktop UI and annotated the new-task + +## Affected users and systems + +Migrated from legacy change.md. + +## Constraints + +Intent and exact geometry are supplied directly by the user's 2026-08-29 browser annotations. No +permission to publish, merge, or release is implied. + +## Out of scope + +Not recorded in the legacy single-file Artifact. + +## Success signals + +See Spec acceptance criteria. + +## Open questions + +None recorded in migration. + +## Decision + +Intent and exact geometry are supplied directly by the user's 2026-08-29 browser annotations. No +permission to publish, merge, or release is implied. diff --git a/docs/sdlc/changes/2026-08-29-semantic-radius-floor/plan.md b/docs/sdlc/changes/2026-08-29-semantic-radius-floor/plan.md new file mode 100644 index 00000000..ae1eb1e8 --- /dev/null +++ b/docs/sdlc/changes/2026-08-29-semantic-radius-floor/plan.md @@ -0,0 +1,53 @@ +--- +id: "2026-08-29-semantic-radius-floor" +stage: plan +schema: 3 +status: accepted +owner: codex +created: 2026-08-29 +based_on: spec.md +risk: low +scope: apps/desktop, docs/design/system.md +approved_by: "#decision-and-gates" +approved_at: "2026-08-29" +--- + +# Plan: Raise the semantic radius floor + +## Files and ownership + +apps/desktop, docs/design/system.md + +## Order of work + +Update the semantic token mappings, the design-system preview labels, and the design law. Validate +the exact computed radii from the real callers and keep the change at the shared-token boundary. +Rollback is the inverse token mapping. + +## Test-first proof + +See legacy Verification section. + +## Visual or integration proof + +See legacy Verification section. + +## Risks and mitigations + +See legacy Decision and gates. + +## Rollback + +See legacy Review and release. + +## Deviations + +The semantic token source now maps micro and control to 12px and module and modal to 16px. A +compatibility bridge gives the remaining legacy `rounded`, `rounded-sm`, `rounded-md`, and +`rounded-lg` utilities the same 12px floor without changing joined-edge `rounded-*-none` behavior. +The design preview and design law show the new values. + +## Decision + +Intent and exact geometry are supplied directly by the user's 2026-08-29 browser annotations. No +permission to publish, merge, or release is implied. diff --git a/docs/sdlc/changes/2026-08-29-semantic-radius-floor/spec.md b/docs/sdlc/changes/2026-08-29-semantic-radius-floor/spec.md new file mode 100644 index 00000000..4249b2f7 --- /dev/null +++ b/docs/sdlc/changes/2026-08-29-semantic-radius-floor/spec.md @@ -0,0 +1,57 @@ +--- +id: "2026-08-29-semantic-radius-floor" +stage: spec +schema: 3 +status: accepted +owner: codex +created: 2026-08-29 +based_on: intent.md +risk: low +approved_by: "#decision-and-gates" +approved_at: "2026-08-29" +--- + +# Spec: Raise the semantic radius floor + +## Requirements + +Change the semantic geometry tokens rather than adding local overrides. Map both micro and control +radii to 12px, and both module and modal radii to 16px. Preserve fully round geometry for +intrinsically circular controls and preserve the 24px Composer radius. + +## User experience + +Not separately recorded in legacy change.md. + +## Technical design + +See Requirements and legacy Git history. + +## Security and privacy + +See migrated Decision and gates. + +## Alternatives and non-goals + +Not separately recorded in legacy change.md. + +## Areas of concern + +Intent and exact geometry are supplied directly by the user's 2026-08-29 browser annotations. No +permission to publish, merge, or release is implied. + +## Acceptance criteria + +- [x] AC-1: No visible semantic role resolves below 12px; verify with the token contract test. +- [x] AC-2: Add action, Run, and Scene controls resolve to 12px. +- [x] AC-3: The split Open control resolves to 12px on each exposed outer edge and keeps the joined edge + square. +- [x] AC-4: Project health and Project checkout resolve to 16px. +- [x] AC-5: The Composer remains 24px and its editor stays inside the painted card. +- [x] AC-6: The annotated surface is checked at narrow and standard widths in light and dark appearance. +- [x] AC-7: The focused regression tests, renderer build, design-system check, and SDLC check pass. + +## Decision + +Intent and exact geometry are supplied directly by the user's 2026-08-29 browser annotations. No +permission to publish, merge, or release is implied. diff --git a/docs/sdlc/changes/2026-08-29-semantic-radius-floor/verification.md b/docs/sdlc/changes/2026-08-29-semantic-radius-floor/verification.md new file mode 100644 index 00000000..f415707c --- /dev/null +++ b/docs/sdlc/changes/2026-08-29-semantic-radius-floor/verification.md @@ -0,0 +1,100 @@ +--- +id: "2026-08-29-semantic-radius-floor" +stage: verification +schema: 3 +status: passed +owner: codex +created: 2026-08-29 +based_on: plan.md +commit: "" +verification_mode: fresh-context +verified_by: "Sol independent review" +verified_at: "2026-08-29" +release_target: none +release_identity: "" +--- + +# Verification: Raise the semantic radius floor + +## Automated checks + +- Sol's minimal independent review ran `bun test tests/composerGeometryContract.test.ts` with 3 + passes, then `bun test tests/designSystem.test.ts -t "radii|radius"` with 2 passes and 12 + assertions. `git diff --check` also passed. +- At 811x998 in both light and dark appearance, computed corners were Add action 12px, Run 12px, + Scene 12px, Open `12/0/0/12`, Open More `0/12/12/0`, Project health 16px, Project checkout 16px, + and Composer 24px. The previously unannotated Split right control also moved from 4px to 12px. +- At 1280x800 in both light and dark appearance, the audited visible controls had no non-zero + corner below 12px and the typed editor stayed within the Composer card. +- `bun run build:renderer`: passed TypeScript, Vite production build, source design check, and + built-CSS design check; 0 new design violations and 35 semantic selectors generated. +- `bun script/verify/sdlc.ts` and `git diff --check`: passed. + +Verdict: verified. + +### Acceptance evidence + +- AC-1: PASS — `bun test tests/designSystem.test.ts -t "radii|radius"` verified the 12px semantic floor. +- AC-2: PASS — recorded 811x998 computed styles measured Add, Run, and Scene controls at `12px`. +- AC-3: PASS — the same inspection measured split Open corners as `12/0/0/12` and `0/12/12/0`. +- AC-4: PASS — recorded computed styles measured Project health and checkout modules at `16px`. +- AC-5: PASS — `bun test tests/composerGeometryContract.test.ts` and rendered inspection retained the 24px Composer and contained editor. +- AC-6: PASS — recorded light/dark screenshots covered 811x998 and 1280x800 viewports. Evidence: `Verification record above`. +- AC-7: PASS — the two focused test commands, `bun run build:renderer`, `bun script/verify/sdlc.ts`, and `git diff --check` passed. + +Residual risk: visual evidence sampled the recorded viewport and appearance matrix rather than +every platform font/rasterization combination. + +## Behavioral evidence + +- Sol's minimal independent review ran `bun test tests/composerGeometryContract.test.ts` with 3 + passes, then `bun test tests/designSystem.test.ts -t "radii|radius"` with 2 passes and 12 + assertions. `git diff --check` also passed. +- At 811x998 in both light and dark appearance, computed corners were Add action 12px, Run 12px, + Scene 12px, Open `12/0/0/12`, Open More `0/12/12/0`, Project health 16px, Project checkout 16px, + and Composer 24px. The previously unannotated Split right control also moved from 4px to 12px. +- At 1280x800 in both light and dark appearance, the audited visible controls had no non-zero + corner below 12px and the typed editor stayed within the Composer card. +- `bun run build:renderer`: passed TypeScript, Vite production build, source design check, and + built-CSS design check; 0 new design violations and 35 semantic selectors generated. +- `bun script/verify/sdlc.ts` and `git diff --check`: passed. + +Verdict: verified. + +### Acceptance evidence + +- AC-1: PASS — `bun test tests/designSystem.test.ts -t "radii|radius"` verified the 12px semantic floor. +- AC-2: PASS — recorded 811x998 computed styles measured Add, Run, and Scene controls at `12px`. +- AC-3: PASS — the same inspection measured split Open corners as `12/0/0/12` and `0/12/12/0`. +- AC-4: PASS — recorded computed styles measured Project health and checkout modules at `16px`. +- AC-5: PASS — `bun test tests/composerGeometryContract.test.ts` and rendered inspection retained the 24px Composer and contained editor. +- AC-6: PASS — recorded light/dark screenshots covered 811x998 and 1280x800 viewports. Evidence: `Verification record above`. +- AC-7: PASS — the two focused test commands, `bun run build:renderer`, `bun script/verify/sdlc.ts`, and `git diff --check` passed. + +Residual risk: visual evidence sampled the recorded viewport and appearance matrix rather than +every platform font/rasterization combination. + +## Visual evidence + +See bundle evidence/ when present. + +## Security and privacy evidence + +Not separately recorded unless present in legacy Verification. + +## Deviations and residual risk + +Residual risk: visual evidence sampled the recorded viewport and appearance matrix rather than + +## Verdict + +Verdict: verified.. + +## Review and release + +No PR, merge, or release requested. Human product review remains the next lifecycle trigger. + +## Feedback + +The exact Browser annotations are the accepted geometry source; no viewport-only overrides or +preview attributes were copied into production code. diff --git a/docs/sdlc/changes/2026-08-29-session-header-toolbar-unification/change.md b/docs/sdlc/changes/2026-08-29-session-header-toolbar-unification/change.md deleted file mode 100644 index 657e2a44..00000000 --- a/docs/sdlc/changes/2026-08-29-session-header-toolbar-unification/change.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -id: change-2026-08-29-session-header-toolbar-unification -kind: change -schema: 2 -status: verified -risk: low -owner: codex -approvers: "#decision-and-gates" -approved_at: 2026-08-29 -created: 2026-08-29 -updated: 2026-08-31 -source: "#intent" -inputs: "#spec" -outputs: "#build" -scope: apps/desktop, docs/design/system.md -next_trigger: human review accepts the rendered interaction and release risk -verification_mode: owner -verified_by: codex -verified_at: 2026-08-29 ---- - -# Unify the session titlebar toolbar - -## Intent - -The user reported from the live session titlebar that its icons use two competing colors and that -neighboring controls mix filled and transparent treatments with uneven spacing. The desired result -is one quiet, macOS-like toolbar: neutral gray icons at rest, consistent control geometry and -spacing, and no persistent filled button competing with the session title. This change is limited -to the right side of the session titlebar and preserves every action and accessible name. - -## Spec - -The session titlebar uses the existing muted foreground for every toolbar icon and label across -rest, hover, open, and pressed states; disabled controls remain visibly disabled. All available -actions use transparent toolbar chrome at rest. Hover, open, or pressed controls may use a neutral -fill, but must not change the icon color or use the product accent color. Standalone titlebar controls -share a 28px square height and a 4px gap; the two halves of a split button keep a zero-width inner -gap and a subtle seam. - -### Acceptance criteria - -- [x] AC-1: In dark and light appearance, every enabled resting titlebar icon has the same computed - neutral foreground and transparent background. -- [x] AC-2: Open or pressed state remains discoverable through a neutral surface without an accent-color - icon; disabled state remains distinct. -- [x] AC-3: Environment, pane, project-action, split-menu, plugin, and panel controls share 28px height, - 4px spacing between independent controls, and aligned icon sizing. -- [x] AC-4: Add action, Open, Commit, split menus, pane controls, environment, plugin action, and panel - actions retain their accessible names and behavior. -- [x] AC-5: Focused tests, design check, SDLC check, and rendered console check pass. - -## Decision and gates - -Intent and design acceptance come directly from the user's 2026-08-29 titlebar feedback. No -permission to create a PR, merge, publish, or release is implied. - -## Plan - -Normalize the existing titlebar controls in place: use one neutral ghost treatment, preserve a -neutral selected state, align the pane buttons with the shared Button primitive, and wrap the -right-side controls in one 4px toolbar cluster. Add narrow contract assertions, document the -titlebar rule, then verify the real renderer at desktop and constrained widths in both appearances. -Rollback is the inverse source change. - -## Build - -The session action buttons, environment trigger, pane controls, panel toggle, and header plugin -actions now share the gray ghost treatment. Environment and panel selected states use the existing -neutral fill without changing icon color. Pane controls now consume the shared Button primitive at -28px, and the entire right-side titlebar is one 4px toolbar cluster. Both split groups explicitly -retain a zero-width inner gap and semantic 8px horizontal padding. - -## Verification - -- Six focused rendered/contract tests passed with 38 unrelated cases filtered out; a follow-up run - of the two changed session-action tests passed with 49 assertions. The selected tests covered - neutral styling, 28px geometry, 4px/0px gaps, split seams, plugin action treatment, popover - open/dismiss, pane wiring, titlebar composition, and the Open/Commit split-menu interaction. -- `bun run check:design`: passed with 0 new violations, 659 tracked legacy occurrences, and all - contrast checks passing. A focused review determined a full renderer build would add little - evidence for this class/markup-only change, so it was intentionally not run. -- At `http://localhost:1420/` in the 1280x720 dark renderer, every enabled resting titlebar control - resolved to one foreground value, a transparent background, 28px height, 4px toolbar/action gaps, - and 0px split-group gaps. The page title was `C2`, the page was nonblank, and console warning/error - output was empty. -- Opening Environment kept the same muted icon foreground and added only a neutral surface. Opening - the right panel constrained the session header to 620px, hid labels through the existing container - rule, preserved accessible names, and showed the pressed panel action with a neutral fill and no - clipping. Closing it restored a fully transparent resting toolbar. -- In light appearance, every enabled resting action again resolved to one foreground value and a - transparent background, with the same 28px height and 4px/0px gap contract. The appearance setting - was restored to System after verification. -- `bun script/verify/sdlc.ts` and `git diff --check`: passed. - -Verdict: verified. - -### Acceptance evidence - -- AC-1: PASS — recorded dark/light computed styles found the same resting neutral icon color across enabled titlebar actions. Evidence: `Verification record above`. -- AC-2: PASS — rendered open and pressed states used the recorded neutral surface without persistent accent fill. Evidence: `Verification record above`. -- AC-3: PASS — the focused toolbar contract and computed geometry retained the shared `28px` control height and spacing. -- AC-4: PASS — recorded pointer and keyboard inspection exercised Add, Open, Commit, split, pane, environment, plugin, and panel actions. Evidence: `Verification record above`. -- AC-5: PASS — focused tests, `bun run check:design`, `bun script/verify/sdlc.ts`, console inspection, and `git diff --check` passed. - -Residual risk: a full renderer build was intentionally skipped for this markup-only change; the -focused tests, design check, live renderer, and diff evidence are the acceptance boundary. - -## Review and release - -No PR, merge, or release requested. Human product review remains the next lifecycle trigger. - -## Feedback - -No additional defect observed during the dark, light, constrained, open, pressed, and restored -states above. diff --git a/docs/sdlc/changes/2026-08-29-session-header-toolbar-unification/intent.md b/docs/sdlc/changes/2026-08-29-session-header-toolbar-unification/intent.md new file mode 100644 index 00000000..5739f867 --- /dev/null +++ b/docs/sdlc/changes/2026-08-29-session-header-toolbar-unification/intent.md @@ -0,0 +1,52 @@ +--- +id: "2026-08-29-session-header-toolbar-unification" +stage: intent +schema: 3 +status: accepted +owner: codex +created: 2026-08-29 +source: #intent +risk: low +approved_by: "#decision-and-gates" +approved_at: "2026-08-29" +--- + +# Intent: Unify the session titlebar toolbar + +## Problem + +The user reported from the live session titlebar that its icons use two competing colors and that +neighboring controls mix filled and transparent treatments with uneven spacing. The desired result +is one quiet, macOS-like toolbar: neutral gray icons at rest, consistent control geometry and +spacing, and no persistent filled button competing with the session title. This change is limited +to the right side of the session titlebar and preserves every action and accessible name. + +## Proposed outcome + +The user reported from the live session titlebar that its icons use two competing colors and that + +## Affected users and systems + +Migrated from legacy change.md. + +## Constraints + +Intent and design acceptance come directly from the user's 2026-08-29 titlebar feedback. No +permission to create a PR, merge, publish, or release is implied. + +## Out of scope + +Not recorded in the legacy single-file Artifact. + +## Success signals + +See Spec acceptance criteria. + +## Open questions + +None recorded in migration. + +## Decision + +Intent and design acceptance come directly from the user's 2026-08-29 titlebar feedback. No +permission to create a PR, merge, publish, or release is implied. diff --git a/docs/sdlc/changes/2026-08-29-session-header-toolbar-unification/plan.md b/docs/sdlc/changes/2026-08-29-session-header-toolbar-unification/plan.md new file mode 100644 index 00000000..0e0a53b2 --- /dev/null +++ b/docs/sdlc/changes/2026-08-29-session-header-toolbar-unification/plan.md @@ -0,0 +1,56 @@ +--- +id: "2026-08-29-session-header-toolbar-unification" +stage: plan +schema: 3 +status: accepted +owner: codex +created: 2026-08-29 +based_on: spec.md +risk: low +scope: apps/desktop, docs/design/system.md +approved_by: "#decision-and-gates" +approved_at: "2026-08-29" +--- + +# Plan: Unify the session titlebar toolbar + +## Files and ownership + +apps/desktop, docs/design/system.md + +## Order of work + +Normalize the existing titlebar controls in place: use one neutral ghost treatment, preserve a +neutral selected state, align the pane buttons with the shared Button primitive, and wrap the +right-side controls in one 4px toolbar cluster. Add narrow contract assertions, document the +titlebar rule, then verify the real renderer at desktop and constrained widths in both appearances. +Rollback is the inverse source change. + +## Test-first proof + +See legacy Verification section. + +## Visual or integration proof + +See legacy Verification section. + +## Risks and mitigations + +See legacy Decision and gates. + +## Rollback + +See legacy Review and release. + +## Deviations + +The session action buttons, environment trigger, pane controls, panel toggle, and header plugin +actions now share the gray ghost treatment. Environment and panel selected states use the existing +neutral fill without changing icon color. Pane controls now consume the shared Button primitive at +28px, and the entire right-side titlebar is one 4px toolbar cluster. Both split groups explicitly +retain a zero-width inner gap and semantic 8px horizontal padding. + +## Decision + +Intent and design acceptance come directly from the user's 2026-08-29 titlebar feedback. No +permission to create a PR, merge, publish, or release is implied. diff --git a/docs/sdlc/changes/2026-08-29-session-header-toolbar-unification/spec.md b/docs/sdlc/changes/2026-08-29-session-header-toolbar-unification/spec.md new file mode 100644 index 00000000..c57c238e --- /dev/null +++ b/docs/sdlc/changes/2026-08-29-session-header-toolbar-unification/spec.md @@ -0,0 +1,61 @@ +--- +id: "2026-08-29-session-header-toolbar-unification" +stage: spec +schema: 3 +status: accepted +owner: codex +created: 2026-08-29 +based_on: intent.md +risk: low +approved_by: "#decision-and-gates" +approved_at: "2026-08-29" +--- + +# Spec: Unify the session titlebar toolbar + +## Requirements + +The session titlebar uses the existing muted foreground for every toolbar icon and label across +rest, hover, open, and pressed states; disabled controls remain visibly disabled. All available +actions use transparent toolbar chrome at rest. Hover, open, or pressed controls may use a neutral +fill, but must not change the icon color or use the product accent color. Standalone titlebar controls +share a 28px square height and a 4px gap; the two halves of a split button keep a zero-width inner +gap and a subtle seam. + +## User experience + +Not separately recorded in legacy change.md. + +## Technical design + +See Requirements and legacy Git history. + +## Security and privacy + +See migrated Decision and gates. + +## Alternatives and non-goals + +Not separately recorded in legacy change.md. + +## Areas of concern + +Intent and design acceptance come directly from the user's 2026-08-29 titlebar feedback. No +permission to create a PR, merge, publish, or release is implied. + +## Acceptance criteria + +- [x] AC-1: In dark and light appearance, every enabled resting titlebar icon has the same computed + neutral foreground and transparent background. +- [x] AC-2: Open or pressed state remains discoverable through a neutral surface without an accent-color + icon; disabled state remains distinct. +- [x] AC-3: Environment, pane, project-action, split-menu, plugin, and panel controls share 28px height, + 4px spacing between independent controls, and aligned icon sizing. +- [x] AC-4: Add action, Open, Commit, split menus, pane controls, environment, plugin action, and panel + actions retain their accessible names and behavior. +- [x] AC-5: Focused tests, design check, SDLC check, and rendered console check pass. + +## Decision + +Intent and design acceptance come directly from the user's 2026-08-29 titlebar feedback. No +permission to create a PR, merge, publish, or release is implied. diff --git a/docs/sdlc/changes/2026-08-29-session-header-toolbar-unification/verification.md b/docs/sdlc/changes/2026-08-29-session-header-toolbar-unification/verification.md new file mode 100644 index 00000000..d6ba93f0 --- /dev/null +++ b/docs/sdlc/changes/2026-08-29-session-header-toolbar-unification/verification.md @@ -0,0 +1,112 @@ +--- +id: "2026-08-29-session-header-toolbar-unification" +stage: verification +schema: 3 +status: passed +owner: codex +created: 2026-08-29 +based_on: plan.md +commit: "" +verification_mode: owner +verified_by: "codex" +verified_at: "2026-08-29" +release_target: none +release_identity: "" +--- + +# Verification: Unify the session titlebar toolbar + +## Automated checks + +- Six focused rendered/contract tests passed with 38 unrelated cases filtered out; a follow-up run + of the two changed session-action tests passed with 49 assertions. The selected tests covered + neutral styling, 28px geometry, 4px/0px gaps, split seams, plugin action treatment, popover + open/dismiss, pane wiring, titlebar composition, and the Open/Commit split-menu interaction. +- `bun run check:design`: passed with 0 new violations, 659 tracked legacy occurrences, and all + contrast checks passing. A focused review determined a full renderer build would add little + evidence for this class/markup-only change, so it was intentionally not run. +- At `http://localhost:1420/` in the 1280x720 dark renderer, every enabled resting titlebar control + resolved to one foreground value, a transparent background, 28px height, 4px toolbar/action gaps, + and 0px split-group gaps. The page title was `C2`, the page was nonblank, and console warning/error + output was empty. +- Opening Environment kept the same muted icon foreground and added only a neutral surface. Opening + the right panel constrained the session header to 620px, hid labels through the existing container + rule, preserved accessible names, and showed the pressed panel action with a neutral fill and no + clipping. Closing it restored a fully transparent resting toolbar. +- In light appearance, every enabled resting action again resolved to one foreground value and a + transparent background, with the same 28px height and 4px/0px gap contract. The appearance setting + was restored to System after verification. +- `bun script/verify/sdlc.ts` and `git diff --check`: passed. + +Verdict: verified. + +### Acceptance evidence + +- AC-1: PASS — recorded dark/light computed styles found the same resting neutral icon color across enabled titlebar actions. Evidence: `Verification record above`. +- AC-2: PASS — rendered open and pressed states used the recorded neutral surface without persistent accent fill. Evidence: `Verification record above`. +- AC-3: PASS — the focused toolbar contract and computed geometry retained the shared `28px` control height and spacing. +- AC-4: PASS — recorded pointer and keyboard inspection exercised Add, Open, Commit, split, pane, environment, plugin, and panel actions. Evidence: `Verification record above`. +- AC-5: PASS — focused tests, `bun run check:design`, `bun script/verify/sdlc.ts`, console inspection, and `git diff --check` passed. + +Residual risk: a full renderer build was intentionally skipped for this markup-only change; the +focused tests, design check, live renderer, and diff evidence are the acceptance boundary. + +## Behavioral evidence + +- Six focused rendered/contract tests passed with 38 unrelated cases filtered out; a follow-up run + of the two changed session-action tests passed with 49 assertions. The selected tests covered + neutral styling, 28px geometry, 4px/0px gaps, split seams, plugin action treatment, popover + open/dismiss, pane wiring, titlebar composition, and the Open/Commit split-menu interaction. +- `bun run check:design`: passed with 0 new violations, 659 tracked legacy occurrences, and all + contrast checks passing. A focused review determined a full renderer build would add little + evidence for this class/markup-only change, so it was intentionally not run. +- At `http://localhost:1420/` in the 1280x720 dark renderer, every enabled resting titlebar control + resolved to one foreground value, a transparent background, 28px height, 4px toolbar/action gaps, + and 0px split-group gaps. The page title was `C2`, the page was nonblank, and console warning/error + output was empty. +- Opening Environment kept the same muted icon foreground and added only a neutral surface. Opening + the right panel constrained the session header to 620px, hid labels through the existing container + rule, preserved accessible names, and showed the pressed panel action with a neutral fill and no + clipping. Closing it restored a fully transparent resting toolbar. +- In light appearance, every enabled resting action again resolved to one foreground value and a + transparent background, with the same 28px height and 4px/0px gap contract. The appearance setting + was restored to System after verification. +- `bun script/verify/sdlc.ts` and `git diff --check`: passed. + +Verdict: verified. + +### Acceptance evidence + +- AC-1: PASS — recorded dark/light computed styles found the same resting neutral icon color across enabled titlebar actions. Evidence: `Verification record above`. +- AC-2: PASS — rendered open and pressed states used the recorded neutral surface without persistent accent fill. Evidence: `Verification record above`. +- AC-3: PASS — the focused toolbar contract and computed geometry retained the shared `28px` control height and spacing. +- AC-4: PASS — recorded pointer and keyboard inspection exercised Add, Open, Commit, split, pane, environment, plugin, and panel actions. Evidence: `Verification record above`. +- AC-5: PASS — focused tests, `bun run check:design`, `bun script/verify/sdlc.ts`, console inspection, and `git diff --check` passed. + +Residual risk: a full renderer build was intentionally skipped for this markup-only change; the +focused tests, design check, live renderer, and diff evidence are the acceptance boundary. + +## Visual evidence + +See bundle evidence/ when present. + +## Security and privacy evidence + +Not separately recorded unless present in legacy Verification. + +## Deviations and residual risk + +Residual risk: a full renderer build was intentionally skipped for this markup-only change; the + +## Verdict + +Verdict: verified.. + +## Review and release + +No PR, merge, or release requested. Human product review remains the next lifecycle trigger. + +## Feedback + +No additional defect observed during the dark, light, constrained, open, pressed, and restored +states above. diff --git a/docs/sdlc/changes/2026-08-30-ai-native-sdlc-learning-loop/change.md b/docs/sdlc/changes/2026-08-30-ai-native-sdlc-learning-loop/change.md deleted file mode 100644 index b89d8c27..00000000 --- a/docs/sdlc/changes/2026-08-30-ai-native-sdlc-learning-loop/change.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -id: change-2026-08-30-ai-native-sdlc-learning-loop -kind: change -schema: 2 -status: verified -risk: low -owner: repository maintainers -approvers: user via the 2026-08-30 implementation request -approved_at: 2026-08-30 -created: 2026-08-30 -updated: 2026-08-31 -source: current user request to install the self-improving-agent system -inputs: installed ai-native-sdlc base skill and the repository SDLC feedback and Eval mechanisms -outputs: project-scoped proposal-only learning records and verification configuration -scope: .agent-learning/ai-native-sdlc, docs/sdlc -next_trigger: the authorized PR passes required checks and merges into origin/main -verification_mode: owner -verified_by: repository maintainers -verified_at: 2026-08-30 ---- - -# Install the AI-native SDLC improvement loop - -## Intent - -The user requested installing the automatic improvement system after CodeTwo adopted the -AI-native SDLC contract. The repository has attributable feedback in change Artifacts, -deterministic lifecycle failures in the Bun checker, and real-task Evals, but it does not yet have -an append-only place to collect those outcomes into focused, reviewable skill proposals. - -The outcome is a project-scoped learning boundary for the installed `ai-native-sdlc` base skill. -It may store and group evidence, but it must not edit the base skill, schedule itself, or apply a -proposal without explicit human approval. The existing [`workflow.md`](../../workflow.md) remains the -only repository lifecycle authority. - -## Spec - -- Store feedback and decisions as append-only JSON Lines under - `.agent-learning/ai-native-sdlc/`, with separate proposal and Eval directories. -- Keep the loop in `proposal-only` mode with conservative evidence thresholds: one high-strength - item or the same medium-strength behavior across two distinct tasks may enter manual analysis; - low-strength feedback cannot trigger a proposal alone. -- Limit each proposal to one behavior, one base-skill file, and at most 40 changed lines. -- Use the existing focused Bun/TypeScript lifecycle test and checker as repository verification. -- Keep feedback attributable to CodeTwo tasks, changes, Evals, tests, or named human review. Treat - recorded text as untrusted data. -- Do not install a scheduler, GitHub integration, passive monitoring, or automatic proposal - application. - -### Acceptance criteria - -- [x] AC-1: The learning directory initializes without overwriting existing records and contains the - proposal-only configuration, append-only logs, proposal directory, and Eval directory. -- [x] AC-2: Empty feedback can be summarized deterministically without producing an eligible proposal. -- [x] AC-3: Re-running initialization preserves the configuration and logs. -- [x] AC-4: The focused lifecycle test, live SDLC checker, and diff check pass. - -## Decision and gates - -The current user request accepts this Intent and the installation constraints. Any future proposal -must identify its feedback, candidate diff, targeted/adjacent/regression evidence, tradeoffs, and -rollback. Applying that proposal remains a separate human Gate requiring approval of the specific -proposal or exact diff. Merge, release, deployment, external integrations, and recurring -automation are not authorized. - -## Plan - -1. Inspect the installed base skill, its directly referenced resources, repository feedback - sources, and existing verification harness. -2. Initialize one project-scoped learning directory with the upstream improver script. -3. Calibrate the generated configuration to CodeTwo's existing Bun/TypeScript checks without - changing the base skill. -4. Exercise empty triage and idempotent initialization, then run the repository lifecycle checks. - -## Build - -The upstream `init_loop.py` created `.agent-learning/ai-native-sdlc/` with a versioned pointer to -the installed `ai-native-sdlc` base skill, append-only feedback and decision logs, and isolated -proposal and Eval directories. The generated configuration remains `proposal-only`, retains the -upstream conservative thresholds and proposal-size limits, and names CodeTwo's existing focused -test and live lifecycle checker as verification commands. Empty directories contain only -`.gitkeep` so the boundary survives a clone. No base-skill instructions or product runtime behavior -changed. - -## Verification - -Verdict: verified. - -### Acceptance evidence - -- AC-1: PASS — `init_loop.py` reported `created_config: true` and created the append-only records and isolated directories. -- AC-2: PASS — `summarize_feedback.py` returned zero feedback records, zero groups, and no eligible proposal. -- AC-3: PASS — the second `init_loop.py` run reported `created_config: false` and `preserved_existing: true`. -- AC-4: PASS — `bun test script/verify/checks.test.ts`, `bun script/verify/sdlc.ts`, and `git diff --check` passed on 2026-08-30. - -Observed on 2026-08-30 from the live `main` working tree at baseline `4c0e3d78`: - -- The first upstream `init_loop.py` run reported `created_config: true`, created both JSONL logs, - and resolved `.agent-learning/ai-native-sdlc` for skill `ai-native-sdlc`. -- `summarize_feedback.py` read the empty feedback and decision logs and returned zero feedback - records and zero groups, so no proposal was eligible. -- A second identical `init_loop.py` run reported `created_config: false`, no created logs, and - `preserved_existing: true`. -- `validate_skill.py` reported the installed 80-line base skill valid with no errors or warnings. -- `bun test script/verify/checks.test.ts` passed all 10 tests with 24 assertions. -- `bun script/verify/sdlc.ts` returned `[sdlc] contract valid`. -- `git diff --check` passed. - -Residual risk: the loop begins with no imported feedback and no global outcome metric, so it cannot -yet establish that a future local Eval gain improves project outcomes. Its base-skill path is tied -to the locally installed `ai-native-sdlc` plugin version `1.1.0`; a plugin relocation or upgrade -must re-resolve that path before proposals are applied. There is intentionally no passive feedback -collector or scheduler. - -## Review and release - -Approval: the user authorized PR creation and merge on 2026-08-30 after reviewing the verified -installation handoff. -Release target: none. -Release identity: not applicable until released. -Smoke evidence: not applicable until released. -Rollback: remove the new `.agent-learning/ai-native-sdlc/` boundary and revert this Artifact. -No release: this repository-process configuration does not ship a product release. - -## Feedback - -No feedback has been imported into the new loop. Historical corrections remain at their existing -authoritative sources until a later recording operation verifies attribution, causality, expected -behavior, and rationale. diff --git a/docs/sdlc/changes/2026-08-30-ai-native-sdlc-learning-loop/intent.md b/docs/sdlc/changes/2026-08-30-ai-native-sdlc-learning-loop/intent.md new file mode 100644 index 00000000..dccdc7ca --- /dev/null +++ b/docs/sdlc/changes/2026-08-30-ai-native-sdlc-learning-loop/intent.md @@ -0,0 +1,62 @@ +--- +id: "2026-08-30-ai-native-sdlc-learning-loop" +stage: intent +schema: 3 +status: accepted +owner: repository maintainers +created: 2026-08-30 +source: current user request to install the self-improving-agent system +risk: low +approved_by: "userthe 2026-08-30 implementation request" +approved_at: "2026-08-30" +--- + +# Intent: Install the AI-native SDLC improvement loop + +## Problem + +The user requested installing the automatic improvement system after CodeTwo adopted the +AI-native SDLC contract. The repository has attributable feedback in change Artifacts, +deterministic lifecycle failures in the Bun checker, and real-task Evals, but it does not yet have +an append-only place to collect those outcomes into focused, reviewable skill proposals. + +The outcome is a project-scoped learning boundary for the installed `ai-native-sdlc` base skill. +It may store and group evidence, but it must not edit the base skill, schedule itself, or apply a +proposal without explicit human approval. The existing [`workflow.md`](../../workflow.md) remains the +only repository lifecycle authority. + +## Proposed outcome + +The user requested installing the automatic improvement system after CodeTwo adopted the + +## Affected users and systems + +Migrated from legacy change.md. + +## Constraints + +The current user request accepts this Intent and the installation constraints. Any future proposal +must identify its feedback, candidate diff, targeted/adjacent/regression evidence, tradeoffs, and +rollback. Applying that proposal remains a separate human Gate requiring approval of the specific +proposal or exact diff. Merge, release, deployment, external integrations, and recurring +automation are not authorized. + +## Out of scope + +Not recorded in the legacy single-file Artifact. + +## Success signals + +See Spec acceptance criteria. + +## Open questions + +None recorded in migration. + +## Decision + +The current user request accepts this Intent and the installation constraints. Any future proposal +must identify its feedback, candidate diff, targeted/adjacent/regression evidence, tradeoffs, and +rollback. Applying that proposal remains a separate human Gate requiring approval of the specific +proposal or exact diff. Merge, release, deployment, external integrations, and recurring +automation are not authorized. diff --git a/docs/sdlc/changes/2026-08-30-ai-native-sdlc-learning-loop/plan.md b/docs/sdlc/changes/2026-08-30-ai-native-sdlc-learning-loop/plan.md new file mode 100644 index 00000000..54fd0963 --- /dev/null +++ b/docs/sdlc/changes/2026-08-30-ai-native-sdlc-learning-loop/plan.md @@ -0,0 +1,62 @@ +--- +id: "2026-08-30-ai-native-sdlc-learning-loop" +stage: plan +schema: 3 +status: accepted +owner: repository maintainers +created: 2026-08-30 +based_on: spec.md +risk: low +scope: .agent-learning/ai-native-sdlc, docs/sdlc +approved_by: "userthe 2026-08-30 implementation request" +approved_at: "2026-08-30" +--- + +# Plan: Install the AI-native SDLC improvement loop + +## Files and ownership + +.agent-learning/ai-native-sdlc, docs/sdlc + +## Order of work + +1. Inspect the installed base skill, its directly referenced resources, repository feedback + sources, and existing verification harness. +2. Initialize one project-scoped learning directory with the upstream improver script. +3. Calibrate the generated configuration to CodeTwo's existing Bun/TypeScript checks without + changing the base skill. +4. Exercise empty triage and idempotent initialization, then run the repository lifecycle checks. + +## Test-first proof + +See legacy Verification section. + +## Visual or integration proof + +See legacy Verification section. + +## Risks and mitigations + +See legacy Decision and gates. + +## Rollback + +See legacy Review and release. + +## Deviations + +The upstream `init_loop.py` created `.agent-learning/ai-native-sdlc/` with a versioned pointer to +the installed `ai-native-sdlc` base skill, append-only feedback and decision logs, and isolated +proposal and Eval directories. The generated configuration remains `proposal-only`, retains the +upstream conservative thresholds and proposal-size limits, and names CodeTwo's existing focused +test and live lifecycle checker as verification commands. Empty directories contain only +`.gitkeep` so the boundary survives a clone. No base-skill instructions or product runtime behavior +changed. + +## Decision + +The current user request accepts this Intent and the installation constraints. Any future proposal +must identify its feedback, candidate diff, targeted/adjacent/regression evidence, tradeoffs, and +rollback. Applying that proposal remains a separate human Gate requiring approval of the specific +proposal or exact diff. Merge, release, deployment, external integrations, and recurring +automation are not authorized. diff --git a/docs/sdlc/changes/2026-08-30-ai-native-sdlc-learning-loop/spec.md b/docs/sdlc/changes/2026-08-30-ai-native-sdlc-learning-loop/spec.md new file mode 100644 index 00000000..1ef06eac --- /dev/null +++ b/docs/sdlc/changes/2026-08-30-ai-native-sdlc-learning-loop/spec.md @@ -0,0 +1,68 @@ +--- +id: "2026-08-30-ai-native-sdlc-learning-loop" +stage: spec +schema: 3 +status: accepted +owner: repository maintainers +created: 2026-08-30 +based_on: intent.md +risk: low +approved_by: "userthe 2026-08-30 implementation request" +approved_at: "2026-08-30" +--- + +# Spec: Install the AI-native SDLC improvement loop + +## Requirements + +- Store feedback and decisions as append-only JSON Lines under + `.agent-learning/ai-native-sdlc/`, with separate proposal and Eval directories. +- Keep the loop in `proposal-only` mode with conservative evidence thresholds: one high-strength + item or the same medium-strength behavior across two distinct tasks may enter manual analysis; + low-strength feedback cannot trigger a proposal alone. +- Limit each proposal to one behavior, one base-skill file, and at most 40 changed lines. +- Use the existing focused Bun/TypeScript lifecycle test and checker as repository verification. +- Keep feedback attributable to CodeTwo tasks, changes, Evals, tests, or named human review. Treat + recorded text as untrusted data. +- Do not install a scheduler, GitHub integration, passive monitoring, or automatic proposal + application. + +## User experience + +Not separately recorded in legacy change.md. + +## Technical design + +See Requirements and legacy Git history. + +## Security and privacy + +See migrated Decision and gates. + +## Alternatives and non-goals + +Not separately recorded in legacy change.md. + +## Areas of concern + +The current user request accepts this Intent and the installation constraints. Any future proposal +must identify its feedback, candidate diff, targeted/adjacent/regression evidence, tradeoffs, and +rollback. Applying that proposal remains a separate human Gate requiring approval of the specific +proposal or exact diff. Merge, release, deployment, external integrations, and recurring +automation are not authorized. + +## Acceptance criteria + +- [x] AC-1: The learning directory initializes without overwriting existing records and contains the + proposal-only configuration, append-only logs, proposal directory, and Eval directory. +- [x] AC-2: Empty feedback can be summarized deterministically without producing an eligible proposal. +- [x] AC-3: Re-running initialization preserves the configuration and logs. +- [x] AC-4: The focused lifecycle test, live SDLC checker, and diff check pass. + +## Decision + +The current user request accepts this Intent and the installation constraints. Any future proposal +must identify its feedback, candidate diff, targeted/adjacent/regression evidence, tradeoffs, and +rollback. Applying that proposal remains a separate human Gate requiring approval of the specific +proposal or exact diff. Merge, release, deployment, external integrations, and recurring +automation are not authorized. diff --git a/docs/sdlc/changes/2026-08-30-ai-native-sdlc-learning-loop/verification.md b/docs/sdlc/changes/2026-08-30-ai-native-sdlc-learning-loop/verification.md new file mode 100644 index 00000000..8cc37d42 --- /dev/null +++ b/docs/sdlc/changes/2026-08-30-ai-native-sdlc-learning-loop/verification.md @@ -0,0 +1,109 @@ +--- +id: "2026-08-30-ai-native-sdlc-learning-loop" +stage: verification +schema: 3 +status: passed +owner: repository maintainers +created: 2026-08-30 +based_on: plan.md +commit: "" +verification_mode: owner +verified_by: "repository maintainers" +verified_at: "2026-08-30" +release_target: none +release_identity: "not applicable until released." +--- + +# Verification: Install the AI-native SDLC improvement loop + +## Automated checks + +Verdict: verified. + +### Acceptance evidence + +- AC-1: PASS — `init_loop.py` reported `created_config: true` and created the append-only records and isolated directories. +- AC-2: PASS — `summarize_feedback.py` returned zero feedback records, zero groups, and no eligible proposal. +- AC-3: PASS — the second `init_loop.py` run reported `created_config: false` and `preserved_existing: true`. +- AC-4: PASS — `bun test script/verify/checks.test.ts`, `bun script/verify/sdlc.ts`, and `git diff --check` passed on 2026-08-30. + +Observed on 2026-08-30 from the live `main` working tree at baseline `4c0e3d78`: + +- The first upstream `init_loop.py` run reported `created_config: true`, created both JSONL logs, + and resolved `.agent-learning/ai-native-sdlc` for skill `ai-native-sdlc`. +- `summarize_feedback.py` read the empty feedback and decision logs and returned zero feedback + records and zero groups, so no proposal was eligible. +- A second identical `init_loop.py` run reported `created_config: false`, no created logs, and + `preserved_existing: true`. +- `validate_skill.py` reported the installed 80-line base skill valid with no errors or warnings. +- `bun test script/verify/checks.test.ts` passed all 10 tests with 24 assertions. +- `bun script/verify/sdlc.ts` returned `[sdlc] contract valid`. +- `git diff --check` passed. + +Residual risk: the loop begins with no imported feedback and no global outcome metric, so it cannot +yet establish that a future local Eval gain improves project outcomes. Its base-skill path is tied +to the locally installed `ai-native-sdlc` plugin version `1.1.0`; a plugin relocation or upgrade +must re-resolve that path before proposals are applied. There is intentionally no passive feedback +collector or scheduler. + +## Behavioral evidence + +Verdict: verified. + +### Acceptance evidence + +- AC-1: PASS — `init_loop.py` reported `created_config: true` and created the append-only records and isolated directories. +- AC-2: PASS — `summarize_feedback.py` returned zero feedback records, zero groups, and no eligible proposal. +- AC-3: PASS — the second `init_loop.py` run reported `created_config: false` and `preserved_existing: true`. +- AC-4: PASS — `bun test script/verify/checks.test.ts`, `bun script/verify/sdlc.ts`, and `git diff --check` passed on 2026-08-30. + +Observed on 2026-08-30 from the live `main` working tree at baseline `4c0e3d78`: + +- The first upstream `init_loop.py` run reported `created_config: true`, created both JSONL logs, + and resolved `.agent-learning/ai-native-sdlc` for skill `ai-native-sdlc`. +- `summarize_feedback.py` read the empty feedback and decision logs and returned zero feedback + records and zero groups, so no proposal was eligible. +- A second identical `init_loop.py` run reported `created_config: false`, no created logs, and + `preserved_existing: true`. +- `validate_skill.py` reported the installed 80-line base skill valid with no errors or warnings. +- `bun test script/verify/checks.test.ts` passed all 10 tests with 24 assertions. +- `bun script/verify/sdlc.ts` returned `[sdlc] contract valid`. +- `git diff --check` passed. + +Residual risk: the loop begins with no imported feedback and no global outcome metric, so it cannot +yet establish that a future local Eval gain improves project outcomes. Its base-skill path is tied +to the locally installed `ai-native-sdlc` plugin version `1.1.0`; a plugin relocation or upgrade +must re-resolve that path before proposals are applied. There is intentionally no passive feedback +collector or scheduler. + +## Visual evidence + +See bundle evidence/ when present. + +## Security and privacy evidence + +Not separately recorded unless present in legacy Verification. + +## Deviations and residual risk + +Residual risk: the loop begins with no imported feedback and no global outcome metric, so it cannot + +## Verdict + +Verdict: verified.. + +## Review and release + +Approval: the user authorized PR creation and merge on 2026-08-30 after reviewing the verified +installation handoff. +Release target: none. +Release identity: not applicable until released. +Smoke evidence: not applicable until released. +Rollback: remove the new `.agent-learning/ai-native-sdlc/` boundary and revert this Artifact. +No release: this repository-process configuration does not ship a product release. + +## Feedback + +No feedback has been imported into the new loop. Historical corrections remain at their existing +authoritative sources until a later recording operation verifies attribution, causality, expected +behavior, and rationale. diff --git a/docs/sdlc/changes/2026-08-30-ai-native-sdlc-migration/change.md b/docs/sdlc/changes/2026-08-30-ai-native-sdlc-migration/change.md deleted file mode 100644 index 430d13e5..00000000 --- a/docs/sdlc/changes/2026-08-30-ai-native-sdlc-migration/change.md +++ /dev/null @@ -1,151 +0,0 @@ ---- -id: change-2026-08-30-ai-native-sdlc-migration -kind: change -schema: 2 -status: verified -risk: medium -owner: repository maintainers -approvers: user via the 2026-08-30 implementation request -approved_at: 2026-08-30 -created: 2026-08-30 -updated: 2026-08-31 -source: current user request to apply the ai-native-sdlc skill and remove the existing lifecycle -inputs: docs/sdlc/workflow.md and the repository CI, review, release, and history mechanisms -outputs: docs/sdlc/evals/ai-native-sdlc-gates.md and the replacement repository lifecycle contract -scope: AGENTS.md, README.md, docs/sdlc, script/verify/sdlc.ts, script/verify/checks.test.ts, .github -next_trigger: the authorized direct push lands on origin/main -verification_mode: owner -verified_by: repository maintainers -verified_at: 2026-08-30 ---- - -# Replace the repository lifecycle with the AI-native SDLC contract - -## Intent - -The user explicitly requested applying the current `ai-native-sdlc` rules to CodeTwo and removing -the existing lifecycle implementation. The repository already has useful CI, release, and -historical change evidence, but its checker mainly validates document shape. It can accept a -material build accompanied by an unaccepted Artifact and does not deterministically close -verification, release, Incident, or Eval gates. - -The outcome is one project-specific lifecycle that preserves real historical evidence, removes the -superseded bootstrap implementation, and makes advancement depend on observable evidence and human -authorization rather than prose alone. Product behavior and external production state are out of -scope. - -## Spec - -- `docs/sdlc/workflow.md` remains the only repository lifecycle authority; issues, ADRs, designs, - PRs, CI, releases, and monitoring remain authoritative for their own facts and are linked. -- Low-risk work uses one compact change Artifact. Higher-risk work links supporting ADR, design, - migration, test, and release evidence from their existing authoritative locations without - creating global parallel spec or plan registries. -- Material branch changes cannot pass with a draft, in-review, blocked, or superseded change. -- Verified or later changes require all acceptance criteria checked, an explicit verification - verdict, actual evidence, and a residual-risk statement. -- Release readiness requires named approval, a target, and rollback evidence; a released state also - requires immutable release identity and smoke evidence. -- Resolved Incidents link a follow-up change and regression Eval, or record a concrete blocker. -- Active Evals come from a real task or Incident and record a repeatable result. -- The previous bootstrap Artifact and its legacy-workflow Eval are removed after their durable - repository facts are incorporated into the replacement workflow and regression case. - -### Acceptance criteria - -- [x] AC-1: Root instructions, README, PR handoff, CI, and release automation point to one workflow. -- [x] AC-2: The superseded bootstrap Artifact and legacy Eval no longer exist; product change history is - retained. -- [x] AC-3: A project-native Bun/TypeScript checker enforces lifecycle shape, readiness, verification, - release, Incident, Eval, single-source, and branch-diff gates. -- [x] AC-4: An isolated dry-run proves both the accepted path and representative failure paths. -- [x] AC-5: The live repository passes the replacement checker and focused tests. -- [x] AC-6: External branch protection and production monitoring are reported accurately rather than - claimed as repository-controlled capabilities. - -## Decision and gates - -The current user request accepts the migration Intent and the stated removal constraint. It does -not authorize creating or merging a pull request, changing GitHub branch protection, dispatching a -release, deploying documentation, or mutating production. Those remain human or external Gates. - -## Plan - -1. Inventory the existing Artifact, CI, review, release, Incident, and Eval mechanisms. -2. Replace the workflow and templates while preserving authoritative historical evidence. -3. Strengthen the Bun/TypeScript checker and its isolated failure-path tests. -4. Remove the superseded bootstrap/Eval pair and add a real regression Eval for the new contract. -5. Run focused tests, live validation, workflow parsing, and diff checks; record actual results. - -## Build - -The migration replaces [`workflow.md`](../../workflow.md), all three templates, the Bun/TypeScript -checker and tests, the PR handoff, the `SDLC contract` workflow, and the versioned macOS release -Gate. Root instructions and README point to the same authority. Existing product change Artifacts -were migrated to the common metadata and explicit verification verdict without rewriting their -historical evidence. - -The superseded `2026-08-29-sdlc-bootstrap.md` and `legacy-workflow-single-source.md` were removed. -Their durable single-source and failure-path intent is replaced by the current workflow and -[`ai-native-sdlc-gates.md`](../../evals/ai-native-sdlc-gates.md). No product code or UI changed. - -## Verification - -Verdict: verified. - -### Acceptance evidence - -- AC-1: PASS — [`workflow.md`](../../workflow.md), [`AGENTS.md`](../../../../AGENTS.md), and repository CI/release workflows point to the same lifecycle. -- AC-2: PASS — `git diff --check` and exact-path checks confirmed the superseded bootstrap Artifact and legacy Eval were absent while product history remained. -- AC-3: PASS — [`check-sdlc.ts`](../../../../script/verify/sdlc.ts) and [`check-sdlc.test.ts`](../../../../script/verify/checks.test.ts) implement the recorded Gates. -- AC-4: PASS — `bun script/verify/sdlc.ts --base e3744874` passed in an isolated committed temporary worktree. -- AC-5: PASS — `bun test script/verify/checks.test.ts` passed 10 tests with 24 assertions and `bun script/verify/sdlc.ts` returned `[sdlc] contract valid`. -- AC-6: PASS — [`workflow.md`](../../workflow.md) records branch protection and production monitoring as external or blocked rather than repository-controlled. - -Observed on 2026-08-30 from the working tree rebased onto `e3744874`: - -- `bun test script/verify/checks.test.ts` passed all 10 tests with 24 assertions. It covers valid - execution, superseded sources, - duplicate ids, missing sections, acceptance closure, verification verdict/risk, release approval, - release identity/smoke, Incident feedback, Eval provenance/result, Artifact-only draft review, - premature implementation, and missing-Artifact branch changes. -- `bun script/verify/sdlc.ts` returned `[sdlc] contract valid`. -- An isolated temporary worktree applied the complete repository diff, committed it over base - `e3744874`, and passed `bun script/verify/sdlc.ts --base e3744874`; the worktree was removed after - its dry-run. -- `bun script/verify/sdlc.ts --release-change change-2026-08-30-ai-native-sdlc-migration` failed as - expected because this change is not `ready-to-release`. -- The first Ruby YAML command used an unavailable `Psych.safe_load_file`; a follow-up parsed both - workflows before mistakenly including the Markdown PR template. The corrected Ruby 2.6-compatible - command parsed `.github/workflows/sdlc.yml` and `.github/workflows/release-macos.yml` successfully. -- Exact file checks confirmed the superseded bootstrap and legacy Eval paths are absent. -- `git diff --check` passed. No product UI or runtime behavior changed, so rendered-window, Rust, - packaging, and production smoke checks are not applicable to this repository-process change. -- The first push was rejected non-fast-forward because PR #183 landed four commits after the - pre-push fetch. The migration rebased cleanly onto merge commit `e3744874`; its two new change - Artifacts were preserved and migrated to the replacement contract before retrying. - -Residual risk: no PR exists, so hosted CI and the external branch-protection requirement have not -been observed for this diff. Repository-owned production monitoring and automatic Incident -creation remain blocked as documented in the workflow. The checker validates deterministic fields, -links, states, and evidence markers; human review still judges whether the evidence is sufficient -for the actual risk. - -## Review and release - -Approval: the user authorized a direct push to `main` on 2026-08-30 after requiring the checker and -tests to use the repository's Bun/TypeScript stack instead of Python; that condition is satisfied. -Release target: none. This repository-process change does not itself ship a product release. -Rollback: revert the repository migration diff to restore the previous contract and checker. -No release: no versioned package, deployment, or production mutation is part of this change. - -## Feedback - -The active regression is -[`eval-ai-native-sdlc-gates`](../../evals/ai-native-sdlc-gates.md). New lifecycle enforcement changes -rerun that focused Eval. Real operational failures must create an Incident, a follow-up Intent, and -an Incident-derived Eval instead of expanding this generic case without provenance. - -During handoff, the user rejected introducing Python into a repository with no Python source files. -The checker and all lifecycle tests, commands, documentation, and CI hooks were therefore migrated -to Bun/TypeScript before any commit or push. diff --git a/docs/sdlc/changes/2026-08-30-ai-native-sdlc-migration/intent.md b/docs/sdlc/changes/2026-08-30-ai-native-sdlc-migration/intent.md new file mode 100644 index 00000000..d15cda9e --- /dev/null +++ b/docs/sdlc/changes/2026-08-30-ai-native-sdlc-migration/intent.md @@ -0,0 +1,59 @@ +--- +id: "2026-08-30-ai-native-sdlc-migration" +stage: intent +schema: 3 +status: accepted +owner: repository maintainers +created: 2026-08-30 +source: current user request to apply the ai-native-sdlc skill and remove the existing lifecycle +risk: medium +approved_by: "userthe 2026-08-30 implementation request" +approved_at: "2026-08-30" +--- + +# Intent: Replace the repository lifecycle with the AI-native SDLC contract + +## Problem + +The user explicitly requested applying the current `ai-native-sdlc` rules to CodeTwo and removing +the existing lifecycle implementation. The repository already has useful CI, release, and +historical change evidence, but its checker mainly validates document shape. It can accept a +material build accompanied by an unaccepted Artifact and does not deterministically close +verification, release, Incident, or Eval gates. + +The outcome is one project-specific lifecycle that preserves real historical evidence, removes the +superseded bootstrap implementation, and makes advancement depend on observable evidence and human +authorization rather than prose alone. Product behavior and external production state are out of +scope. + +## Proposed outcome + +The user explicitly requested applying the current `ai-native-sdlc` rules to CodeTwo and removing + +## Affected users and systems + +Migrated from legacy change.md. + +## Constraints + +The current user request accepts the migration Intent and the stated removal constraint. It does +not authorize creating or merging a pull request, changing GitHub branch protection, dispatching a +release, deploying documentation, or mutating production. Those remain human or external Gates. + +## Out of scope + +Not recorded in the legacy single-file Artifact. + +## Success signals + +See Spec acceptance criteria. + +## Open questions + +None recorded in migration. + +## Decision + +The current user request accepts the migration Intent and the stated removal constraint. It does +not authorize creating or merging a pull request, changing GitHub branch protection, dispatching a +release, deploying documentation, or mutating production. Those remain human or external Gates. diff --git a/docs/sdlc/changes/2026-08-30-ai-native-sdlc-migration/plan.md b/docs/sdlc/changes/2026-08-30-ai-native-sdlc-migration/plan.md new file mode 100644 index 00000000..c395219c --- /dev/null +++ b/docs/sdlc/changes/2026-08-30-ai-native-sdlc-migration/plan.md @@ -0,0 +1,61 @@ +--- +id: "2026-08-30-ai-native-sdlc-migration" +stage: plan +schema: 3 +status: accepted +owner: repository maintainers +created: 2026-08-30 +based_on: spec.md +risk: medium +scope: AGENTS.md, README.md, docs/sdlc, script/verify/sdlc.ts, script/verify/checks.test.ts, .github +approved_by: "userthe 2026-08-30 implementation request" +approved_at: "2026-08-30" +--- + +# Plan: Replace the repository lifecycle with the AI-native SDLC contract + +## Files and ownership + +AGENTS.md, README.md, docs/sdlc, script/verify/sdlc.ts, script/verify/checks.test.ts, .github + +## Order of work + +1. Inventory the existing Artifact, CI, review, release, Incident, and Eval mechanisms. +2. Replace the workflow and templates while preserving authoritative historical evidence. +3. Strengthen the Bun/TypeScript checker and its isolated failure-path tests. +4. Remove the superseded bootstrap/Eval pair and add a real regression Eval for the new contract. +5. Run focused tests, live validation, workflow parsing, and diff checks; record actual results. + +## Test-first proof + +See legacy Verification section. + +## Visual or integration proof + +See legacy Verification section. + +## Risks and mitigations + +See legacy Decision and gates. + +## Rollback + +See legacy Review and release. + +## Deviations + +The migration replaces [`workflow.md`](../../workflow.md), all three templates, the Bun/TypeScript +checker and tests, the PR handoff, the `SDLC contract` workflow, and the versioned macOS release +Gate. Root instructions and README point to the same authority. Existing product change Artifacts +were migrated to the common metadata and explicit verification verdict without rewriting their +historical evidence. + +The superseded `2026-08-29-sdlc-bootstrap.md` and `legacy-workflow-single-source.md` were removed. +Their durable single-source and failure-path intent is replaced by the current workflow and +[`ai-native-sdlc-gates.md`](../../evals/ai-native-sdlc-gates.md). No product code or UI changed. + +## Decision + +The current user request accepts the migration Intent and the stated removal constraint. It does +not authorize creating or merging a pull request, changing GitHub branch protection, dispatching a +release, deploying documentation, or mutating production. Those remain human or external Gates. diff --git a/docs/sdlc/changes/2026-08-30-ai-native-sdlc-migration/spec.md b/docs/sdlc/changes/2026-08-30-ai-native-sdlc-migration/spec.md new file mode 100644 index 00000000..63382a43 --- /dev/null +++ b/docs/sdlc/changes/2026-08-30-ai-native-sdlc-migration/spec.md @@ -0,0 +1,71 @@ +--- +id: "2026-08-30-ai-native-sdlc-migration" +stage: spec +schema: 3 +status: accepted +owner: repository maintainers +created: 2026-08-30 +based_on: intent.md +risk: medium +approved_by: "userthe 2026-08-30 implementation request" +approved_at: "2026-08-30" +--- + +# Spec: Replace the repository lifecycle with the AI-native SDLC contract + +## Requirements + +- `docs/sdlc/workflow.md` remains the only repository lifecycle authority; issues, ADRs, designs, + PRs, CI, releases, and monitoring remain authoritative for their own facts and are linked. +- Low-risk work uses one compact change Artifact. Higher-risk work links supporting ADR, design, + migration, test, and release evidence from their existing authoritative locations without + creating global parallel spec or plan registries. +- Material branch changes cannot pass with a draft, in-review, blocked, or superseded change. +- Verified or later changes require all acceptance criteria checked, an explicit verification + verdict, actual evidence, and a residual-risk statement. +- Release readiness requires named approval, a target, and rollback evidence; a released state also + requires immutable release identity and smoke evidence. +- Resolved Incidents link a follow-up change and regression Eval, or record a concrete blocker. +- Active Evals come from a real task or Incident and record a repeatable result. +- The previous bootstrap Artifact and its legacy-workflow Eval are removed after their durable + repository facts are incorporated into the replacement workflow and regression case. + +## User experience + +Not separately recorded in legacy change.md. + +## Technical design + +See Requirements and legacy Git history. + +## Security and privacy + +See migrated Decision and gates. + +## Alternatives and non-goals + +Not separately recorded in legacy change.md. + +## Areas of concern + +The current user request accepts the migration Intent and the stated removal constraint. It does +not authorize creating or merging a pull request, changing GitHub branch protection, dispatching a +release, deploying documentation, or mutating production. Those remain human or external Gates. + +## Acceptance criteria + +- [x] AC-1: Root instructions, README, PR handoff, CI, and release automation point to one workflow. +- [x] AC-2: The superseded bootstrap Artifact and legacy Eval no longer exist; product change history is + retained. +- [x] AC-3: A project-native Bun/TypeScript checker enforces lifecycle shape, readiness, verification, + release, Incident, Eval, single-source, and branch-diff gates. +- [x] AC-4: An isolated dry-run proves both the accepted path and representative failure paths. +- [x] AC-5: The live repository passes the replacement checker and focused tests. +- [x] AC-6: External branch protection and production monitoring are reported accurately rather than + claimed as repository-controlled capabilities. + +## Decision + +The current user request accepts the migration Intent and the stated removal constraint. It does +not authorize creating or merging a pull request, changing GitHub branch protection, dispatching a +release, deploying documentation, or mutating production. Those remain human or external Gates. diff --git a/docs/sdlc/changes/2026-08-30-ai-native-sdlc-migration/verification.md b/docs/sdlc/changes/2026-08-30-ai-native-sdlc-migration/verification.md new file mode 100644 index 00000000..014473c3 --- /dev/null +++ b/docs/sdlc/changes/2026-08-30-ai-native-sdlc-migration/verification.md @@ -0,0 +1,136 @@ +--- +id: "2026-08-30-ai-native-sdlc-migration" +stage: verification +schema: 3 +status: passed +owner: repository maintainers +created: 2026-08-30 +based_on: plan.md +commit: "" +verification_mode: owner +verified_by: "repository maintainers" +verified_at: "2026-08-30" +release_target: none. This repository-process change does not itself ship a product release +release_identity: "" +--- + +# Verification: Replace the repository lifecycle with the AI-native SDLC contract + +## Automated checks + +Verdict: verified. + +### Acceptance evidence + +- AC-1: PASS — [`workflow.md`](../../workflow.md), [`AGENTS.md`](../../../../AGENTS.md), and repository CI/release workflows point to the same lifecycle. +- AC-2: PASS — `git diff --check` and exact-path checks confirmed the superseded bootstrap Artifact and legacy Eval were absent while product history remained. +- AC-3: PASS — [`check-sdlc.ts`](../../../../script/verify/sdlc.ts) and [`check-sdlc.test.ts`](../../../../script/verify/checks.test.ts) implement the recorded Gates. +- AC-4: PASS — `bun script/verify/sdlc.ts --base e3744874` passed in an isolated committed temporary worktree. +- AC-5: PASS — `bun test script/verify/checks.test.ts` passed 10 tests with 24 assertions and `bun script/verify/sdlc.ts` returned `[sdlc] contract valid`. +- AC-6: PASS — [`workflow.md`](../../workflow.md) records branch protection and production monitoring as external or blocked rather than repository-controlled. + +Observed on 2026-08-30 from the working tree rebased onto `e3744874`: + +- `bun test script/verify/checks.test.ts` passed all 10 tests with 24 assertions. It covers valid + execution, superseded sources, + duplicate ids, missing sections, acceptance closure, verification verdict/risk, release approval, + release identity/smoke, Incident feedback, Eval provenance/result, Artifact-only draft review, + premature implementation, and missing-Artifact branch changes. +- `bun script/verify/sdlc.ts` returned `[sdlc] contract valid`. +- An isolated temporary worktree applied the complete repository diff, committed it over base + `e3744874`, and passed `bun script/verify/sdlc.ts --base e3744874`; the worktree was removed after + its dry-run. +- `bun script/verify/sdlc.ts --release-change change-2026-08-30-ai-native-sdlc-migration` failed as + expected because this change is not `ready-to-release`. +- The first Ruby YAML command used an unavailable `Psych.safe_load_file`; a follow-up parsed both + workflows before mistakenly including the Markdown PR template. The corrected Ruby 2.6-compatible + command parsed `.github/workflows/sdlc.yml` and `.github/workflows/release-macos.yml` successfully. +- Exact file checks confirmed the superseded bootstrap and legacy Eval paths are absent. +- `git diff --check` passed. No product UI or runtime behavior changed, so rendered-window, Rust, + packaging, and production smoke checks are not applicable to this repository-process change. +- The first push was rejected non-fast-forward because PR #183 landed four commits after the + pre-push fetch. The migration rebased cleanly onto merge commit `e3744874`; its two new change + Artifacts were preserved and migrated to the replacement contract before retrying. + +Residual risk: no PR exists, so hosted CI and the external branch-protection requirement have not +been observed for this diff. Repository-owned production monitoring and automatic Incident +creation remain blocked as documented in the workflow. The checker validates deterministic fields, +links, states, and evidence markers; human review still judges whether the evidence is sufficient +for the actual risk. + +## Behavioral evidence + +Verdict: verified. + +### Acceptance evidence + +- AC-1: PASS — [`workflow.md`](../../workflow.md), [`AGENTS.md`](../../../../AGENTS.md), and repository CI/release workflows point to the same lifecycle. +- AC-2: PASS — `git diff --check` and exact-path checks confirmed the superseded bootstrap Artifact and legacy Eval were absent while product history remained. +- AC-3: PASS — [`check-sdlc.ts`](../../../../script/verify/sdlc.ts) and [`check-sdlc.test.ts`](../../../../script/verify/checks.test.ts) implement the recorded Gates. +- AC-4: PASS — `bun script/verify/sdlc.ts --base e3744874` passed in an isolated committed temporary worktree. +- AC-5: PASS — `bun test script/verify/checks.test.ts` passed 10 tests with 24 assertions and `bun script/verify/sdlc.ts` returned `[sdlc] contract valid`. +- AC-6: PASS — [`workflow.md`](../../workflow.md) records branch protection and production monitoring as external or blocked rather than repository-controlled. + +Observed on 2026-08-30 from the working tree rebased onto `e3744874`: + +- `bun test script/verify/checks.test.ts` passed all 10 tests with 24 assertions. It covers valid + execution, superseded sources, + duplicate ids, missing sections, acceptance closure, verification verdict/risk, release approval, + release identity/smoke, Incident feedback, Eval provenance/result, Artifact-only draft review, + premature implementation, and missing-Artifact branch changes. +- `bun script/verify/sdlc.ts` returned `[sdlc] contract valid`. +- An isolated temporary worktree applied the complete repository diff, committed it over base + `e3744874`, and passed `bun script/verify/sdlc.ts --base e3744874`; the worktree was removed after + its dry-run. +- `bun script/verify/sdlc.ts --release-change change-2026-08-30-ai-native-sdlc-migration` failed as + expected because this change is not `ready-to-release`. +- The first Ruby YAML command used an unavailable `Psych.safe_load_file`; a follow-up parsed both + workflows before mistakenly including the Markdown PR template. The corrected Ruby 2.6-compatible + command parsed `.github/workflows/sdlc.yml` and `.github/workflows/release-macos.yml` successfully. +- Exact file checks confirmed the superseded bootstrap and legacy Eval paths are absent. +- `git diff --check` passed. No product UI or runtime behavior changed, so rendered-window, Rust, + packaging, and production smoke checks are not applicable to this repository-process change. +- The first push was rejected non-fast-forward because PR #183 landed four commits after the + pre-push fetch. The migration rebased cleanly onto merge commit `e3744874`; its two new change + Artifacts were preserved and migrated to the replacement contract before retrying. + +Residual risk: no PR exists, so hosted CI and the external branch-protection requirement have not +been observed for this diff. Repository-owned production monitoring and automatic Incident +creation remain blocked as documented in the workflow. The checker validates deterministic fields, +links, states, and evidence markers; human review still judges whether the evidence is sufficient +for the actual risk. + +## Visual evidence + +See bundle evidence/ when present. + +## Security and privacy evidence + +Not separately recorded unless present in legacy Verification. + +## Deviations and residual risk + +Residual risk: no PR exists, so hosted CI and the external branch-protection requirement have not + +## Verdict + +Verdict: verified.. + +## Review and release + +Approval: the user authorized a direct push to `main` on 2026-08-30 after requiring the checker and +tests to use the repository's Bun/TypeScript stack instead of Python; that condition is satisfied. +Release target: none. This repository-process change does not itself ship a product release. +Rollback: revert the repository migration diff to restore the previous contract and checker. +No release: no versioned package, deployment, or production mutation is part of this change. + +## Feedback + +The active regression is +[`eval-ai-native-sdlc-gates`](../../evals/ai-native-sdlc-gates.md). New lifecycle enforcement changes +rerun that focused Eval. Real operational failures must create an Incident, a follow-up Intent, and +an Incident-derived Eval instead of expanding this generic case without provenance. + +During handoff, the user rejected introducing Python into a repository with no Python source files. +The checker and all lifecycle tests, commands, documentation, and CI hooks were therefore migrated +to Bun/TypeScript before any commit or push. diff --git a/docs/sdlc/changes/2026-08-30-desktop-pet-pointer-interaction/change.md b/docs/sdlc/changes/2026-08-30-desktop-pet-pointer-interaction/change.md deleted file mode 100644 index 0533129c..00000000 --- a/docs/sdlc/changes/2026-08-30-desktop-pet-pointer-interaction/change.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -id: change-2026-08-30-desktop-pet-pointer-interaction -kind: change -schema: 2 -status: verified -risk: low -owner: codex -approvers: "#decision-and-gates" -approved_at: 2026-08-30 -created: 2026-08-30 -updated: 2026-08-31 -source: "#intent" -inputs: "#spec" -outputs: "#build" -scope: apps/desktop -next_trigger: pull request checks and repository merge -verification_mode: owner -verified_by: codex -verified_at: 2026-08-30 ---- - -# Restore desktop pet pointer interaction - -## Intent - -The user reported on 2026-08-30 that the floating pet cannot be used as a real independent desktop -companion because clicking it produces no response. The desktop pet must remain outside the -conversation surface while accepting the pointer interaction already exposed by its renderer. - -## Spec - -Keep the existing single floating companion and active-task state projection. Make its native -desktop window accept pointer input so the mascot greeting and controls can receive events. Do not -add a second lifecycle or change pet selection and task-state semantics. - -### Acceptance criteria - -- [x] AC-1: The pet remains in its dedicated desktop window rather than the conversation transcript. -- [x] AC-2: The native pet surface accepts pointer input instead of passing it through to windows below. -- [x] AC-3: Clicking the mascot visibly switches it to the waving animation. -- [x] AC-4: Existing voice, hide, selection, size, and active-task animation paths remain wired. -- [x] AC-5: Focused interaction, host-contract, type, SDLC, and real-window checks pass. - -## Decision and gates - -Intent and observable acceptance come directly from the user's 2026-08-30 report. No permission to -create a PR, merge, publish, or release is implied. - -## Plan - -First lock the rendered greeting and native input configuration into focused regression checks. -Then remove the conflicting native pass-through option, run the narrow checks, and verify the -packaged desktop surface in an isolated development profile if the current launcher supports the -required profile contract. Rollback is the inverse one-line native window option change. - -## Build - -The desktop pet `BrowserWindow` now disables Electrobun input pass-through while preserving the -existing transparent, non-activating, always-on-top companion window. The focused renderer test -locks the click-to-wave behavior, and the host contract prevents input pass-through from being -reintroduced. - -## Verification - -- Before the fix, `bun test tests/petSettings.test.tsx tests/pluginComponentPolicyContract.test.ts` - produced 8 passes and 1 failure: the host still contained `passthrough: true`. After the fix, the - same command produced 9 passes and 0 failures. The existing renderer harness still emits - non-failing React `act(...)` warnings. -- `./script/dev/run.sh --verify` completed renderer, design, type, native Core, and package - checks using the machine's existing Xcode beta / macOS 26.5 SDK compatibility setup. The design - check reported 0 new violations; legacy debt remains 657. -- Real macOS-window verification used the built `C2-dev.app` with an isolated data directory while - leaving the user's existing CodeTwo process running. After the main window was minimized, the - separate `C2 Dev Pet` window remained visible at `views://main/desktop-pet.html`; the first mascot - click visibly rendered the waving frame. -- The isolated Core later exited with `Resource temporarily unavailable (os error 35)`, so this - evidence does not claim that the whole development runtime stayed healthy. The Electrobun pet - window and its renderer remained available long enough to reproduce and verify the input fix. -- `bun script/verify/sdlc.ts` reported `[sdlc] contract valid`; task-scoped - `git diff --check` passed. - -Verdict: verified. - -### Acceptance evidence - -- AC-1: PASS — the recorded real-window check kept the mascot in the dedicated Electrobun pet window. Evidence: `Verification record above`. -- AC-2: PASS — `./script/dev/run.sh --verify` and host-contract inspection confirmed pointer passthrough was disabled for the pet surface. -- AC-3: PASS — the recorded click interaction visibly switched the mascot to its waving animation. Evidence: `Verification record above`. -- AC-4: PASS — `bun test tests/petSettings.test.tsx tests/pluginComponentPolicyContract.test.ts` preserved the existing pet paths. -- AC-5: PASS — focused tests, host verification, `bun script/verify/sdlc.ts`, real-window inspection, and `git diff --check` passed. - -Residual risk: the isolated Core later exited with the recorded `os error 35`; evidence verifies -the pet window interaction, not long-running Core health or a versioned product release. - -## Review and release - -The user explicitly authorized creating and merging the repository pull request on 2026-08-30. -[PR #181](https://github.com/IchenDEV/codeTwo/pull/181) carries the implementation; repository -integration remains pending until its checks pass and the merge is observed. - -## Feedback - -The repaired surface responded on the first click; no second click or main-window activation was -required. No additional pet-selection or active-task animation regression was observed in the -focused checks. diff --git a/docs/sdlc/changes/2026-08-30-desktop-pet-pointer-interaction/intent.md b/docs/sdlc/changes/2026-08-30-desktop-pet-pointer-interaction/intent.md new file mode 100644 index 00000000..8c48d48f --- /dev/null +++ b/docs/sdlc/changes/2026-08-30-desktop-pet-pointer-interaction/intent.md @@ -0,0 +1,50 @@ +--- +id: "2026-08-30-desktop-pet-pointer-interaction" +stage: intent +schema: 3 +status: accepted +owner: codex +created: 2026-08-30 +source: #intent +risk: low +approved_by: "#decision-and-gates" +approved_at: "2026-08-30" +--- + +# Intent: Restore desktop pet pointer interaction + +## Problem + +The user reported on 2026-08-30 that the floating pet cannot be used as a real independent desktop +companion because clicking it produces no response. The desktop pet must remain outside the +conversation surface while accepting the pointer interaction already exposed by its renderer. + +## Proposed outcome + +The user reported on 2026-08-30 that the floating pet cannot be used as a real independent desktop + +## Affected users and systems + +Migrated from legacy change.md. + +## Constraints + +Intent and observable acceptance come directly from the user's 2026-08-30 report. No permission to +create a PR, merge, publish, or release is implied. + +## Out of scope + +Not recorded in the legacy single-file Artifact. + +## Success signals + +See Spec acceptance criteria. + +## Open questions + +None recorded in migration. + +## Decision + +Intent and observable acceptance come directly from the user's 2026-08-30 report. No permission to +create a PR, merge, publish, or release is implied. diff --git a/docs/sdlc/changes/2026-08-30-desktop-pet-pointer-interaction/plan.md b/docs/sdlc/changes/2026-08-30-desktop-pet-pointer-interaction/plan.md new file mode 100644 index 00000000..f9013d03 --- /dev/null +++ b/docs/sdlc/changes/2026-08-30-desktop-pet-pointer-interaction/plan.md @@ -0,0 +1,54 @@ +--- +id: "2026-08-30-desktop-pet-pointer-interaction" +stage: plan +schema: 3 +status: accepted +owner: codex +created: 2026-08-30 +based_on: spec.md +risk: low +scope: apps/desktop +approved_by: "#decision-and-gates" +approved_at: "2026-08-30" +--- + +# Plan: Restore desktop pet pointer interaction + +## Files and ownership + +apps/desktop + +## Order of work + +First lock the rendered greeting and native input configuration into focused regression checks. +Then remove the conflicting native pass-through option, run the narrow checks, and verify the +packaged desktop surface in an isolated development profile if the current launcher supports the +required profile contract. Rollback is the inverse one-line native window option change. + +## Test-first proof + +See legacy Verification section. + +## Visual or integration proof + +See legacy Verification section. + +## Risks and mitigations + +See legacy Decision and gates. + +## Rollback + +See legacy Review and release. + +## Deviations + +The desktop pet `BrowserWindow` now disables Electrobun input pass-through while preserving the +existing transparent, non-activating, always-on-top companion window. The focused renderer test +locks the click-to-wave behavior, and the host contract prevents input pass-through from being +reintroduced. + +## Decision + +Intent and observable acceptance come directly from the user's 2026-08-30 report. No permission to +create a PR, merge, publish, or release is implied. diff --git a/docs/sdlc/changes/2026-08-30-desktop-pet-pointer-interaction/spec.md b/docs/sdlc/changes/2026-08-30-desktop-pet-pointer-interaction/spec.md new file mode 100644 index 00000000..057fd696 --- /dev/null +++ b/docs/sdlc/changes/2026-08-30-desktop-pet-pointer-interaction/spec.md @@ -0,0 +1,54 @@ +--- +id: "2026-08-30-desktop-pet-pointer-interaction" +stage: spec +schema: 3 +status: accepted +owner: codex +created: 2026-08-30 +based_on: intent.md +risk: low +approved_by: "#decision-and-gates" +approved_at: "2026-08-30" +--- + +# Spec: Restore desktop pet pointer interaction + +## Requirements + +Keep the existing single floating companion and active-task state projection. Make its native +desktop window accept pointer input so the mascot greeting and controls can receive events. Do not +add a second lifecycle or change pet selection and task-state semantics. + +## User experience + +Not separately recorded in legacy change.md. + +## Technical design + +See Requirements and legacy Git history. + +## Security and privacy + +See migrated Decision and gates. + +## Alternatives and non-goals + +Not separately recorded in legacy change.md. + +## Areas of concern + +Intent and observable acceptance come directly from the user's 2026-08-30 report. No permission to +create a PR, merge, publish, or release is implied. + +## Acceptance criteria + +- [x] AC-1: The pet remains in its dedicated desktop window rather than the conversation transcript. +- [x] AC-2: The native pet surface accepts pointer input instead of passing it through to windows below. +- [x] AC-3: Clicking the mascot visibly switches it to the waving animation. +- [x] AC-4: Existing voice, hide, selection, size, and active-task animation paths remain wired. +- [x] AC-5: Focused interaction, host-contract, type, SDLC, and real-window checks pass. + +## Decision + +Intent and observable acceptance come directly from the user's 2026-08-30 report. No permission to +create a PR, merge, publish, or release is implied. diff --git a/docs/sdlc/changes/2026-08-30-desktop-pet-pointer-interaction/verification.md b/docs/sdlc/changes/2026-08-30-desktop-pet-pointer-interaction/verification.md new file mode 100644 index 00000000..ac2b577d --- /dev/null +++ b/docs/sdlc/changes/2026-08-30-desktop-pet-pointer-interaction/verification.md @@ -0,0 +1,109 @@ +--- +id: "2026-08-30-desktop-pet-pointer-interaction" +stage: verification +schema: 3 +status: passed +owner: codex +created: 2026-08-30 +based_on: plan.md +commit: "" +verification_mode: owner +verified_by: "codex" +verified_at: "2026-08-30" +release_target: none +release_identity: "" +--- + +# Verification: Restore desktop pet pointer interaction + +## Automated checks + +- Before the fix, `bun test tests/petSettings.test.tsx tests/pluginComponentPolicyContract.test.ts` + produced 8 passes and 1 failure: the host still contained `passthrough: true`. After the fix, the + same command produced 9 passes and 0 failures. The existing renderer harness still emits + non-failing React `act(...)` warnings. +- `./script/dev/run.sh --verify` completed renderer, design, type, native Core, and package + checks using the machine's existing Xcode beta / macOS 26.5 SDK compatibility setup. The design + check reported 0 new violations; legacy debt remains 657. +- Real macOS-window verification used the built `C2-dev.app` with an isolated data directory while + leaving the user's existing CodeTwo process running. After the main window was minimized, the + separate `C2 Dev Pet` window remained visible at `views://main/desktop-pet.html`; the first mascot + click visibly rendered the waving frame. +- The isolated Core later exited with `Resource temporarily unavailable (os error 35)`, so this + evidence does not claim that the whole development runtime stayed healthy. The Electrobun pet + window and its renderer remained available long enough to reproduce and verify the input fix. +- `bun script/verify/sdlc.ts` reported `[sdlc] contract valid`; task-scoped + `git diff --check` passed. + +Verdict: verified. + +### Acceptance evidence + +- AC-1: PASS — the recorded real-window check kept the mascot in the dedicated Electrobun pet window. Evidence: `Verification record above`. +- AC-2: PASS — `./script/dev/run.sh --verify` and host-contract inspection confirmed pointer passthrough was disabled for the pet surface. +- AC-3: PASS — the recorded click interaction visibly switched the mascot to its waving animation. Evidence: `Verification record above`. +- AC-4: PASS — `bun test tests/petSettings.test.tsx tests/pluginComponentPolicyContract.test.ts` preserved the existing pet paths. +- AC-5: PASS — focused tests, host verification, `bun script/verify/sdlc.ts`, real-window inspection, and `git diff --check` passed. + +Residual risk: the isolated Core later exited with the recorded `os error 35`; evidence verifies +the pet window interaction, not long-running Core health or a versioned product release. + +## Behavioral evidence + +- Before the fix, `bun test tests/petSettings.test.tsx tests/pluginComponentPolicyContract.test.ts` + produced 8 passes and 1 failure: the host still contained `passthrough: true`. After the fix, the + same command produced 9 passes and 0 failures. The existing renderer harness still emits + non-failing React `act(...)` warnings. +- `./script/dev/run.sh --verify` completed renderer, design, type, native Core, and package + checks using the machine's existing Xcode beta / macOS 26.5 SDK compatibility setup. The design + check reported 0 new violations; legacy debt remains 657. +- Real macOS-window verification used the built `C2-dev.app` with an isolated data directory while + leaving the user's existing CodeTwo process running. After the main window was minimized, the + separate `C2 Dev Pet` window remained visible at `views://main/desktop-pet.html`; the first mascot + click visibly rendered the waving frame. +- The isolated Core later exited with `Resource temporarily unavailable (os error 35)`, so this + evidence does not claim that the whole development runtime stayed healthy. The Electrobun pet + window and its renderer remained available long enough to reproduce and verify the input fix. +- `bun script/verify/sdlc.ts` reported `[sdlc] contract valid`; task-scoped + `git diff --check` passed. + +Verdict: verified. + +### Acceptance evidence + +- AC-1: PASS — the recorded real-window check kept the mascot in the dedicated Electrobun pet window. Evidence: `Verification record above`. +- AC-2: PASS — `./script/dev/run.sh --verify` and host-contract inspection confirmed pointer passthrough was disabled for the pet surface. +- AC-3: PASS — the recorded click interaction visibly switched the mascot to its waving animation. Evidence: `Verification record above`. +- AC-4: PASS — `bun test tests/petSettings.test.tsx tests/pluginComponentPolicyContract.test.ts` preserved the existing pet paths. +- AC-5: PASS — focused tests, host verification, `bun script/verify/sdlc.ts`, real-window inspection, and `git diff --check` passed. + +Residual risk: the isolated Core later exited with the recorded `os error 35`; evidence verifies +the pet window interaction, not long-running Core health or a versioned product release. + +## Visual evidence + +See bundle evidence/ when present. + +## Security and privacy evidence + +Not separately recorded unless present in legacy Verification. + +## Deviations and residual risk + +Residual risk: the isolated Core later exited with the recorded `os error 35`; evidence verifies + +## Verdict + +Verdict: verified.. + +## Review and release + +The user explicitly authorized creating and merging the repository pull request on 2026-08-30. +[PR #181](https://github.com/IchenDEV/codeTwo/pull/181) carries the implementation; repository +integration remains pending until its checks pass and the merge is observed. + +## Feedback + +The repaired surface responded on the first click; no second click or main-window activation was +required. No additional pet-selection or active-task animation regression was observed in the +focused checks. diff --git a/docs/sdlc/changes/2026-08-30-desktop-pet-remove-voice-control/change.md b/docs/sdlc/changes/2026-08-30-desktop-pet-remove-voice-control/change.md deleted file mode 100644 index 90122ba3..00000000 --- a/docs/sdlc/changes/2026-08-30-desktop-pet-remove-voice-control/change.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -id: change-2026-08-30-desktop-pet-remove-voice-control -kind: change -schema: 2 -status: verified -risk: low -owner: codex -approvers: "#decision-and-gates" -approved_at: 2026-08-30 -created: 2026-08-30 -updated: 2026-08-31 -source: "#intent" -inputs: "#spec" -outputs: "#build" -scope: apps/desktop -next_trigger: pull request checks and repository merge -verification_mode: owner -verified_by: codex -verified_at: 2026-08-30 ---- - -# Remove the desktop pet voice control - -## Intent - -The user reported on 2026-08-30 that the microphone below the floating desktop pet is unnecessary -and misleading because it cannot provide the streaming voice experience implied by the control. -Remove that entry point instead of presenting an incomplete interaction. - -## Spec - -Keep composer voice input unchanged. Remove the microphone from the independent desktop pet and -delete only the pet-specific voice props, state, event, and RPC path that become unreachable. Keep -the mascot greeting, activity animation, drag handle, and hide control intact. - -### Acceptance criteria - -- [x] AC-1: The independent desktop pet renders no microphone or voice-input control. -- [x] AC-2: Pet state and native RPC no longer carry a pet-only voice path. -- [x] AC-3: Composer voice input remains wired to its existing component-policy gate. -- [x] AC-4: Greeting, activity animation, drag handle, and hide control remain intact. -- [x] AC-5: Focused interaction, host-contract, type, SDLC, diff, and real-window checks pass. - -## Decision and gates - -Intent and acceptance come directly from the user's 2026-08-30 follow-up. No permission to create -a PR, merge, publish, or release is implied. - -## Plan - -Lock the absence of the pet voice bridge into the existing component-policy contract, remove the -now-unused pet-specific plumbing from renderer through native RPC, then verify the focused tests -and built desktop pet window. Rollback is the inverse source change. - -## Build - -`CodeTwoPet` now owns only its mascot greeting and hide control. The desktop pet bridge and native -RPC state no longer carry voice enablement or voice text, while the composer continues to use the -existing `voice.composer` policy gate and `VoiceButton`. - -## Verification - -- Before implementation, `bun test tests/pluginComponentPolicyContract.test.ts` produced 2 passes - and 1 failure because the app still projected `voiceEnabled` into both the composer and desktop - pet. After implementation, - `bun test tests/petSettings.test.tsx tests/pluginComponentPolicyContract.test.ts` produced 9 - passes and 0 failures. The existing renderer harness still emits non-failing React `act(...)` - warnings. -- `bunx tsc --noEmit` passed. -- `./script/dev/run.sh --verify` completed design, type, renderer, native, and package checks. - The design check reported 0 new violations; legacy debt remains 657. -- The built app ran with a fresh isolated data directory while the user's existing CodeTwo process - remained running. With the main window minimized, the independent `C2 Dev Pet` window at - `views://main/desktop-pet.html` exposed only `Say hello to the pet` and `Hide desktop pet`; no - microphone or voice control appeared in the accessibility tree or rendered screenshot. -- Clicking the mascot in that real window still rendered its waving frame. -- `bun script/verify/sdlc.ts` reported `[sdlc] contract valid`; task-scoped - `git diff --check` passed. - -Verdict: verified. - -### Acceptance evidence - -- AC-1: PASS — the recorded real-window inspection found no microphone or pet voice-input control. Evidence: `Verification record above`. -- AC-2: PASS — focused host-contract inspection confirmed the pet-only voice state and RPC path were removed. Evidence: `Verification record above`. -- AC-3: PASS — `bun test tests/pluginComponentPolicyContract.test.ts` retained composer voice policy wiring. -- AC-4: PASS — `bun test tests/petSettings.test.tsx tests/pluginComponentPolicyContract.test.ts` retained greeting, animation, drag, and hide behavior. -- AC-5: PASS — focused tests, `bunx tsc --noEmit`, `./script/dev/run.sh --verify`, `bun script/verify/sdlc.ts`, real-window inspection, and `git diff --check` passed. - -Residual risk: validation used an isolated development build; no versioned product release or -public distribution was requested or observed. - -## Review and release - -The user explicitly authorized creating and merging the repository pull request on 2026-08-30. -[PR #181](https://github.com/IchenDEV/codeTwo/pull/181) carries the implementation; repository -integration remains pending until its checks pass and the merge is observed. - -## Feedback - -The pet now presents only interactions it can fulfill. Composer voice input remains outside this -change. diff --git a/docs/sdlc/changes/2026-08-30-desktop-pet-remove-voice-control/intent.md b/docs/sdlc/changes/2026-08-30-desktop-pet-remove-voice-control/intent.md new file mode 100644 index 00000000..a871f081 --- /dev/null +++ b/docs/sdlc/changes/2026-08-30-desktop-pet-remove-voice-control/intent.md @@ -0,0 +1,50 @@ +--- +id: "2026-08-30-desktop-pet-remove-voice-control" +stage: intent +schema: 3 +status: accepted +owner: codex +created: 2026-08-30 +source: #intent +risk: low +approved_by: "#decision-and-gates" +approved_at: "2026-08-30" +--- + +# Intent: Remove the desktop pet voice control + +## Problem + +The user reported on 2026-08-30 that the microphone below the floating desktop pet is unnecessary +and misleading because it cannot provide the streaming voice experience implied by the control. +Remove that entry point instead of presenting an incomplete interaction. + +## Proposed outcome + +The user reported on 2026-08-30 that the microphone below the floating desktop pet is unnecessary + +## Affected users and systems + +Migrated from legacy change.md. + +## Constraints + +Intent and acceptance come directly from the user's 2026-08-30 follow-up. No permission to create +a PR, merge, publish, or release is implied. + +## Out of scope + +Not recorded in the legacy single-file Artifact. + +## Success signals + +See Spec acceptance criteria. + +## Open questions + +None recorded in migration. + +## Decision + +Intent and acceptance come directly from the user's 2026-08-30 follow-up. No permission to create +a PR, merge, publish, or release is implied. diff --git a/docs/sdlc/changes/2026-08-30-desktop-pet-remove-voice-control/plan.md b/docs/sdlc/changes/2026-08-30-desktop-pet-remove-voice-control/plan.md new file mode 100644 index 00000000..5d6cd07c --- /dev/null +++ b/docs/sdlc/changes/2026-08-30-desktop-pet-remove-voice-control/plan.md @@ -0,0 +1,52 @@ +--- +id: "2026-08-30-desktop-pet-remove-voice-control" +stage: plan +schema: 3 +status: accepted +owner: codex +created: 2026-08-30 +based_on: spec.md +risk: low +scope: apps/desktop +approved_by: "#decision-and-gates" +approved_at: "2026-08-30" +--- + +# Plan: Remove the desktop pet voice control + +## Files and ownership + +apps/desktop + +## Order of work + +Lock the absence of the pet voice bridge into the existing component-policy contract, remove the +now-unused pet-specific plumbing from renderer through native RPC, then verify the focused tests +and built desktop pet window. Rollback is the inverse source change. + +## Test-first proof + +See legacy Verification section. + +## Visual or integration proof + +See legacy Verification section. + +## Risks and mitigations + +See legacy Decision and gates. + +## Rollback + +See legacy Review and release. + +## Deviations + +`CodeTwoPet` now owns only its mascot greeting and hide control. The desktop pet bridge and native +RPC state no longer carry voice enablement or voice text, while the composer continues to use the +existing `voice.composer` policy gate and `VoiceButton`. + +## Decision + +Intent and acceptance come directly from the user's 2026-08-30 follow-up. No permission to create +a PR, merge, publish, or release is implied. diff --git a/docs/sdlc/changes/2026-08-30-desktop-pet-remove-voice-control/spec.md b/docs/sdlc/changes/2026-08-30-desktop-pet-remove-voice-control/spec.md new file mode 100644 index 00000000..c6c0e0c1 --- /dev/null +++ b/docs/sdlc/changes/2026-08-30-desktop-pet-remove-voice-control/spec.md @@ -0,0 +1,54 @@ +--- +id: "2026-08-30-desktop-pet-remove-voice-control" +stage: spec +schema: 3 +status: accepted +owner: codex +created: 2026-08-30 +based_on: intent.md +risk: low +approved_by: "#decision-and-gates" +approved_at: "2026-08-30" +--- + +# Spec: Remove the desktop pet voice control + +## Requirements + +Keep composer voice input unchanged. Remove the microphone from the independent desktop pet and +delete only the pet-specific voice props, state, event, and RPC path that become unreachable. Keep +the mascot greeting, activity animation, drag handle, and hide control intact. + +## User experience + +Not separately recorded in legacy change.md. + +## Technical design + +See Requirements and legacy Git history. + +## Security and privacy + +See migrated Decision and gates. + +## Alternatives and non-goals + +Not separately recorded in legacy change.md. + +## Areas of concern + +Intent and acceptance come directly from the user's 2026-08-30 follow-up. No permission to create +a PR, merge, publish, or release is implied. + +## Acceptance criteria + +- [x] AC-1: The independent desktop pet renders no microphone or voice-input control. +- [x] AC-2: Pet state and native RPC no longer carry a pet-only voice path. +- [x] AC-3: Composer voice input remains wired to its existing component-policy gate. +- [x] AC-4: Greeting, activity animation, drag handle, and hide control remain intact. +- [x] AC-5: Focused interaction, host-contract, type, SDLC, diff, and real-window checks pass. + +## Decision + +Intent and acceptance come directly from the user's 2026-08-30 follow-up. No permission to create +a PR, merge, publish, or release is implied. diff --git a/docs/sdlc/changes/2026-08-30-desktop-pet-remove-voice-control/verification.md b/docs/sdlc/changes/2026-08-30-desktop-pet-remove-voice-control/verification.md new file mode 100644 index 00000000..e1a6e68e --- /dev/null +++ b/docs/sdlc/changes/2026-08-30-desktop-pet-remove-voice-control/verification.md @@ -0,0 +1,108 @@ +--- +id: "2026-08-30-desktop-pet-remove-voice-control" +stage: verification +schema: 3 +status: passed +owner: codex +created: 2026-08-30 +based_on: plan.md +commit: "" +verification_mode: owner +verified_by: "codex" +verified_at: "2026-08-30" +release_target: none +release_identity: "" +--- + +# Verification: Remove the desktop pet voice control + +## Automated checks + +- Before implementation, `bun test tests/pluginComponentPolicyContract.test.ts` produced 2 passes + and 1 failure because the app still projected `voiceEnabled` into both the composer and desktop + pet. After implementation, + `bun test tests/petSettings.test.tsx tests/pluginComponentPolicyContract.test.ts` produced 9 + passes and 0 failures. The existing renderer harness still emits non-failing React `act(...)` + warnings. +- `bunx tsc --noEmit` passed. +- `./script/dev/run.sh --verify` completed design, type, renderer, native, and package checks. + The design check reported 0 new violations; legacy debt remains 657. +- The built app ran with a fresh isolated data directory while the user's existing CodeTwo process + remained running. With the main window minimized, the independent `C2 Dev Pet` window at + `views://main/desktop-pet.html` exposed only `Say hello to the pet` and `Hide desktop pet`; no + microphone or voice control appeared in the accessibility tree or rendered screenshot. +- Clicking the mascot in that real window still rendered its waving frame. +- `bun script/verify/sdlc.ts` reported `[sdlc] contract valid`; task-scoped + `git diff --check` passed. + +Verdict: verified. + +### Acceptance evidence + +- AC-1: PASS — the recorded real-window inspection found no microphone or pet voice-input control. Evidence: `Verification record above`. +- AC-2: PASS — focused host-contract inspection confirmed the pet-only voice state and RPC path were removed. Evidence: `Verification record above`. +- AC-3: PASS — `bun test tests/pluginComponentPolicyContract.test.ts` retained composer voice policy wiring. +- AC-4: PASS — `bun test tests/petSettings.test.tsx tests/pluginComponentPolicyContract.test.ts` retained greeting, animation, drag, and hide behavior. +- AC-5: PASS — focused tests, `bunx tsc --noEmit`, `./script/dev/run.sh --verify`, `bun script/verify/sdlc.ts`, real-window inspection, and `git diff --check` passed. + +Residual risk: validation used an isolated development build; no versioned product release or +public distribution was requested or observed. + +## Behavioral evidence + +- Before implementation, `bun test tests/pluginComponentPolicyContract.test.ts` produced 2 passes + and 1 failure because the app still projected `voiceEnabled` into both the composer and desktop + pet. After implementation, + `bun test tests/petSettings.test.tsx tests/pluginComponentPolicyContract.test.ts` produced 9 + passes and 0 failures. The existing renderer harness still emits non-failing React `act(...)` + warnings. +- `bunx tsc --noEmit` passed. +- `./script/dev/run.sh --verify` completed design, type, renderer, native, and package checks. + The design check reported 0 new violations; legacy debt remains 657. +- The built app ran with a fresh isolated data directory while the user's existing CodeTwo process + remained running. With the main window minimized, the independent `C2 Dev Pet` window at + `views://main/desktop-pet.html` exposed only `Say hello to the pet` and `Hide desktop pet`; no + microphone or voice control appeared in the accessibility tree or rendered screenshot. +- Clicking the mascot in that real window still rendered its waving frame. +- `bun script/verify/sdlc.ts` reported `[sdlc] contract valid`; task-scoped + `git diff --check` passed. + +Verdict: verified. + +### Acceptance evidence + +- AC-1: PASS — the recorded real-window inspection found no microphone or pet voice-input control. Evidence: `Verification record above`. +- AC-2: PASS — focused host-contract inspection confirmed the pet-only voice state and RPC path were removed. Evidence: `Verification record above`. +- AC-3: PASS — `bun test tests/pluginComponentPolicyContract.test.ts` retained composer voice policy wiring. +- AC-4: PASS — `bun test tests/petSettings.test.tsx tests/pluginComponentPolicyContract.test.ts` retained greeting, animation, drag, and hide behavior. +- AC-5: PASS — focused tests, `bunx tsc --noEmit`, `./script/dev/run.sh --verify`, `bun script/verify/sdlc.ts`, real-window inspection, and `git diff --check` passed. + +Residual risk: validation used an isolated development build; no versioned product release or +public distribution was requested or observed. + +## Visual evidence + +See bundle evidence/ when present. + +## Security and privacy evidence + +Not separately recorded unless present in legacy Verification. + +## Deviations and residual risk + +Residual risk: validation used an isolated development build; no versioned product release or + +## Verdict + +Verdict: verified.. + +## Review and release + +The user explicitly authorized creating and merging the repository pull request on 2026-08-30. +[PR #181](https://github.com/IchenDEV/codeTwo/pull/181) carries the implementation; repository +integration remains pending until its checks pass and the merge is observed. + +## Feedback + +The pet now presents only interactions it can fulfill. Composer voice input remains outside this +change. diff --git a/docs/sdlc/changes/2026-08-30-feishu-document-component/change.md b/docs/sdlc/changes/2026-08-30-feishu-document-component/change.md deleted file mode 100644 index 52676519..00000000 --- a/docs/sdlc/changes/2026-08-30-feishu-document-component/change.md +++ /dev/null @@ -1,159 +0,0 @@ ---- -id: change-2026-08-30-feishu-document-component -kind: change -schema: 2 -status: executing -risk: high -owner: codex -approvers: chenli -approved_at: 2026-08-30 -created: 2026-08-30 -updated: 2026-08-31 -source: user request in this task, "云文档的渲染考虑使用飞书云文档组件或者说是 iframe 来接" -inputs: the official Feishu Docs Component, the community Feishu Runtime, and the C2 document detail surface -outputs: an official-component-first Feishu document viewer with a readable Markdown fallback -scope: community/plugins/feishu, apps/desktop -next_trigger: resolve the official SDK's missing mount callback in Electrobun WebKit, then rerun the live component matrix -verification_mode: independent -verified_by: pending -verified_at: pending ---- - -# Embed Feishu documents with the official component - -## Intent - -The current C2 document detail fetches raw document text and renders it as Markdown. The user asked -whether the official Feishu Docs Component or a direct iframe should become the richer document -surface. The preferred path must preserve Feishu permissions and live collaboration without exposing -the app secret or user token to the renderer, while retaining a usable result when the component -cannot load. - -## Spec - -C2 uses the current official `DocComponentSdk` as the primary renderer for Feishu document URLs. -The community Runtime obtains the user-identity JSAPI ticket and computes a one-use signature for -the exact C2 page URL; only the signed component-auth payload and public SDK URL cross the connector -boundary. The app secret, access token, and JSAPI ticket remain Runtime-only. The component is -destroyed when the document changes or the view unmounts, retries authorization once after an auth -failure, receives the current C2 theme and a bounded height, and exposes localized loading and -failure states. - -A normal Feishu document URL is not placed directly in an iframe. Direct framing would rely on the -document site's login cookies and framing policy, while the official component owns its internal -iframe, permission handshake, supported document URLs, error model, and collaboration behavior. -When the SDK, signature, WebView environment, network, or document type is unsupported, C2 keeps the -existing OpenAPI-to-Markdown rendering visible and offers the canonical Feishu link. - -### Acceptance criteria - -- [x] AC-1: Official current Feishu documentation, SDK identity, authorization flow, iframe boundary, and - user-versus-app capabilities are recorded in a source-linked research note. -- [x] AC-2: A selected cloud document attempts the official component first and never embeds the ordinary - Feishu document page as a raw iframe. -- [x] AC-3: Component authorization uses the user identity and one-use signature while secrets, access - tokens, and JSAPI tickets remain inside the community Runtime. -- [x] AC-4: The SDK lifecycle handles mount, one authorization retry, document/theme changes, destruction, - and bounded sizing without leaving duplicate iframes. -- [x] AC-5: Markdown remains a readable fallback, including a localized explanation and an open-in-Feishu - action when the richer renderer is unavailable. -- [x] AC-6: Focused Runtime and rendered tests, renderer build, diff checks, and the SDLC contract pass; - any unexercised real Feishu/WebView boundary is stated as residual risk. - -## Decision and gates - -The user's direct implementation request approves this Intent and Spec, with chenli as the named -approver. The user later authorized PR #185 and explicitly authorized its merge on 2026-08-31. -No publication, deployment, permission approval, or release is authorized. - -## Plan - -Verify the current official component contract, add a narrowly scoped signed-auth connector -operation, isolate the vendor SDK lifecycle in one C2 component, and replace the document detail's -single Markdown body with component-first progressive enhancement. Rollback removes the signed-auth -operation and component host while restoring the existing Markdown-only document detail. - -## Build - -The community adapter is now version 0.5.0. Its Runtime exposes one -`document.component` connector operation, accepts only HTTPS Feishu/Lark tenant URLs supported by -SDK 1.0.13, obtains the user JSAPI ticket, signs the exact loopback page URL, and serves a short-lived -isolated component page. The page loads the pinned official SDK, constrains duplicate chrome, follows -the active theme, reports lifecycle events to C2, and destroys the SDK instance on page teardown. - -C2 now attempts that component before showing the existing OpenAPI/Markdown document body. It -retries an authentication failure once with a forced user-token/ticket refresh, then shows a -localized Markdown fallback with Retry and Open in Feishu. The adapter does not pass its app secret, -user token, refresh token, or raw ticket to the page. Base and Slides remain on their existing C2 -renderers because this SDK version rejects those URL shapes. - -## Verification - -Verdict: implementation, packaged installation, user authorization, and authenticated fallback smoke -pass. The official live component still times out in Electrobun WebKit and remains an open residual. - -- `npm run check` in `dsh-feishu-docs`: 69 tests passed, typecheck passed, and the minified CodeTwo - bundle rebuilt at 1.9 MiB, below C2's 4 MiB per-file installation limit. -- `CODETWO_RUNTIME_BUNDLE=1 npx vitest run tests/codetwo-runtime.spec.ts`: 11 tests passed against - the actual packaged CommonJS bundle, including signature-host isolation, secret non-disclosure, - forced token/ticket refresh, and marketplace/manifest version alignment. -- The native `plugins.install_marketplace` operation atomically replaced the existing installed - Feishu bundle with version 0.5.0 while retaining its enabled and trusted state. -- `bun test` over the eight affected desktop suites: 93 tests passed with 777 expectations, - including component-first rendering, Markdown fallback, one auth retry, connector slots, flat - resource groups, and the shared titlebar/rail contract. -- `bunx tsc --noEmit`: passed. -- `bun run build:renderer`: passed; the design-system gate reported no new violations and the - production renderer built successfully. -- `cargo build --release --bin codetwo-desktop-host`: passed after using the generated Ghostty - pkg-config artifact to bypass the checkout's known unchanged Zig/libc++ `INFINITY` failure; the - temporary feature toggle was reverted and no Ghostty source change remains. -- `bun scripts/validate-plugin.ts /codetwo`: manifest 0.5.0 valid with one - connector. -- `git diff --check` and `bun script/check-sdlc.ts`: passed before the final Artifact update and are - rerun at handoff. -- The packaged a685 `C2-dev.app` launched with one Core owner on the default data directory. Native - Computer Use verified that Contacts, Docs, and Base appear as flat collapsible groups directly in - the main rail, with no duplicate search field or plugin-specific nested sidebar. The official - Feishu launcher opened successfully, the user approved the one-click app permission and event - configuration, and Feishu reported `配置成功`. The subsequent user OAuth page was reached and - enumerated ten requested capabilities before the final grant. The user then approved that grant; - C2 immediately loaded 8 recent contacts/groups and 36 cloud documents from the authorized account. -- Two different real Feishu cloud documents were opened in the packaged Electrobun WebView. For both, - C2 created a signed short-lived loopback component page, the page returned HTTP 200, and the pinned - official SDK returned HTTP 200. Neither page produced a mount success or error callback before the - 20-second product timeout, so C2 correctly replaced the live surface with the latest readable - OpenAPI/Markdown preview and kept Retry and Open in Feishu available. A speculative WebKit - `MessageEvent.source` relaxation did not change this result and was reverted. - -### Acceptance evidence - -- AC-1: PASS — `Verification record above` preserves the original passing evidence. -- AC-2: PASS — `Verification record above` preserves the original passing evidence. -- AC-3: PASS — `Verification record above` preserves the original passing evidence. -- AC-4: PASS — `Verification record above` preserves the original passing evidence. -- AC-5: PASS — `Verification record above` preserves the original passing evidence. -- AC-6: PASS — `Verification record above` preserves the original passing evidence. - -Residual risk: the official SDK's live mount is not yet proven inside Electrobun WebKit. The -component-first boundary and no-blank-screen fallback are verified, but the SDK's missing callback -needs a separate WebKit/vendor-capability investigation before claiming live editing or collaboration. -Docs, Wiki, and Sheets should then be repeated in light and dark themes; this handoff makes no claim -that the live component itself succeeded. - -## Review and release - -Approval: implementation approved by chenli through the user request. -Merge approval: PR #185 explicitly approved for merge by chenli on 2026-08-31. -Release target: none. -Release identity: not applicable until released. -Smoke evidence: not applicable until released. -Rollback: described in the Plan. -No release: no release was requested. - -## Feedback - -The official component is the supported integration contract. A normal Feishu document URL may -happen to load in an iframe, but it does not provide the component's signed session, feature -configuration, error model, or documented collaboration boundary and is therefore not a product -fallback. diff --git a/docs/sdlc/changes/2026-08-30-feishu-document-component/intent.md b/docs/sdlc/changes/2026-08-30-feishu-document-component/intent.md new file mode 100644 index 00000000..a9e396c5 --- /dev/null +++ b/docs/sdlc/changes/2026-08-30-feishu-document-component/intent.md @@ -0,0 +1,54 @@ +--- +id: "2026-08-30-feishu-document-component" +stage: intent +schema: 3 +status: accepted +owner: codex +created: 2026-08-30 +source: user request in this task, "云文档的渲染考虑使用飞书云文档组件或者说是 iframe 来接" +risk: high +approved_by: "chenli" +approved_at: "2026-08-30" +--- + +# Intent: Embed Feishu documents with the official component + +## Problem + +The current C2 document detail fetches raw document text and renders it as Markdown. The user asked +whether the official Feishu Docs Component or a direct iframe should become the richer document +surface. The preferred path must preserve Feishu permissions and live collaboration without exposing +the app secret or user token to the renderer, while retaining a usable result when the component +cannot load. + +## Proposed outcome + +The current C2 document detail fetches raw document text and renders it as Markdown. The user asked + +## Affected users and systems + +Migrated from legacy change.md. + +## Constraints + +The user's direct implementation request approves this Intent and Spec, with chenli as the named +approver. The user later authorized PR #185 and explicitly authorized its merge on 2026-08-31. +No publication, deployment, permission approval, or release is authorized. + +## Out of scope + +Not recorded in the legacy single-file Artifact. + +## Success signals + +See Spec acceptance criteria. + +## Open questions + +None recorded in migration. + +## Decision + +The user's direct implementation request approves this Intent and Spec, with chenli as the named +approver. The user later authorized PR #185 and explicitly authorized its merge on 2026-08-31. +No publication, deployment, permission approval, or release is authorized. diff --git a/docs/sdlc/changes/2026-08-30-feishu-document-component/plan.md b/docs/sdlc/changes/2026-08-30-feishu-document-component/plan.md new file mode 100644 index 00000000..bf56e5c0 --- /dev/null +++ b/docs/sdlc/changes/2026-08-30-feishu-document-component/plan.md @@ -0,0 +1,62 @@ +--- +id: "2026-08-30-feishu-document-component" +stage: plan +schema: 3 +status: accepted +owner: codex +created: 2026-08-30 +based_on: spec.md +risk: high +scope: community/plugins/feishu, apps/desktop +approved_by: "chenli" +approved_at: "2026-08-30" +--- + +# Plan: Embed Feishu documents with the official component + +## Files and ownership + +community/plugins/feishu, apps/desktop + +## Order of work + +Verify the current official component contract, add a narrowly scoped signed-auth connector +operation, isolate the vendor SDK lifecycle in one C2 component, and replace the document detail's +single Markdown body with component-first progressive enhancement. Rollback removes the signed-auth +operation and component host while restoring the existing Markdown-only document detail. + +## Test-first proof + +See legacy Verification section. + +## Visual or integration proof + +See legacy Verification section. + +## Risks and mitigations + +See legacy Decision and gates. + +## Rollback + +See legacy Review and release. + +## Deviations + +The community adapter is now version 0.5.0. Its Runtime exposes one +`document.component` connector operation, accepts only HTTPS Feishu/Lark tenant URLs supported by +SDK 1.0.13, obtains the user JSAPI ticket, signs the exact loopback page URL, and serves a short-lived +isolated component page. The page loads the pinned official SDK, constrains duplicate chrome, follows +the active theme, reports lifecycle events to C2, and destroys the SDK instance on page teardown. + +C2 now attempts that component before showing the existing OpenAPI/Markdown document body. It +retries an authentication failure once with a forced user-token/ticket refresh, then shows a +localized Markdown fallback with Retry and Open in Feishu. The adapter does not pass its app secret, +user token, refresh token, or raw ticket to the page. Base and Slides remain on their existing C2 +renderers because this SDK version rejects those URL shapes. + +## Decision + +The user's direct implementation request approves this Intent and Spec, with chenli as the named +approver. The user later authorized PR #185 and explicitly authorized its merge on 2026-08-31. +No publication, deployment, permission approval, or release is authorized. diff --git a/docs/sdlc/changes/2026-08-30-feishu-document-component/spec.md b/docs/sdlc/changes/2026-08-30-feishu-document-component/spec.md new file mode 100644 index 00000000..d5d12c7f --- /dev/null +++ b/docs/sdlc/changes/2026-08-30-feishu-document-component/spec.md @@ -0,0 +1,73 @@ +--- +id: "2026-08-30-feishu-document-component" +stage: spec +schema: 3 +status: accepted +owner: codex +created: 2026-08-30 +based_on: intent.md +risk: high +approved_by: "chenli" +approved_at: "2026-08-30" +--- + +# Spec: Embed Feishu documents with the official component + +## Requirements + +C2 uses the current official `DocComponentSdk` as the primary renderer for Feishu document URLs. +The community Runtime obtains the user-identity JSAPI ticket and computes a one-use signature for +the exact C2 page URL; only the signed component-auth payload and public SDK URL cross the connector +boundary. The app secret, access token, and JSAPI ticket remain Runtime-only. The component is +destroyed when the document changes or the view unmounts, retries authorization once after an auth +failure, receives the current C2 theme and a bounded height, and exposes localized loading and +failure states. + +A normal Feishu document URL is not placed directly in an iframe. Direct framing would rely on the +document site's login cookies and framing policy, while the official component owns its internal +iframe, permission handshake, supported document URLs, error model, and collaboration behavior. +When the SDK, signature, WebView environment, network, or document type is unsupported, C2 keeps the +existing OpenAPI-to-Markdown rendering visible and offers the canonical Feishu link. + +## User experience + +Not separately recorded in legacy change.md. + +## Technical design + +See Requirements and legacy Git history. + +## Security and privacy + +See migrated Decision and gates. + +## Alternatives and non-goals + +Not separately recorded in legacy change.md. + +## Areas of concern + +The user's direct implementation request approves this Intent and Spec, with chenli as the named +approver. The user later authorized PR #185 and explicitly authorized its merge on 2026-08-31. +No publication, deployment, permission approval, or release is authorized. + +## Acceptance criteria + +- [x] AC-1: Official current Feishu documentation, SDK identity, authorization flow, iframe boundary, and + user-versus-app capabilities are recorded in a source-linked research note. +- [x] AC-2: A selected cloud document attempts the official component first and never embeds the ordinary + Feishu document page as a raw iframe. +- [x] AC-3: Component authorization uses the user identity and one-use signature while secrets, access + tokens, and JSAPI tickets remain inside the community Runtime. +- [x] AC-4: The SDK lifecycle handles mount, one authorization retry, document/theme changes, destruction, + and bounded sizing without leaving duplicate iframes. +- [x] AC-5: Markdown remains a readable fallback, including a localized explanation and an open-in-Feishu + action when the richer renderer is unavailable. +- [x] AC-6: Focused Runtime and rendered tests, renderer build, diff checks, and the SDLC contract pass; + any unexercised real Feishu/WebView boundary is stated as residual risk. + +## Decision + +The user's direct implementation request approves this Intent and Spec, with chenli as the named +approver. The user later authorized PR #185 and explicitly authorized its merge on 2026-08-31. +No publication, deployment, permission approval, or release is authorized. diff --git a/docs/sdlc/changes/2026-08-30-feishu-document-component/verification.md b/docs/sdlc/changes/2026-08-30-feishu-document-component/verification.md new file mode 100644 index 00000000..4359d201 --- /dev/null +++ b/docs/sdlc/changes/2026-08-30-feishu-document-component/verification.md @@ -0,0 +1,158 @@ +--- +id: "2026-08-30-feishu-document-component" +stage: verification +schema: 3 +status: pending +owner: codex +created: 2026-08-30 +based_on: plan.md +commit: "" +verification_mode: independent +verified_by: "" +verified_at: "" +release_target: none +release_identity: "not applicable until released." +--- + +# Verification: Embed Feishu documents with the official component + +## Automated checks + +Verdict: implementation, packaged installation, user authorization, and authenticated fallback smoke +pass. The official live component still times out in Electrobun WebKit and remains an open residual. + +- `npm run check` in `dsh-feishu-docs`: 69 tests passed, typecheck passed, and the minified CodeTwo + bundle rebuilt at 1.9 MiB, below C2's 4 MiB per-file installation limit. +- `CODETWO_RUNTIME_BUNDLE=1 npx vitest run tests/codetwo-runtime.spec.ts`: 11 tests passed against + the actual packaged CommonJS bundle, including signature-host isolation, secret non-disclosure, + forced token/ticket refresh, and marketplace/manifest version alignment. +- The native `plugins.install_marketplace` operation atomically replaced the existing installed + Feishu bundle with version 0.5.0 while retaining its enabled and trusted state. +- `bun test` over the eight affected desktop suites: 93 tests passed with 777 expectations, + including component-first rendering, Markdown fallback, one auth retry, connector slots, flat + resource groups, and the shared titlebar/rail contract. +- `bunx tsc --noEmit`: passed. +- `bun run build:renderer`: passed; the design-system gate reported no new violations and the + production renderer built successfully. +- `cargo build --release --bin codetwo-desktop-host`: passed after using the generated Ghostty + pkg-config artifact to bypass the checkout's known unchanged Zig/libc++ `INFINITY` failure; the + temporary feature toggle was reverted and no Ghostty source change remains. +- `bun scripts/validate-plugin.ts /codetwo`: manifest 0.5.0 valid with one + connector. +- `git diff --check` and `bun script/check-sdlc.ts`: passed before the final Artifact update and are + rerun at handoff. +- The packaged a685 `C2-dev.app` launched with one Core owner on the default data directory. Native + Computer Use verified that Contacts, Docs, and Base appear as flat collapsible groups directly in + the main rail, with no duplicate search field or plugin-specific nested sidebar. The official + Feishu launcher opened successfully, the user approved the one-click app permission and event + configuration, and Feishu reported `配置成功`. The subsequent user OAuth page was reached and + enumerated ten requested capabilities before the final grant. The user then approved that grant; + C2 immediately loaded 8 recent contacts/groups and 36 cloud documents from the authorized account. +- Two different real Feishu cloud documents were opened in the packaged Electrobun WebView. For both, + C2 created a signed short-lived loopback component page, the page returned HTTP 200, and the pinned + official SDK returned HTTP 200. Neither page produced a mount success or error callback before the + 20-second product timeout, so C2 correctly replaced the live surface with the latest readable + OpenAPI/Markdown preview and kept Retry and Open in Feishu available. A speculative WebKit + `MessageEvent.source` relaxation did not change this result and was reverted. + +### Acceptance evidence + +- AC-1: PASS — `Verification record above` preserves the original passing evidence. +- AC-2: PASS — `Verification record above` preserves the original passing evidence. +- AC-3: PASS — `Verification record above` preserves the original passing evidence. +- AC-4: PASS — `Verification record above` preserves the original passing evidence. +- AC-5: PASS — `Verification record above` preserves the original passing evidence. +- AC-6: PASS — `Verification record above` preserves the original passing evidence. + +Residual risk: the official SDK's live mount is not yet proven inside Electrobun WebKit. The +component-first boundary and no-blank-screen fallback are verified, but the SDK's missing callback +needs a separate WebKit/vendor-capability investigation before claiming live editing or collaboration. +Docs, Wiki, and Sheets should then be repeated in light and dark themes; this handoff makes no claim +that the live component itself succeeded. + +## Behavioral evidence + +Verdict: implementation, packaged installation, user authorization, and authenticated fallback smoke +pass. The official live component still times out in Electrobun WebKit and remains an open residual. + +- `npm run check` in `dsh-feishu-docs`: 69 tests passed, typecheck passed, and the minified CodeTwo + bundle rebuilt at 1.9 MiB, below C2's 4 MiB per-file installation limit. +- `CODETWO_RUNTIME_BUNDLE=1 npx vitest run tests/codetwo-runtime.spec.ts`: 11 tests passed against + the actual packaged CommonJS bundle, including signature-host isolation, secret non-disclosure, + forced token/ticket refresh, and marketplace/manifest version alignment. +- The native `plugins.install_marketplace` operation atomically replaced the existing installed + Feishu bundle with version 0.5.0 while retaining its enabled and trusted state. +- `bun test` over the eight affected desktop suites: 93 tests passed with 777 expectations, + including component-first rendering, Markdown fallback, one auth retry, connector slots, flat + resource groups, and the shared titlebar/rail contract. +- `bunx tsc --noEmit`: passed. +- `bun run build:renderer`: passed; the design-system gate reported no new violations and the + production renderer built successfully. +- `cargo build --release --bin codetwo-desktop-host`: passed after using the generated Ghostty + pkg-config artifact to bypass the checkout's known unchanged Zig/libc++ `INFINITY` failure; the + temporary feature toggle was reverted and no Ghostty source change remains. +- `bun scripts/validate-plugin.ts /codetwo`: manifest 0.5.0 valid with one + connector. +- `git diff --check` and `bun script/check-sdlc.ts`: passed before the final Artifact update and are + rerun at handoff. +- The packaged a685 `C2-dev.app` launched with one Core owner on the default data directory. Native + Computer Use verified that Contacts, Docs, and Base appear as flat collapsible groups directly in + the main rail, with no duplicate search field or plugin-specific nested sidebar. The official + Feishu launcher opened successfully, the user approved the one-click app permission and event + configuration, and Feishu reported `配置成功`. The subsequent user OAuth page was reached and + enumerated ten requested capabilities before the final grant. The user then approved that grant; + C2 immediately loaded 8 recent contacts/groups and 36 cloud documents from the authorized account. +- Two different real Feishu cloud documents were opened in the packaged Electrobun WebView. For both, + C2 created a signed short-lived loopback component page, the page returned HTTP 200, and the pinned + official SDK returned HTTP 200. Neither page produced a mount success or error callback before the + 20-second product timeout, so C2 correctly replaced the live surface with the latest readable + OpenAPI/Markdown preview and kept Retry and Open in Feishu available. A speculative WebKit + `MessageEvent.source` relaxation did not change this result and was reverted. + +### Acceptance evidence + +- AC-1: PASS — `Verification record above` preserves the original passing evidence. +- AC-2: PASS — `Verification record above` preserves the original passing evidence. +- AC-3: PASS — `Verification record above` preserves the original passing evidence. +- AC-4: PASS — `Verification record above` preserves the original passing evidence. +- AC-5: PASS — `Verification record above` preserves the original passing evidence. +- AC-6: PASS — `Verification record above` preserves the original passing evidence. + +Residual risk: the official SDK's live mount is not yet proven inside Electrobun WebKit. The +component-first boundary and no-blank-screen fallback are verified, but the SDK's missing callback +needs a separate WebKit/vendor-capability investigation before claiming live editing or collaboration. +Docs, Wiki, and Sheets should then be repeated in light and dark themes; this handoff makes no claim +that the live component itself succeeded. + +## Visual evidence + +See bundle evidence/ when present. + +## Security and privacy evidence + +Not separately recorded unless present in legacy Verification. + +## Deviations and residual risk + +Residual risk: the official SDK's live mount is not yet proven inside Electrobun WebKit. The + +## Verdict + +Verdict: implementation, packaged installation, user authorization, and authenticated fallback smoke. + +## Review and release + +Approval: implementation approved by chenli through the user request. +Merge approval: PR #185 explicitly approved for merge by chenli on 2026-08-31. +Release target: none. +Release identity: not applicable until released. +Smoke evidence: not applicable until released. +Rollback: described in the Plan. +No release: no release was requested. + +## Feedback + +The official component is the supported integration contract. A normal Feishu document URL may +happen to load in an iframe, but it does not provide the component's signed session, feature +configuration, error model, or documented collaboration boundary and is therefore not a product +fallback. diff --git a/docs/sdlc/changes/2026-08-30-feishu-document-markdown/change.md b/docs/sdlc/changes/2026-08-30-feishu-document-markdown/change.md deleted file mode 100644 index bb27f948..00000000 --- a/docs/sdlc/changes/2026-08-30-feishu-document-markdown/change.md +++ /dev/null @@ -1,142 +0,0 @@ ---- -id: change-2026-08-30-feishu-document-markdown -kind: change -schema: 2 -status: executing -risk: medium -owner: codex -approvers: chenli -approved_at: 2026-08-30 -created: 2026-08-30 -updated: 2026-08-31 -source: user request in this task, "文档 md 渲染" -inputs: existing Feishu document detail and shared Markdown renderer -outputs: Feishu document, conversation, emoji, and reaction rendering with focused tests and rendered evidence -scope: community/plugins/feishu, apps/desktop -next_trigger: focused Feishu content rendering verification completes -verification_mode: owner -verified_by: pending -verified_at: pending ---- - -# Render Feishu documents and conversations - -## Intent - -The user requested that Feishu document content render as Markdown, then explicitly extended the -request to conversation, emoji, and reaction rendering. Document and message bodies should show -readable semantic content rather than raw Markdown delimiters or technical placeholders, and -reaction totals should remain visually attached to the message they annotate. The change affects -the read-only Feishu document and conversation detail surfaces. Editing, export, and adding or -removing reactions are non-goals. - -## Spec - -Reuse CodeTwo's existing `MarkdownContent` renderer for fetched document and conversation bodies. -Preserve the current loading and empty states, scroll containers, reading width, source text, and -external-link behavior. Plain text must remain readable because it is valid Markdown input. When a -message has no converted text, show a localized human label for common Feishu message types and a -generic "view in Feishu" fallback instead of a raw `[type]` marker. -The community plugin enriches one message page through Feishu's reaction batch API, converts common -Feishu emoji identifiers into visible emoji, and omits reaction data when none exists or enrichment -fails. CodeTwo renders each aggregate as a compact, accessible emoji-and-count pill beneath the -message without making the pill interactive. - -### Acceptance criteria - -- [x] AC-1: A fetched document containing Markdown headings, emphasis, lists, links, and code renders - semantic HTML instead of visible Markdown delimiters. -- [x] AC-2: Conversation text, rich-text posts, and converted message cards use Markdown semantics; empty - media or unsupported payloads show localized readable fallbacks rather than `[type]`. -- [x] AC-3: Inline Feishu emotion nodes render as visible emoji, and message reactions render as compact - emoji-and-count aggregates with accessible names. -- [x] AC-4: Reaction enrichment uses one batch request for the visible message page, requires only the - read scope, and fails without hiding the underlying messages. -- [x] AC-5: The loading state and localized empty-document state remain unchanged. -- [x] AC-6: Focused rendered tests, the renderer and full desktop builds, the SDLC check, and diff checks - pass. -- [ ] AC-7: A real C2-dev conversation view passes without a visible error overlay after macOS is - unlocked and the existing single Core can be restarted safely. - -## Decision and gates - -The user's direct implementation request approves this narrowly scoped Intent and Spec, with -chenli as the named approver. The user later authorized PR #185 and explicitly authorized its merge -on 2026-08-31. No publication, deployment, or release is authorized. - -## Plan - -Replace the plain-text document body with the existing shared Markdown renderer, keep conversation -content on that same renderer, add localized message-type fallbacks, and extend only the focused -Feishu rendered test to protect semantic output, emoji, and reactions. The community plugin adds -the reaction read scope, advances its one-click scope revision, batch-enriches the visible message -page, and owns the Feishu emoji-name conversion. Verify the focused tests, renderer build, -lifecycle contract, and real document and conversation details in the existing single C2-dev -instance. Rollback is the inverse component, localization, and test change. - -## Build - -The Feishu document detail now passes its fetched body through the existing shared -`MarkdownContent` renderer instead of presenting the source as whitespace-preserved plain text. -The surrounding document container, loading state, localized empty fallback, reading width, and -external-link behavior remain unchanged. The document stylesheet now applies its reading line -height to the renderer's `.codetwo-markdown` child. A focused rendered regression test covers a -heading, emphasis, a list, a link, inline code, and the absence of raw Markdown delimiters. The -conversation path already shared this renderer; it now also replaces empty `[type]` placeholders -with localized labels for images, files, audio, video, stickers, cards, rich text, and unsupported -messages. -The conversation row now renders reaction aggregates beneath the Markdown body using quiet, -non-interactive pills. The community plugin adapter `0.2.11` requests -`im:message.reactions:read`, uses `/open-apis/im/v1/messages/reactions/batch_query`, maps common -emoji identifiers to Unicode, and degrades to readable names for unknown identifiers. Reaction -enrichment is fail-soft so message history remains available when the extra request is unavailable. - -## Verification - -Verdict: implementation checks passed; real-window verification pending an unlocked macOS session. - -- `bun test ./tests/feishuWorkspaceRendered.test.tsx`: 7 passed, 0 failed, 253 - expectations. React emitted the suite's existing non-failing `act(...)` warnings. -- `npx vitest run tests/codetwo-runtime.spec.ts` in the community plugin: 9 tests passed, including - one-click reaction scope registration, inline emotion conversion, batch reaction aggregation, - and the runtime response contract. -- `bun run build:renderer`: passed, including the design-system check, TypeScript compilation, and - Vite production build. Vite retained its existing large-chunk advisory. -- `bun run build`: passed and produced the development macOS app. The native helper linker retained - existing missing CommandLineTools search-path warnings; package signing and notarization remain - intentionally skipped for this development build. -- The first `bun script/check-sdlc.ts` run rejected non-scalar frontmatter and a pending output - description. The artifact was corrected; the next run passed. `git diff --check` also passed. -- A later focused-test invocation used a repository-root path while already inside `apps/desktop`, - so Bun found no matching test. Re-running the same test with the correct relative path passed. -- Real-window evidence is pending because macOS is locked; the existing single C2-dev instance has - not been killed, duplicated, or reopened against shared state. - -### Acceptance evidence - -- AC-1: PASS — `Verification record above` preserves the original passing evidence. -- AC-2: PASS — `Verification record above` preserves the original passing evidence. -- AC-3: PASS — `Verification record above` preserves the original passing evidence. -- AC-4: PASS — `Verification record above` preserves the original passing evidence. -- AC-5: PASS — `Verification record above` preserves the original passing evidence. -- AC-6: PASS — `Verification record above` preserves the original passing evidence. -- AC-7: BLOCKED — `Verification record above` preserves the original unresolved criterion. - -Residual risk: Feishu publishes many custom emoji identifiers. Common reactions map to matching -Unicode emoji; unknown identifiers fall back to a spaced readable name rather than the proprietary -Feishu artwork. Feishu rich blocks that the plugin does not convert to Markdown remain limited by -the fetched source representation. - -## Review and release - -Approval: implementation approved by chenli through the user request. -Merge approval: PR #185 explicitly approved for merge by chenli on 2026-08-31. -Release target: none. -Release identity: not applicable until released. -Smoke evidence: not applicable until released. -Rollback: restore the prior plain-text Feishu document body rendering. -No release: repository integration was approved; no release was requested. - -## Feedback - -No post-change feedback exists yet. diff --git a/docs/sdlc/changes/2026-08-30-feishu-document-markdown/intent.md b/docs/sdlc/changes/2026-08-30-feishu-document-markdown/intent.md new file mode 100644 index 00000000..a2385676 --- /dev/null +++ b/docs/sdlc/changes/2026-08-30-feishu-document-markdown/intent.md @@ -0,0 +1,55 @@ +--- +id: "2026-08-30-feishu-document-markdown" +stage: intent +schema: 3 +status: accepted +owner: codex +created: 2026-08-30 +source: user request in this task, "文档 md 渲染" +risk: medium +approved_by: "chenli" +approved_at: "2026-08-30" +--- + +# Intent: Render Feishu documents and conversations + +## Problem + +The user requested that Feishu document content render as Markdown, then explicitly extended the +request to conversation, emoji, and reaction rendering. Document and message bodies should show +readable semantic content rather than raw Markdown delimiters or technical placeholders, and +reaction totals should remain visually attached to the message they annotate. The change affects +the read-only Feishu document and conversation detail surfaces. Editing, export, and adding or +removing reactions are non-goals. + +## Proposed outcome + +The user requested that Feishu document content render as Markdown, then explicitly extended the + +## Affected users and systems + +Migrated from legacy change.md. + +## Constraints + +The user's direct implementation request approves this narrowly scoped Intent and Spec, with +chenli as the named approver. The user later authorized PR #185 and explicitly authorized its merge +on 2026-08-31. No publication, deployment, or release is authorized. + +## Out of scope + +Not recorded in the legacy single-file Artifact. + +## Success signals + +See Spec acceptance criteria. + +## Open questions + +None recorded in migration. + +## Decision + +The user's direct implementation request approves this narrowly scoped Intent and Spec, with +chenli as the named approver. The user later authorized PR #185 and explicitly authorized its merge +on 2026-08-31. No publication, deployment, or release is authorized. diff --git a/docs/sdlc/changes/2026-08-30-feishu-document-markdown/plan.md b/docs/sdlc/changes/2026-08-30-feishu-document-markdown/plan.md new file mode 100644 index 00000000..92acc63f --- /dev/null +++ b/docs/sdlc/changes/2026-08-30-feishu-document-markdown/plan.md @@ -0,0 +1,68 @@ +--- +id: "2026-08-30-feishu-document-markdown" +stage: plan +schema: 3 +status: accepted +owner: codex +created: 2026-08-30 +based_on: spec.md +risk: medium +scope: community/plugins/feishu, apps/desktop +approved_by: "chenli" +approved_at: "2026-08-30" +--- + +# Plan: Render Feishu documents and conversations + +## Files and ownership + +community/plugins/feishu, apps/desktop + +## Order of work + +Replace the plain-text document body with the existing shared Markdown renderer, keep conversation +content on that same renderer, add localized message-type fallbacks, and extend only the focused +Feishu rendered test to protect semantic output, emoji, and reactions. The community plugin adds +the reaction read scope, advances its one-click scope revision, batch-enriches the visible message +page, and owns the Feishu emoji-name conversion. Verify the focused tests, renderer build, +lifecycle contract, and real document and conversation details in the existing single C2-dev +instance. Rollback is the inverse component, localization, and test change. + +## Test-first proof + +See legacy Verification section. + +## Visual or integration proof + +See legacy Verification section. + +## Risks and mitigations + +See legacy Decision and gates. + +## Rollback + +See legacy Review and release. + +## Deviations + +The Feishu document detail now passes its fetched body through the existing shared +`MarkdownContent` renderer instead of presenting the source as whitespace-preserved plain text. +The surrounding document container, loading state, localized empty fallback, reading width, and +external-link behavior remain unchanged. The document stylesheet now applies its reading line +height to the renderer's `.codetwo-markdown` child. A focused rendered regression test covers a +heading, emphasis, a list, a link, inline code, and the absence of raw Markdown delimiters. The +conversation path already shared this renderer; it now also replaces empty `[type]` placeholders +with localized labels for images, files, audio, video, stickers, cards, rich text, and unsupported +messages. +The conversation row now renders reaction aggregates beneath the Markdown body using quiet, +non-interactive pills. The community plugin adapter `0.2.11` requests +`im:message.reactions:read`, uses `/open-apis/im/v1/messages/reactions/batch_query`, maps common +emoji identifiers to Unicode, and degrades to readable names for unknown identifiers. Reaction +enrichment is fail-soft so message history remains available when the extra request is unavailable. + +## Decision + +The user's direct implementation request approves this narrowly scoped Intent and Spec, with +chenli as the named approver. The user later authorized PR #185 and explicitly authorized its merge +on 2026-08-31. No publication, deployment, or release is authorized. diff --git a/docs/sdlc/changes/2026-08-30-feishu-document-markdown/spec.md b/docs/sdlc/changes/2026-08-30-feishu-document-markdown/spec.md new file mode 100644 index 00000000..e5596018 --- /dev/null +++ b/docs/sdlc/changes/2026-08-30-feishu-document-markdown/spec.md @@ -0,0 +1,70 @@ +--- +id: "2026-08-30-feishu-document-markdown" +stage: spec +schema: 3 +status: accepted +owner: codex +created: 2026-08-30 +based_on: intent.md +risk: medium +approved_by: "chenli" +approved_at: "2026-08-30" +--- + +# Spec: Render Feishu documents and conversations + +## Requirements + +Reuse CodeTwo's existing `MarkdownContent` renderer for fetched document and conversation bodies. +Preserve the current loading and empty states, scroll containers, reading width, source text, and +external-link behavior. Plain text must remain readable because it is valid Markdown input. When a +message has no converted text, show a localized human label for common Feishu message types and a +generic "view in Feishu" fallback instead of a raw `[type]` marker. +The community plugin enriches one message page through Feishu's reaction batch API, converts common +Feishu emoji identifiers into visible emoji, and omits reaction data when none exists or enrichment +fails. CodeTwo renders each aggregate as a compact, accessible emoji-and-count pill beneath the +message without making the pill interactive. + +## User experience + +Not separately recorded in legacy change.md. + +## Technical design + +See Requirements and legacy Git history. + +## Security and privacy + +See migrated Decision and gates. + +## Alternatives and non-goals + +Not separately recorded in legacy change.md. + +## Areas of concern + +The user's direct implementation request approves this narrowly scoped Intent and Spec, with +chenli as the named approver. The user later authorized PR #185 and explicitly authorized its merge +on 2026-08-31. No publication, deployment, or release is authorized. + +## Acceptance criteria + +- [x] AC-1: A fetched document containing Markdown headings, emphasis, lists, links, and code renders + semantic HTML instead of visible Markdown delimiters. +- [x] AC-2: Conversation text, rich-text posts, and converted message cards use Markdown semantics; empty + media or unsupported payloads show localized readable fallbacks rather than `[type]`. +- [x] AC-3: Inline Feishu emotion nodes render as visible emoji, and message reactions render as compact + emoji-and-count aggregates with accessible names. +- [x] AC-4: Reaction enrichment uses one batch request for the visible message page, requires only the + read scope, and fails without hiding the underlying messages. +- [x] AC-5: The loading state and localized empty-document state remain unchanged. +- [x] AC-6: Focused rendered tests, the renderer and full desktop builds, the SDLC check, and diff checks + pass. +- [ ] AC-7: A real C2-dev conversation view passes without a visible error overlay after macOS is + unlocked and the existing single Core can be restarted safely. + +## Decision + +The user's direct implementation request approves this narrowly scoped Intent and Spec, with +chenli as the named approver. The user later authorized PR #185 and explicitly authorized its merge +on 2026-08-31. No publication, deployment, or release is authorized. diff --git a/docs/sdlc/changes/2026-08-30-feishu-document-markdown/verification.md b/docs/sdlc/changes/2026-08-30-feishu-document-markdown/verification.md new file mode 100644 index 00000000..7a8b021c --- /dev/null +++ b/docs/sdlc/changes/2026-08-30-feishu-document-markdown/verification.md @@ -0,0 +1,119 @@ +--- +id: "2026-08-30-feishu-document-markdown" +stage: verification +schema: 3 +status: pending +owner: codex +created: 2026-08-30 +based_on: plan.md +commit: "" +verification_mode: owner +verified_by: "" +verified_at: "" +release_target: none +release_identity: "not applicable until released." +--- + +# Verification: Render Feishu documents and conversations + +## Automated checks + +Verdict: implementation checks passed; real-window verification pending an unlocked macOS session. + +- `bun test ./tests/feishuWorkspaceRendered.test.tsx`: 7 passed, 0 failed, 253 + expectations. React emitted the suite's existing non-failing `act(...)` warnings. +- `npx vitest run tests/codetwo-runtime.spec.ts` in the community plugin: 9 tests passed, including + one-click reaction scope registration, inline emotion conversion, batch reaction aggregation, + and the runtime response contract. +- `bun run build:renderer`: passed, including the design-system check, TypeScript compilation, and + Vite production build. Vite retained its existing large-chunk advisory. +- `bun run build`: passed and produced the development macOS app. The native helper linker retained + existing missing CommandLineTools search-path warnings; package signing and notarization remain + intentionally skipped for this development build. +- The first `bun script/check-sdlc.ts` run rejected non-scalar frontmatter and a pending output + description. The artifact was corrected; the next run passed. `git diff --check` also passed. +- A later focused-test invocation used a repository-root path while already inside `apps/desktop`, + so Bun found no matching test. Re-running the same test with the correct relative path passed. +- Real-window evidence is pending because macOS is locked; the existing single C2-dev instance has + not been killed, duplicated, or reopened against shared state. + +### Acceptance evidence + +- AC-1: PASS — `Verification record above` preserves the original passing evidence. +- AC-2: PASS — `Verification record above` preserves the original passing evidence. +- AC-3: PASS — `Verification record above` preserves the original passing evidence. +- AC-4: PASS — `Verification record above` preserves the original passing evidence. +- AC-5: PASS — `Verification record above` preserves the original passing evidence. +- AC-6: PASS — `Verification record above` preserves the original passing evidence. +- AC-7: BLOCKED — `Verification record above` preserves the original unresolved criterion. + +Residual risk: Feishu publishes many custom emoji identifiers. Common reactions map to matching +Unicode emoji; unknown identifiers fall back to a spaced readable name rather than the proprietary +Feishu artwork. Feishu rich blocks that the plugin does not convert to Markdown remain limited by +the fetched source representation. + +## Behavioral evidence + +Verdict: implementation checks passed; real-window verification pending an unlocked macOS session. + +- `bun test ./tests/feishuWorkspaceRendered.test.tsx`: 7 passed, 0 failed, 253 + expectations. React emitted the suite's existing non-failing `act(...)` warnings. +- `npx vitest run tests/codetwo-runtime.spec.ts` in the community plugin: 9 tests passed, including + one-click reaction scope registration, inline emotion conversion, batch reaction aggregation, + and the runtime response contract. +- `bun run build:renderer`: passed, including the design-system check, TypeScript compilation, and + Vite production build. Vite retained its existing large-chunk advisory. +- `bun run build`: passed and produced the development macOS app. The native helper linker retained + existing missing CommandLineTools search-path warnings; package signing and notarization remain + intentionally skipped for this development build. +- The first `bun script/check-sdlc.ts` run rejected non-scalar frontmatter and a pending output + description. The artifact was corrected; the next run passed. `git diff --check` also passed. +- A later focused-test invocation used a repository-root path while already inside `apps/desktop`, + so Bun found no matching test. Re-running the same test with the correct relative path passed. +- Real-window evidence is pending because macOS is locked; the existing single C2-dev instance has + not been killed, duplicated, or reopened against shared state. + +### Acceptance evidence + +- AC-1: PASS — `Verification record above` preserves the original passing evidence. +- AC-2: PASS — `Verification record above` preserves the original passing evidence. +- AC-3: PASS — `Verification record above` preserves the original passing evidence. +- AC-4: PASS — `Verification record above` preserves the original passing evidence. +- AC-5: PASS — `Verification record above` preserves the original passing evidence. +- AC-6: PASS — `Verification record above` preserves the original passing evidence. +- AC-7: BLOCKED — `Verification record above` preserves the original unresolved criterion. + +Residual risk: Feishu publishes many custom emoji identifiers. Common reactions map to matching +Unicode emoji; unknown identifiers fall back to a spaced readable name rather than the proprietary +Feishu artwork. Feishu rich blocks that the plugin does not convert to Markdown remain limited by +the fetched source representation. + +## Visual evidence + +See bundle evidence/ when present. + +## Security and privacy evidence + +Not separately recorded unless present in legacy Verification. + +## Deviations and residual risk + +Residual risk: Feishu publishes many custom emoji identifiers. Common reactions map to matching + +## Verdict + +Verdict: implementation checks passed; real-window verification pending an unlocked macOS session.. + +## Review and release + +Approval: implementation approved by chenli through the user request. +Merge approval: PR #185 explicitly approved for merge by chenli on 2026-08-31. +Release target: none. +Release identity: not applicable until released. +Smoke evidence: not applicable until released. +Rollback: restore the prior plain-text Feishu document body rendering. +No release: repository integration was approved; no release was requested. + +## Feedback + +No post-change feedback exists yet. diff --git a/docs/sdlc/changes/2026-08-30-feishu-realtime-sync/change.md b/docs/sdlc/changes/2026-08-30-feishu-realtime-sync/change.md deleted file mode 100644 index c7147cd7..00000000 --- a/docs/sdlc/changes/2026-08-30-feishu-realtime-sync/change.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -id: change-2026-08-30-feishu-realtime-sync -kind: change -schema: 2 -status: executing -risk: high -owner: codex -approvers: chenli -approved_at: 2026-08-30 -created: 2026-08-30 -updated: 2026-08-31 -source: user request in this task, "支持飞书新消息的同步……有红点……立即更新，而不是通过轮询" -inputs: the Feishu collaboration connector, C2 process-runtime events, and the host-rendered Feishu sidebar -outputs: event-driven Feishu message and document updates with local unread/change indicators -scope: community/plugins/feishu, apps/desktop, crates/plugins -next_trigger: generate one covered external Feishu event and verify immediate C2 refresh plus clear-on-open activity dots -verification_mode: independent -verified_by: pending -verified_at: pending ---- - -# Add realtime Feishu connector updates - -## Intent - -The Feishu collaboration surface currently reads messages and documents only when the user opens or -manually reloads them. The user requested event-driven updates, including a visible red dot for new -activity, without periodic message or document polling. - -Official Feishu APIs do not expose an event that mirrors an authorized user's complete inbox. -`im.message.receive_v1` is an application/bot event and can cover bot direct messages and messages in -groups that contain the bot, subject to the granted scope. Cloud-document events can use user identity, -but only after a resource owner or manager subscribes each document or Base. The product must not -present either source as Feishu's global unread state. - -## Spec - -The community Feishu Runtime establishes the official Feishu WebSocket client after an authorized -connection becomes active. It declares the message, reaction, document, and Base events in the -one-click application registration add-ons and requests only the scopes required by the implemented -coverage. Visible documents and Bases are subscribed with the user's access token when Feishu permits -the current user to manage that resource. - -The Runtime emits a typed connector event through the process protocol. C2 authenticates the source -bundle before adding its bundle id and forwarding the event to the renderer. The Feishu surface accepts -events only from its active connector, deduplicates provider event ids, refreshes the currently visible -conversation or resource immediately, and records local unread/change dots for background resources. -Opening a resource clears its local dot. Periodic polling is not used for messages, documents, or Base; -OAuth completion polling remains a separate short-lived authorization mechanism. - -### Acceptance criteria - -- [x] AC-1: Application registration requests the implemented tenant message/reaction events and user - document/Base events, and increments its scope revision so an existing one-click application is - prompted to approve the new configuration. -- [x] AC-2: An authorized Runtime starts one official Feishu WebSocket client, deduplicates at-least-once - delivery, emits normalized connector events, and stops it on disconnect or process exit. -- [x] AC-3: Documents and Bases visible to C2 are subscribed with user identity when the current user is an - owner or manager; unsupported resources remain usable and surface a bounded warning instead of - failing the whole overview. -- [x] AC-4: C2 authenticates the source plugin of each connector event and the renderer accepts events only - for the currently active Feishu connector. -- [x] AC-5: New covered messages and changed resources produce local dots; selecting the item clears the dot, - while an already-visible item refreshes immediately without a recurring timer. -- [x] AC-6: Product copy and documentation state that ordinary user-to-user chats and non-manageable - documents do not have full realtime coverage and that C2 dots are not Feishu global unread counts. -- [x] AC-7: Focused community-plugin, Rust, renderer, build, and SDLC checks pass within the documented - native-link limitation. - -## Decision and gates - -The user's direct implementation request approves this Intent and Spec, with chenli as the named -approver. The user later authorized PR #185 and explicitly authorized its merge on 2026-08-31. -No publication, deployment, or release is authorized. - -## Plan - -Extend the one-click app configuration, bundle the official Node SDK into the self-contained Runtime, -subscribe eligible resources, add a source-authenticated connector event route, and update the existing -flat Feishu sidebar with event-driven refresh and local dots. Rollback removes the event registration, -WebSocket client, connector event route, and local dot state while retaining the current on-open reads. - -## Build - -- Added `im.message.receive_v1`, reaction events, Drive edit, and Base record/field events to the - one-click registration add-ons. Scope revision 5 makes an already-authorized one-click app return - to the Feishu confirmation flow before C2 treats the connection as ready. -- Added the official `@larksuiteoapi/node-sdk` WebSocket client to the community Runtime, with one - client per authorized process, automatic reconnect, bounded event-id/message-id deduplication, - normalized connector events, and shutdown on disconnect or stdin close. The SDK and its runtime - dependencies are bundled into the self-contained `plugin.bundle.cjs`; the C2 adapter is version - 0.4.0. -- Added user-token `document.subscribe` and `table.subscribe` operations. The renderer subscribes - the small visible set, the current selection, and pinned Docs/Base resources; owner/manager - failures degrade to an English/Chinese informational message rather than failing the workspace. -- Added a typed internal `ConnectorEvent`. The process protocol strips the internal `bundle:` prefix, - attaches the authenticated installed-bundle id, and does not place connector payloads on the - host-wide public JSON bus. The desktop forwards only that attributed envelope; App matches both - plugin id and connector id before dispatching it to Feishu UI state. -- Added local per-resource and per-section activity dots, immediate current-detail refresh, event - coalescing for Drive/Base bursts, preview reordering for new messages, and clear-on-open behavior. - The only remaining interval in the component is the short-lived OAuth-completion poll; provider - data refresh has no recurring timer. -- Added an official-source research note and updated the C2 Plugin Protocol, Plugin Standard, and - community README files with identity, coverage, confidentiality, and multi-client limitations. - -## Verification - -- Community Runtime `npx vitest run tests/codetwo-runtime.spec.ts`: 10 passed. This covers event/scope - registration, scope-revision upgrade, OAuth, resource listing, user-identity document subscription, - message rendering, sending, and credential storage. -- Community `npm run -s build`: passed and produced a 5.9 MB self-contained - `codetwo/plugin.bundle.cjs`. A direct JSON-RPC initialize smoke test against that generated Bundle - returned version 0.4.0 and the expected single connector command. -- C2 validator accepted the 0.4.0 adapter with one Runtime command and one connector. -- Renderer tests covering the plugin model and Feishu surface: 23 passed, including event-driven - preview updates, resource and section dots, clear-on-open, visible-conversation refresh, Markdown, - avatar, pin, limit, and bilingual UI behavior. Existing React `act(...)` warnings remain. -- `bun run build:renderer` passed design-system source/dist checks, TypeScript, and Vite production - build; the existing large-chunk warning remains. A final `bunx tsc --noEmit` also passed. -- `DOCS_RS=1 cargo test -p codetwo-plugins --lib`: 38 passed, including normalization from internal - `bundle:` runtime names to authenticated installed bundle ids. -- `DOCS_RS=1 cargo check -p codetwo-plugins --tests` and - `DOCS_RS=1 cargo check -p codetwo-desktop-host`: passed. The focused `plugin_protocol` integration - binary still cannot link in this checkout because local Ghostty symbols are unavailable; its source - type-checks, and this is the same known repository limitation recorded by the connector change. -- Rust formatting for changed files and both repositories' `git diff --check` passed. - -Verdict: partial. The code, generated self-contained Bundle, UI behavior, static/runtime contracts, -packaged installation, application event configuration, and authorized transport startup pass. A -real external Feishu event has not yet been generated, so the final provider-to-red-dot observation -remains open. - -The current packaged app now runs community adapter 0.5.0. Feishu reported the one-click application -and revision-5 event configuration successful, the user approved the ten-scope OAuth grant, and the -C2 connection panel reports the authorized account as Connected. The adapter's dedicated Node process -holds a live established TLS connection after overview loading and emits no realtime-start error, -which is consistent with the official WebSocket client remaining active. This proves transport -startup, not delivery of a particular message/document event. - -### Acceptance evidence - -- AC-1: PASS — `Verification record above` preserves the original passing evidence. -- AC-2: PASS — `Verification record above` preserves the original passing evidence. -- AC-3: PASS — `Verification record above` preserves the original passing evidence. -- AC-4: PASS — `Verification record above` preserves the original passing evidence. -- AC-5: PASS — `Verification record above` preserves the original passing evidence. -- AC-6: PASS — `Verification record above` preserves the original passing evidence. -- AC-7: PASS — `Verification record above` preserves the original passing evidence. - -Residual risk: Feishu does not provide user-identity realtime events for arbitrary colleague chats; -read-only/non-manageable documents cannot be subscribed. Multiple clients with one App ID share a -clustered event stream rather than receiving broadcast copies. The UI labels these events as local C2 -activity and falls back to refresh-on-open for uncovered resources. - -## Review and release - -Approval: implementation approved by chenli through the user request. -Merge approval: PR #185 explicitly approved for merge by chenli on 2026-08-31. -Release target: none. -Release identity: not applicable until released. -Smoke evidence: not applicable until released. -Rollback: described in the Plan. -No release: no release was requested. - -## Feedback - -The research skill's official-source pass changed the implementation boundary: message realtime is -limited to bot/application coverage, while Docs/Base use per-resource user subscriptions. The UI and -documentation therefore avoid claiming a full user inbox mirror or Feishu global unread count. diff --git a/docs/sdlc/changes/2026-08-30-feishu-realtime-sync/intent.md b/docs/sdlc/changes/2026-08-30-feishu-realtime-sync/intent.md new file mode 100644 index 00000000..62ab42b5 --- /dev/null +++ b/docs/sdlc/changes/2026-08-30-feishu-realtime-sync/intent.md @@ -0,0 +1,58 @@ +--- +id: "2026-08-30-feishu-realtime-sync" +stage: intent +schema: 3 +status: accepted +owner: codex +created: 2026-08-30 +source: user request in this task, "支持飞书新消息的同步……有红点……立即更新，而不是通过轮询" +risk: high +approved_by: "chenli" +approved_at: "2026-08-30" +--- + +# Intent: Add realtime Feishu connector updates + +## Problem + +The Feishu collaboration surface currently reads messages and documents only when the user opens or +manually reloads them. The user requested event-driven updates, including a visible red dot for new +activity, without periodic message or document polling. + +Official Feishu APIs do not expose an event that mirrors an authorized user's complete inbox. +`im.message.receive_v1` is an application/bot event and can cover bot direct messages and messages in +groups that contain the bot, subject to the granted scope. Cloud-document events can use user identity, +but only after a resource owner or manager subscribes each document or Base. The product must not +present either source as Feishu's global unread state. + +## Proposed outcome + +The Feishu collaboration surface currently reads messages and documents only when the user opens or + +## Affected users and systems + +Migrated from legacy change.md. + +## Constraints + +The user's direct implementation request approves this Intent and Spec, with chenli as the named +approver. The user later authorized PR #185 and explicitly authorized its merge on 2026-08-31. +No publication, deployment, or release is authorized. + +## Out of scope + +Not recorded in the legacy single-file Artifact. + +## Success signals + +See Spec acceptance criteria. + +## Open questions + +None recorded in migration. + +## Decision + +The user's direct implementation request approves this Intent and Spec, with chenli as the named +approver. The user later authorized PR #185 and explicitly authorized its merge on 2026-08-31. +No publication, deployment, or release is authorized. diff --git a/docs/sdlc/changes/2026-08-30-feishu-realtime-sync/plan.md b/docs/sdlc/changes/2026-08-30-feishu-realtime-sync/plan.md new file mode 100644 index 00000000..9098e0ea --- /dev/null +++ b/docs/sdlc/changes/2026-08-30-feishu-realtime-sync/plan.md @@ -0,0 +1,72 @@ +--- +id: "2026-08-30-feishu-realtime-sync" +stage: plan +schema: 3 +status: accepted +owner: codex +created: 2026-08-30 +based_on: spec.md +risk: high +scope: community/plugins/feishu, apps/desktop, crates/plugins +approved_by: "chenli" +approved_at: "2026-08-30" +--- + +# Plan: Add realtime Feishu connector updates + +## Files and ownership + +community/plugins/feishu, apps/desktop, crates/plugins + +## Order of work + +Extend the one-click app configuration, bundle the official Node SDK into the self-contained Runtime, +subscribe eligible resources, add a source-authenticated connector event route, and update the existing +flat Feishu sidebar with event-driven refresh and local dots. Rollback removes the event registration, +WebSocket client, connector event route, and local dot state while retaining the current on-open reads. + +## Test-first proof + +See legacy Verification section. + +## Visual or integration proof + +See legacy Verification section. + +## Risks and mitigations + +See legacy Decision and gates. + +## Rollback + +See legacy Review and release. + +## Deviations + +- Added `im.message.receive_v1`, reaction events, Drive edit, and Base record/field events to the + one-click registration add-ons. Scope revision 5 makes an already-authorized one-click app return + to the Feishu confirmation flow before C2 treats the connection as ready. +- Added the official `@larksuiteoapi/node-sdk` WebSocket client to the community Runtime, with one + client per authorized process, automatic reconnect, bounded event-id/message-id deduplication, + normalized connector events, and shutdown on disconnect or stdin close. The SDK and its runtime + dependencies are bundled into the self-contained `plugin.bundle.cjs`; the C2 adapter is version + 0.4.0. +- Added user-token `document.subscribe` and `table.subscribe` operations. The renderer subscribes + the small visible set, the current selection, and pinned Docs/Base resources; owner/manager + failures degrade to an English/Chinese informational message rather than failing the workspace. +- Added a typed internal `ConnectorEvent`. The process protocol strips the internal `bundle:` prefix, + attaches the authenticated installed-bundle id, and does not place connector payloads on the + host-wide public JSON bus. The desktop forwards only that attributed envelope; App matches both + plugin id and connector id before dispatching it to Feishu UI state. +- Added local per-resource and per-section activity dots, immediate current-detail refresh, event + coalescing for Drive/Base bursts, preview reordering for new messages, and clear-on-open behavior. + The only remaining interval in the component is the short-lived OAuth-completion poll; provider + data refresh has no recurring timer. +- Added an official-source research note and updated the C2 Plugin Protocol, Plugin Standard, and + community README files with identity, coverage, confidentiality, and multi-client limitations. + +## Decision + +The user's direct implementation request approves this Intent and Spec, with chenli as the named +approver. The user later authorized PR #185 and explicitly authorized its merge on 2026-08-31. +No publication, deployment, or release is authorized. diff --git a/docs/sdlc/changes/2026-08-30-feishu-realtime-sync/spec.md b/docs/sdlc/changes/2026-08-30-feishu-realtime-sync/spec.md new file mode 100644 index 00000000..31656642 --- /dev/null +++ b/docs/sdlc/changes/2026-08-30-feishu-realtime-sync/spec.md @@ -0,0 +1,76 @@ +--- +id: "2026-08-30-feishu-realtime-sync" +stage: spec +schema: 3 +status: accepted +owner: codex +created: 2026-08-30 +based_on: intent.md +risk: high +approved_by: "chenli" +approved_at: "2026-08-30" +--- + +# Spec: Add realtime Feishu connector updates + +## Requirements + +The community Feishu Runtime establishes the official Feishu WebSocket client after an authorized +connection becomes active. It declares the message, reaction, document, and Base events in the +one-click application registration add-ons and requests only the scopes required by the implemented +coverage. Visible documents and Bases are subscribed with the user's access token when Feishu permits +the current user to manage that resource. + +The Runtime emits a typed connector event through the process protocol. C2 authenticates the source +bundle before adding its bundle id and forwarding the event to the renderer. The Feishu surface accepts +events only from its active connector, deduplicates provider event ids, refreshes the currently visible +conversation or resource immediately, and records local unread/change dots for background resources. +Opening a resource clears its local dot. Periodic polling is not used for messages, documents, or Base; +OAuth completion polling remains a separate short-lived authorization mechanism. + +## User experience + +Not separately recorded in legacy change.md. + +## Technical design + +See Requirements and legacy Git history. + +## Security and privacy + +See migrated Decision and gates. + +## Alternatives and non-goals + +Not separately recorded in legacy change.md. + +## Areas of concern + +The user's direct implementation request approves this Intent and Spec, with chenli as the named +approver. The user later authorized PR #185 and explicitly authorized its merge on 2026-08-31. +No publication, deployment, or release is authorized. + +## Acceptance criteria + +- [x] AC-1: Application registration requests the implemented tenant message/reaction events and user + document/Base events, and increments its scope revision so an existing one-click application is + prompted to approve the new configuration. +- [x] AC-2: An authorized Runtime starts one official Feishu WebSocket client, deduplicates at-least-once + delivery, emits normalized connector events, and stops it on disconnect or process exit. +- [x] AC-3: Documents and Bases visible to C2 are subscribed with user identity when the current user is an + owner or manager; unsupported resources remain usable and surface a bounded warning instead of + failing the whole overview. +- [x] AC-4: C2 authenticates the source plugin of each connector event and the renderer accepts events only + for the currently active Feishu connector. +- [x] AC-5: New covered messages and changed resources produce local dots; selecting the item clears the dot, + while an already-visible item refreshes immediately without a recurring timer. +- [x] AC-6: Product copy and documentation state that ordinary user-to-user chats and non-manageable + documents do not have full realtime coverage and that C2 dots are not Feishu global unread counts. +- [x] AC-7: Focused community-plugin, Rust, renderer, build, and SDLC checks pass within the documented + native-link limitation. + +## Decision + +The user's direct implementation request approves this Intent and Spec, with chenli as the named +approver. The user later authorized PR #185 and explicitly authorized its merge on 2026-08-31. +No publication, deployment, or release is authorized. diff --git a/docs/sdlc/changes/2026-08-30-feishu-realtime-sync/verification.md b/docs/sdlc/changes/2026-08-30-feishu-realtime-sync/verification.md new file mode 100644 index 00000000..d6bc60fc --- /dev/null +++ b/docs/sdlc/changes/2026-08-30-feishu-realtime-sync/verification.md @@ -0,0 +1,147 @@ +--- +id: "2026-08-30-feishu-realtime-sync" +stage: verification +schema: 3 +status: pending +owner: codex +created: 2026-08-30 +based_on: plan.md +commit: "" +verification_mode: independent +verified_by: "" +verified_at: "" +release_target: none +release_identity: "not applicable until released." +--- + +# Verification: Add realtime Feishu connector updates + +## Automated checks + +- Community Runtime `npx vitest run tests/codetwo-runtime.spec.ts`: 10 passed. This covers event/scope + registration, scope-revision upgrade, OAuth, resource listing, user-identity document subscription, + message rendering, sending, and credential storage. +- Community `npm run -s build`: passed and produced a 5.9 MB self-contained + `codetwo/plugin.bundle.cjs`. A direct JSON-RPC initialize smoke test against that generated Bundle + returned version 0.4.0 and the expected single connector command. +- C2 validator accepted the 0.4.0 adapter with one Runtime command and one connector. +- Renderer tests covering the plugin model and Feishu surface: 23 passed, including event-driven + preview updates, resource and section dots, clear-on-open, visible-conversation refresh, Markdown, + avatar, pin, limit, and bilingual UI behavior. Existing React `act(...)` warnings remain. +- `bun run build:renderer` passed design-system source/dist checks, TypeScript, and Vite production + build; the existing large-chunk warning remains. A final `bunx tsc --noEmit` also passed. +- `DOCS_RS=1 cargo test -p codetwo-plugins --lib`: 38 passed, including normalization from internal + `bundle:` runtime names to authenticated installed bundle ids. +- `DOCS_RS=1 cargo check -p codetwo-plugins --tests` and + `DOCS_RS=1 cargo check -p codetwo-desktop-host`: passed. The focused `plugin_protocol` integration + binary still cannot link in this checkout because local Ghostty symbols are unavailable; its source + type-checks, and this is the same known repository limitation recorded by the connector change. +- Rust formatting for changed files and both repositories' `git diff --check` passed. + +Verdict: partial. The code, generated self-contained Bundle, UI behavior, static/runtime contracts, +packaged installation, application event configuration, and authorized transport startup pass. A +real external Feishu event has not yet been generated, so the final provider-to-red-dot observation +remains open. + +The current packaged app now runs community adapter 0.5.0. Feishu reported the one-click application +and revision-5 event configuration successful, the user approved the ten-scope OAuth grant, and the +C2 connection panel reports the authorized account as Connected. The adapter's dedicated Node process +holds a live established TLS connection after overview loading and emits no realtime-start error, +which is consistent with the official WebSocket client remaining active. This proves transport +startup, not delivery of a particular message/document event. + +### Acceptance evidence + +- AC-1: PASS — `Verification record above` preserves the original passing evidence. +- AC-2: PASS — `Verification record above` preserves the original passing evidence. +- AC-3: PASS — `Verification record above` preserves the original passing evidence. +- AC-4: PASS — `Verification record above` preserves the original passing evidence. +- AC-5: PASS — `Verification record above` preserves the original passing evidence. +- AC-6: PASS — `Verification record above` preserves the original passing evidence. +- AC-7: PASS — `Verification record above` preserves the original passing evidence. + +Residual risk: Feishu does not provide user-identity realtime events for arbitrary colleague chats; +read-only/non-manageable documents cannot be subscribed. Multiple clients with one App ID share a +clustered event stream rather than receiving broadcast copies. The UI labels these events as local C2 +activity and falls back to refresh-on-open for uncovered resources. + +## Behavioral evidence + +- Community Runtime `npx vitest run tests/codetwo-runtime.spec.ts`: 10 passed. This covers event/scope + registration, scope-revision upgrade, OAuth, resource listing, user-identity document subscription, + message rendering, sending, and credential storage. +- Community `npm run -s build`: passed and produced a 5.9 MB self-contained + `codetwo/plugin.bundle.cjs`. A direct JSON-RPC initialize smoke test against that generated Bundle + returned version 0.4.0 and the expected single connector command. +- C2 validator accepted the 0.4.0 adapter with one Runtime command and one connector. +- Renderer tests covering the plugin model and Feishu surface: 23 passed, including event-driven + preview updates, resource and section dots, clear-on-open, visible-conversation refresh, Markdown, + avatar, pin, limit, and bilingual UI behavior. Existing React `act(...)` warnings remain. +- `bun run build:renderer` passed design-system source/dist checks, TypeScript, and Vite production + build; the existing large-chunk warning remains. A final `bunx tsc --noEmit` also passed. +- `DOCS_RS=1 cargo test -p codetwo-plugins --lib`: 38 passed, including normalization from internal + `bundle:` runtime names to authenticated installed bundle ids. +- `DOCS_RS=1 cargo check -p codetwo-plugins --tests` and + `DOCS_RS=1 cargo check -p codetwo-desktop-host`: passed. The focused `plugin_protocol` integration + binary still cannot link in this checkout because local Ghostty symbols are unavailable; its source + type-checks, and this is the same known repository limitation recorded by the connector change. +- Rust formatting for changed files and both repositories' `git diff --check` passed. + +Verdict: partial. The code, generated self-contained Bundle, UI behavior, static/runtime contracts, +packaged installation, application event configuration, and authorized transport startup pass. A +real external Feishu event has not yet been generated, so the final provider-to-red-dot observation +remains open. + +The current packaged app now runs community adapter 0.5.0. Feishu reported the one-click application +and revision-5 event configuration successful, the user approved the ten-scope OAuth grant, and the +C2 connection panel reports the authorized account as Connected. The adapter's dedicated Node process +holds a live established TLS connection after overview loading and emits no realtime-start error, +which is consistent with the official WebSocket client remaining active. This proves transport +startup, not delivery of a particular message/document event. + +### Acceptance evidence + +- AC-1: PASS — `Verification record above` preserves the original passing evidence. +- AC-2: PASS — `Verification record above` preserves the original passing evidence. +- AC-3: PASS — `Verification record above` preserves the original passing evidence. +- AC-4: PASS — `Verification record above` preserves the original passing evidence. +- AC-5: PASS — `Verification record above` preserves the original passing evidence. +- AC-6: PASS — `Verification record above` preserves the original passing evidence. +- AC-7: PASS — `Verification record above` preserves the original passing evidence. + +Residual risk: Feishu does not provide user-identity realtime events for arbitrary colleague chats; +read-only/non-manageable documents cannot be subscribed. Multiple clients with one App ID share a +clustered event stream rather than receiving broadcast copies. The UI labels these events as local C2 +activity and falls back to refresh-on-open for uncovered resources. + +## Visual evidence + +See bundle evidence/ when present. + +## Security and privacy evidence + +Not separately recorded unless present in legacy Verification. + +## Deviations and residual risk + +Residual risk: Feishu does not provide user-identity realtime events for arbitrary colleague chats; + +## Verdict + +Verdict: partial. The code, generated self-contained Bundle, UI behavior, static/runtime contracts,. + +## Review and release + +Approval: implementation approved by chenli through the user request. +Merge approval: PR #185 explicitly approved for merge by chenli on 2026-08-31. +Release target: none. +Release identity: not applicable until released. +Smoke evidence: not applicable until released. +Rollback: described in the Plan. +No release: no release was requested. + +## Feedback + +The research skill's official-source pass changed the implementation boundary: message realtime is +limited to bot/application coverage, while Docs/Base use per-resource user subscriptions. The UI and +documentation therefore avoid claiming a full user inbox mirror or Feishu global unread count. diff --git a/docs/sdlc/changes/2026-08-30-flat-task-sections/change.md b/docs/sdlc/changes/2026-08-30-flat-task-sections/change.md deleted file mode 100644 index 8b9d8c1b..00000000 --- a/docs/sdlc/changes/2026-08-30-flat-task-sections/change.md +++ /dev/null @@ -1,167 +0,0 @@ ---- -id: change-2026-08-30-flat-task-sections -kind: change -schema: 2 -status: closed -risk: medium -owner: codex -approvers: user via the 2026-08-30 sidebar requests and explicit PR merge authorization -approved_at: 2026-08-30 -created: 2026-08-30 -updated: 2026-08-31 -source: user-supplied sidebar references and PR #183 -inputs: accepted sidebar hierarchy and interaction requirements -outputs: merge commit e3744874 and focused UI verification evidence -scope: apps/desktop -next_trigger: new sidebar feedback or a regression report -verification_mode: owner -verified_by: codex -verified_at: 2026-08-30 ---- - -# Flatten recent Tasks and add sidebar Sections - -## Intent - -The user supplied three macOS sidebar references on 2026-08-30 and asked that recent Tasks stop -being grouped or filtered by Project/folder. Tasks should appear in one cross-project feed, with -optional Sections as the only organizational layer. Users need to create and manage their own -Sections, while the system may maintain explainable automatic Sections. Disclosure controls should -sit immediately after each Section title as in the supplied references. - -In a follow-up reference on the same date, the user explicitly removed the entire redundant -`Recent chats`/Project-switcher row. The Task area now begins directly with Highlight, manual -Sections, or flat Tasks; Section creation remains available from a Task's context menu. - -The affected surface is the desktop SessionRail and its local organization state. This change does -not alter Task ownership, Project selection for new work, working directories, provider Sessions, -archive semantics, or any external system. The direct user request is accepted Intent and design -approval; it does not authorize a PR, merge, release, or production mutation. - -## Spec - -The Task surface is globally sorted across every Project. It has no separate Recent heading or -Project switcher. Project identity remains quiet row context, not a list partition. Unsectioned -Tasks remain a flat feed. A Task may have at most one explicit user Section. Explicit membership -wins over automatic grouping. - -`Highlight` is the first system Section. It automatically contains unassigned Tasks that are -pinned, running, awaiting input, or failed. `Archived` remains a system-owned fold. Manual Sections -can be created, renamed, folded, deleted, and selected from a Task context-menu submenu. Deleting a -Section returns its Tasks to automatic/flat placement; no Task is deleted. Section names, -assignments, order, and folded state persist as local UI organization. Semantic model-driven -clustering, cross-device synchronization, and drag reordering are non-goals for this change. - -### Acceptance criteria - -- [x] AC-1: Active and archived Tasks from different Projects are available without changing the active - Project, and no Project/folder headings partition the Task list. -- [x] AC-2: Unassigned idle Tasks remain one globally recency-sorted flat feed with their Project shown - only as row metadata. -- [x] AC-3: The automatic `Highlight` Section contains only unassigned pinned, running, awaiting-input, - or failed Tasks; explicit user Section membership takes precedence. -- [x] AC-4: Users can create, rename, delete, fold, and unfold manual Sections and move a Task into a - Section or back to no Section from its context menu. -- [x] AC-5: Manual Section state survives a renderer remount, invalid stored data fails closed to an - empty organization, and deleting a Section preserves every Task. -- [x] AC-6: Each disclosure chevron appears immediately after its Section title, communicates expanded - state, and works with pointer and keyboard input in light, dark, and the 220-pixel rail. Each - Section title shares the same 16-pixel left baseline as Task titles. -- [x] AC-7: The redundant Recent/Project header and its inline add control do not render; the list begins - directly with a Section or Task without reserving empty space. -- [x] AC-8: Existing select, rename, pin, archive/restore, and context-menu behavior remains available - without duplicating Tasks between Sections. -- [x] AC-9: Focused tests, renderer/design build, SDLC check, and real renderer inspection pass. - -## Decision and gates - -The user's request accepts the Intent and visible design. The implementation uses deterministic -automatic grouping so the system cannot silently reclassify work by model inference. Local UI -persistence matches existing rail width/fold preferences and avoids changing Core Task data. Human -review remains the next gate after verification. - -## Plan - -1. Add a small versioned Task Section state module with defensive parsing and pure create, rename, - assign, fold, and delete operations. -2. Replace active-Project filtering and Pinned/Active partitions with cross-project sorting, - automatic Highlight, manual Section folds, and a flat remainder in SessionRail. -3. Add native and rendered context-menu Section assignment plus quiet inline Section management; - remove the redundant Recent/Project header after the user's follow-up direction. -4. Protect persistence, precedence, ordering, disclosure placement, and existing actions with - focused tests; verify the real renderer in light, dark, standard, and minimum rail widths. - -Rollback removes the local Section state module and restores the prior active-Project list -partition. Stored UI organization is versioned and ignored by older builds. - -## Build - -- Added a versioned, local `sidebarSections` state module with defensive parsing and pure - create/rename/assign/fold/delete operations. -- Reworked SessionRail into an all-Project Task feed with deterministic Highlight, manual - Sections, a flat remainder, and a global Archived fold. -- Added native and rendered Section submenus plus quiet inline Section creation and management. -- Removed the entire Recent/Project-switcher row and its inline Section-add button. Section - creation remains contextual to the Task being organized. -- Kept the optional recent-conversation line between title and workspace; rows without a useful - conversation line do not reserve space. - -## Verification - -Verdict: verified. - -### Acceptance evidence - -- AC-1: PASS — `bun test apps/desktop/tests/sidebarSections.test.ts apps/desktop/tests/sessionRailRendered.test.tsx` covered cross-project active and archived visibility. -- AC-2: PASS — the focused tests and real renderer confirmed one globally recency-sorted unassigned feed with Project metadata. Evidence: `Verification record above`. -- AC-3: PASS — focused Section-precedence coverage verified the deterministic Highlight membership rules. Evidence: `Verification record above`. -- AC-4: PASS — recorded pointer and context-menu QA exercised create, rename, delete, fold, unfold, assign, and unassign actions. Evidence: `Verification record above`. -- AC-5: PASS — `sidebarSections.test.ts` covered persistence, fail-closed parsing, and Task preservation after Section deletion. -- AC-6: PASS — 320px and 220px renderer measurements verified disclosure semantics and the common 16px title baseline. Evidence: `Verification record above`. -- AC-7: PASS — real renderer inspection confirmed the Recent/Project header and inline add control were absent without blank space. Evidence: `Verification record above`. -- AC-8: PASS — `sessionRailRendered.test.tsx` retained selection, rename, pin, archive/restore, and context-menu behavior without duplicates. -- AC-9: PASS — the focused test command, `bun run build:renderer`, `bun script/verify/sdlc.ts`, and real light/dark/narrow inspection passed after the recorded failed CI iteration was corrected. - -- PR #183's first cross-platform desktop run failed on Linux, macOS, and Windows in the explicit - Section-precedence test. The complete suite left an intentionally partial Canvas context in the - shared DOM, and the test's running Task then mounted ActivityOrb against that stub. The focused - suite had passed because it did not include the polluting Canvas tests. The existing test now - disables Canvas drawing within its own boundary before rendering the running Task. -- `bun test apps/desktop/tests/sidebarSections.test.ts apps/desktop/tests/sessionRailRendered.test.tsx` - passed: 20 tests, 195 expectations, 0 failures. -- `bun run build:renderer` passed TypeScript, Vite production rendering, the source design-system - gate with 0 new violations, and the built-selector design-system gate. -- `bun script/verify/sdlc.ts` revalidated the migrated Artifact with `[sdlc] contract valid`. -- Renderer-only QA used isolated port 1421 and did not launch a second Core. Browser inspection - confirmed the Recent label, Project switcher, and inline add control were absent, with Highlight - becoming the first visible Task control and no blank placeholder above it. -- Real pointer/keyboard inspection confirmed Highlight folding, manual Section creation, - persistence after reload, the Section context submenu, and moving an unsectioned Task into a - manual Section. A fresh dark-mode tab reported no console warnings or errors. -- Screenshots and layout measurements covered light and dark at 320 pixels and the minimum - 220-pixel rail. At the minimum width every Task row measured 204 CSS pixels of client and scroll - width, with no horizontal overflow. Highlight still folded by pointer input, hid only its own - Task, and left the following manual Section visible. -- Follow-up alignment inspection measured the Highlight title, manual Work title, grouped Task - title, and flat Task title at the same 16 CSS-pixel left edge at both 320- and 220-pixel rail - widths. The narrow rail had no horizontal overflow, and folding Work removed only its rows. - -Residual risk: Section state remains renderer-local and the recorded UI checks do not establish -cross-device synchronization, which was explicitly outside this change. - -## Review and release - -Approval: the user explicitly authorized creating and merging the repository pull request on -2026-08-30. -Release target: none; this was a repository integration, not a versioned product release. -Rollback: revert merge commit `e3744874` and its PR #183 implementation commits. -No release: [PR #183](https://github.com/IchenDEV/codeTwo/pull/183) was observed on `origin/main` as -merge commit `e3744874`; no versioned package or deployment was requested. - -## Feedback - -The follow-up renderer matches the supplied deletion request: the redundant heading/project bar is -gone, organization begins directly with title-adjacent Section disclosures, status remains quiet, -and the optional middle conversation line collapses away when there is no useful content. A later -visual review found Section headings were eight pixels too far right; system, manual, empty, and -creation states now share the Task-title baseline without moving trailing Section actions. diff --git a/docs/sdlc/changes/2026-08-30-flat-task-sections/intent.md b/docs/sdlc/changes/2026-08-30-flat-task-sections/intent.md new file mode 100644 index 00000000..2e2d3d9d --- /dev/null +++ b/docs/sdlc/changes/2026-08-30-flat-task-sections/intent.md @@ -0,0 +1,65 @@ +--- +id: "2026-08-30-flat-task-sections" +stage: intent +schema: 3 +status: accepted +owner: codex +created: 2026-08-30 +source: user-supplied sidebar references and PR #183 +risk: medium +approved_by: "userthe 2026-08-30 sidebar requests and explicit PR merge authorization" +approved_at: "2026-08-30" +--- + +# Intent: Flatten recent Tasks and add sidebar Sections + +## Problem + +The user supplied three macOS sidebar references on 2026-08-30 and asked that recent Tasks stop +being grouped or filtered by Project/folder. Tasks should appear in one cross-project feed, with +optional Sections as the only organizational layer. Users need to create and manage their own +Sections, while the system may maintain explainable automatic Sections. Disclosure controls should +sit immediately after each Section title as in the supplied references. + +In a follow-up reference on the same date, the user explicitly removed the entire redundant +`Recent chats`/Project-switcher row. The Task area now begins directly with Highlight, manual +Sections, or flat Tasks; Section creation remains available from a Task's context menu. + +The affected surface is the desktop SessionRail and its local organization state. This change does +not alter Task ownership, Project selection for new work, working directories, provider Sessions, +archive semantics, or any external system. The direct user request is accepted Intent and design +approval; it does not authorize a PR, merge, release, or production mutation. + +## Proposed outcome + +The user supplied three macOS sidebar references on 2026-08-30 and asked that recent Tasks stop + +## Affected users and systems + +Migrated from legacy change.md. + +## Constraints + +The user's request accepts the Intent and visible design. The implementation uses deterministic +automatic grouping so the system cannot silently reclassify work by model inference. Local UI +persistence matches existing rail width/fold preferences and avoids changing Core Task data. Human +review remains the next gate after verification. + +## Out of scope + +Not recorded in the legacy single-file Artifact. + +## Success signals + +See Spec acceptance criteria. + +## Open questions + +None recorded in migration. + +## Decision + +The user's request accepts the Intent and visible design. The implementation uses deterministic +automatic grouping so the system cannot silently reclassify work by model inference. Local UI +persistence matches existing rail width/fold preferences and avoids changing Core Task data. Human +review remains the next gate after verification. diff --git a/docs/sdlc/changes/2026-08-30-flat-task-sections/plan.md b/docs/sdlc/changes/2026-08-30-flat-task-sections/plan.md new file mode 100644 index 00000000..37ca4097 --- /dev/null +++ b/docs/sdlc/changes/2026-08-30-flat-task-sections/plan.md @@ -0,0 +1,68 @@ +--- +id: "2026-08-30-flat-task-sections" +stage: plan +schema: 3 +status: accepted +owner: codex +created: 2026-08-30 +based_on: spec.md +risk: medium +scope: apps/desktop +approved_by: "userthe 2026-08-30 sidebar requests and explicit PR merge authorization" +approved_at: "2026-08-30" +--- + +# Plan: Flatten recent Tasks and add sidebar Sections + +## Files and ownership + +apps/desktop + +## Order of work + +1. Add a small versioned Task Section state module with defensive parsing and pure create, rename, + assign, fold, and delete operations. +2. Replace active-Project filtering and Pinned/Active partitions with cross-project sorting, + automatic Highlight, manual Section folds, and a flat remainder in SessionRail. +3. Add native and rendered context-menu Section assignment plus quiet inline Section management; + remove the redundant Recent/Project header after the user's follow-up direction. +4. Protect persistence, precedence, ordering, disclosure placement, and existing actions with + focused tests; verify the real renderer in light, dark, standard, and minimum rail widths. + +Rollback removes the local Section state module and restores the prior active-Project list +partition. Stored UI organization is versioned and ignored by older builds. + +## Test-first proof + +See legacy Verification section. + +## Visual or integration proof + +See legacy Verification section. + +## Risks and mitigations + +See legacy Decision and gates. + +## Rollback + +See legacy Review and release. + +## Deviations + +- Added a versioned, local `sidebarSections` state module with defensive parsing and pure + create/rename/assign/fold/delete operations. +- Reworked SessionRail into an all-Project Task feed with deterministic Highlight, manual + Sections, a flat remainder, and a global Archived fold. +- Added native and rendered Section submenus plus quiet inline Section creation and management. +- Removed the entire Recent/Project-switcher row and its inline Section-add button. Section + creation remains contextual to the Task being organized. +- Kept the optional recent-conversation line between title and workspace; rows without a useful + conversation line do not reserve space. + +## Decision + +The user's request accepts the Intent and visible design. The implementation uses deterministic +automatic grouping so the system cannot silently reclassify work by model inference. Local UI +persistence matches existing rail width/fold preferences and avoids changing Core Task data. Human +review remains the next gate after verification. diff --git a/docs/sdlc/changes/2026-08-30-flat-task-sections/spec.md b/docs/sdlc/changes/2026-08-30-flat-task-sections/spec.md new file mode 100644 index 00000000..ab0db4fb --- /dev/null +++ b/docs/sdlc/changes/2026-08-30-flat-task-sections/spec.md @@ -0,0 +1,79 @@ +--- +id: "2026-08-30-flat-task-sections" +stage: spec +schema: 3 +status: accepted +owner: codex +created: 2026-08-30 +based_on: intent.md +risk: medium +approved_by: "userthe 2026-08-30 sidebar requests and explicit PR merge authorization" +approved_at: "2026-08-30" +--- + +# Spec: Flatten recent Tasks and add sidebar Sections + +## Requirements + +The Task surface is globally sorted across every Project. It has no separate Recent heading or +Project switcher. Project identity remains quiet row context, not a list partition. Unsectioned +Tasks remain a flat feed. A Task may have at most one explicit user Section. Explicit membership +wins over automatic grouping. + +`Highlight` is the first system Section. It automatically contains unassigned Tasks that are +pinned, running, awaiting input, or failed. `Archived` remains a system-owned fold. Manual Sections +can be created, renamed, folded, deleted, and selected from a Task context-menu submenu. Deleting a +Section returns its Tasks to automatic/flat placement; no Task is deleted. Section names, +assignments, order, and folded state persist as local UI organization. Semantic model-driven +clustering, cross-device synchronization, and drag reordering are non-goals for this change. + +## User experience + +Not separately recorded in legacy change.md. + +## Technical design + +See Requirements and legacy Git history. + +## Security and privacy + +See migrated Decision and gates. + +## Alternatives and non-goals + +Not separately recorded in legacy change.md. + +## Areas of concern + +The user's request accepts the Intent and visible design. The implementation uses deterministic +automatic grouping so the system cannot silently reclassify work by model inference. Local UI +persistence matches existing rail width/fold preferences and avoids changing Core Task data. Human +review remains the next gate after verification. + +## Acceptance criteria + +- [x] AC-1: Active and archived Tasks from different Projects are available without changing the active + Project, and no Project/folder headings partition the Task list. +- [x] AC-2: Unassigned idle Tasks remain one globally recency-sorted flat feed with their Project shown + only as row metadata. +- [x] AC-3: The automatic `Highlight` Section contains only unassigned pinned, running, awaiting-input, + or failed Tasks; explicit user Section membership takes precedence. +- [x] AC-4: Users can create, rename, delete, fold, and unfold manual Sections and move a Task into a + Section or back to no Section from its context menu. +- [x] AC-5: Manual Section state survives a renderer remount, invalid stored data fails closed to an + empty organization, and deleting a Section preserves every Task. +- [x] AC-6: Each disclosure chevron appears immediately after its Section title, communicates expanded + state, and works with pointer and keyboard input in light, dark, and the 220-pixel rail. Each + Section title shares the same 16-pixel left baseline as Task titles. +- [x] AC-7: The redundant Recent/Project header and its inline add control do not render; the list begins + directly with a Section or Task without reserving empty space. +- [x] AC-8: Existing select, rename, pin, archive/restore, and context-menu behavior remains available + without duplicating Tasks between Sections. +- [x] AC-9: Focused tests, renderer/design build, SDLC check, and real renderer inspection pass. + +## Decision + +The user's request accepts the Intent and visible design. The implementation uses deterministic +automatic grouping so the system cannot silently reclassify work by model inference. Local UI +persistence matches existing rail width/fold preferences and avoids changing Core Task data. Human +review remains the next gate after verification. diff --git a/docs/sdlc/changes/2026-08-30-flat-task-sections/verification.md b/docs/sdlc/changes/2026-08-30-flat-task-sections/verification.md new file mode 100644 index 00000000..8ffaf8bc --- /dev/null +++ b/docs/sdlc/changes/2026-08-30-flat-task-sections/verification.md @@ -0,0 +1,136 @@ +--- +id: "2026-08-30-flat-task-sections" +stage: verification +schema: 3 +status: passed +owner: codex +created: 2026-08-30 +based_on: plan.md +commit: "" +verification_mode: owner +verified_by: "codex" +verified_at: "2026-08-30" +release_target: none; this was a repository integration, not a versioned product release +release_identity: "" +--- + +# Verification: Flatten recent Tasks and add sidebar Sections + +## Automated checks + +Verdict: verified. + +### Acceptance evidence + +- AC-1: PASS — `bun test apps/desktop/tests/sidebarSections.test.ts apps/desktop/tests/sessionRailRendered.test.tsx` covered cross-project active and archived visibility. +- AC-2: PASS — the focused tests and real renderer confirmed one globally recency-sorted unassigned feed with Project metadata. Evidence: `Verification record above`. +- AC-3: PASS — focused Section-precedence coverage verified the deterministic Highlight membership rules. Evidence: `Verification record above`. +- AC-4: PASS — recorded pointer and context-menu QA exercised create, rename, delete, fold, unfold, assign, and unassign actions. Evidence: `Verification record above`. +- AC-5: PASS — `sidebarSections.test.ts` covered persistence, fail-closed parsing, and Task preservation after Section deletion. +- AC-6: PASS — 320px and 220px renderer measurements verified disclosure semantics and the common 16px title baseline. Evidence: `Verification record above`. +- AC-7: PASS — real renderer inspection confirmed the Recent/Project header and inline add control were absent without blank space. Evidence: `Verification record above`. +- AC-8: PASS — `sessionRailRendered.test.tsx` retained selection, rename, pin, archive/restore, and context-menu behavior without duplicates. +- AC-9: PASS — the focused test command, `bun run build:renderer`, `bun script/verify/sdlc.ts`, and real light/dark/narrow inspection passed after the recorded failed CI iteration was corrected. + +- PR #183's first cross-platform desktop run failed on Linux, macOS, and Windows in the explicit + Section-precedence test. The complete suite left an intentionally partial Canvas context in the + shared DOM, and the test's running Task then mounted ActivityOrb against that stub. The focused + suite had passed because it did not include the polluting Canvas tests. The existing test now + disables Canvas drawing within its own boundary before rendering the running Task. +- `bun test apps/desktop/tests/sidebarSections.test.ts apps/desktop/tests/sessionRailRendered.test.tsx` + passed: 20 tests, 195 expectations, 0 failures. +- `bun run build:renderer` passed TypeScript, Vite production rendering, the source design-system + gate with 0 new violations, and the built-selector design-system gate. +- `bun script/verify/sdlc.ts` revalidated the migrated Artifact with `[sdlc] contract valid`. +- Renderer-only QA used isolated port 1421 and did not launch a second Core. Browser inspection + confirmed the Recent label, Project switcher, and inline add control were absent, with Highlight + becoming the first visible Task control and no blank placeholder above it. +- Real pointer/keyboard inspection confirmed Highlight folding, manual Section creation, + persistence after reload, the Section context submenu, and moving an unsectioned Task into a + manual Section. A fresh dark-mode tab reported no console warnings or errors. +- Screenshots and layout measurements covered light and dark at 320 pixels and the minimum + 220-pixel rail. At the minimum width every Task row measured 204 CSS pixels of client and scroll + width, with no horizontal overflow. Highlight still folded by pointer input, hid only its own + Task, and left the following manual Section visible. +- Follow-up alignment inspection measured the Highlight title, manual Work title, grouped Task + title, and flat Task title at the same 16 CSS-pixel left edge at both 320- and 220-pixel rail + widths. The narrow rail had no horizontal overflow, and folding Work removed only its rows. + +Residual risk: Section state remains renderer-local and the recorded UI checks do not establish +cross-device synchronization, which was explicitly outside this change. + +## Behavioral evidence + +Verdict: verified. + +### Acceptance evidence + +- AC-1: PASS — `bun test apps/desktop/tests/sidebarSections.test.ts apps/desktop/tests/sessionRailRendered.test.tsx` covered cross-project active and archived visibility. +- AC-2: PASS — the focused tests and real renderer confirmed one globally recency-sorted unassigned feed with Project metadata. Evidence: `Verification record above`. +- AC-3: PASS — focused Section-precedence coverage verified the deterministic Highlight membership rules. Evidence: `Verification record above`. +- AC-4: PASS — recorded pointer and context-menu QA exercised create, rename, delete, fold, unfold, assign, and unassign actions. Evidence: `Verification record above`. +- AC-5: PASS — `sidebarSections.test.ts` covered persistence, fail-closed parsing, and Task preservation after Section deletion. +- AC-6: PASS — 320px and 220px renderer measurements verified disclosure semantics and the common 16px title baseline. Evidence: `Verification record above`. +- AC-7: PASS — real renderer inspection confirmed the Recent/Project header and inline add control were absent without blank space. Evidence: `Verification record above`. +- AC-8: PASS — `sessionRailRendered.test.tsx` retained selection, rename, pin, archive/restore, and context-menu behavior without duplicates. +- AC-9: PASS — the focused test command, `bun run build:renderer`, `bun script/verify/sdlc.ts`, and real light/dark/narrow inspection passed after the recorded failed CI iteration was corrected. + +- PR #183's first cross-platform desktop run failed on Linux, macOS, and Windows in the explicit + Section-precedence test. The complete suite left an intentionally partial Canvas context in the + shared DOM, and the test's running Task then mounted ActivityOrb against that stub. The focused + suite had passed because it did not include the polluting Canvas tests. The existing test now + disables Canvas drawing within its own boundary before rendering the running Task. +- `bun test apps/desktop/tests/sidebarSections.test.ts apps/desktop/tests/sessionRailRendered.test.tsx` + passed: 20 tests, 195 expectations, 0 failures. +- `bun run build:renderer` passed TypeScript, Vite production rendering, the source design-system + gate with 0 new violations, and the built-selector design-system gate. +- `bun script/verify/sdlc.ts` revalidated the migrated Artifact with `[sdlc] contract valid`. +- Renderer-only QA used isolated port 1421 and did not launch a second Core. Browser inspection + confirmed the Recent label, Project switcher, and inline add control were absent, with Highlight + becoming the first visible Task control and no blank placeholder above it. +- Real pointer/keyboard inspection confirmed Highlight folding, manual Section creation, + persistence after reload, the Section context submenu, and moving an unsectioned Task into a + manual Section. A fresh dark-mode tab reported no console warnings or errors. +- Screenshots and layout measurements covered light and dark at 320 pixels and the minimum + 220-pixel rail. At the minimum width every Task row measured 204 CSS pixels of client and scroll + width, with no horizontal overflow. Highlight still folded by pointer input, hid only its own + Task, and left the following manual Section visible. +- Follow-up alignment inspection measured the Highlight title, manual Work title, grouped Task + title, and flat Task title at the same 16 CSS-pixel left edge at both 320- and 220-pixel rail + widths. The narrow rail had no horizontal overflow, and folding Work removed only its rows. + +Residual risk: Section state remains renderer-local and the recorded UI checks do not establish +cross-device synchronization, which was explicitly outside this change. + +## Visual evidence + +See bundle evidence/ when present. + +## Security and privacy evidence + +Not separately recorded unless present in legacy Verification. + +## Deviations and residual risk + +Residual risk: Section state remains renderer-local and the recorded UI checks do not establish + +## Verdict + +Verdict: verified.. + +## Review and release + +Approval: the user explicitly authorized creating and merging the repository pull request on +2026-08-30. +Release target: none; this was a repository integration, not a versioned product release. +Rollback: revert merge commit `e3744874` and its PR #183 implementation commits. +No release: [PR #183](https://github.com/IchenDEV/codeTwo/pull/183) was observed on `origin/main` as +merge commit `e3744874`; no versioned package or deployment was requested. + +## Feedback + +The follow-up renderer matches the supplied deletion request: the redundant heading/project bar is +gone, organization begins directly with title-adjacent Section disclosures, status remains quiet, +and the optional middle conversation line collapses away when there is no useful content. A later +visual review found Section headings were eight pixels too far right; system, manual, empty, and +creation states now share the Task-title baseline without moving trailing Section actions. diff --git a/docs/sdlc/changes/2026-08-30-memory-settings-redesign/intent.md b/docs/sdlc/changes/2026-08-30-memory-settings-redesign/intent.md new file mode 100644 index 00000000..459f4d56 --- /dev/null +++ b/docs/sdlc/changes/2026-08-30-memory-settings-redesign/intent.md @@ -0,0 +1,53 @@ +--- +id: "2026-08-30-memory-settings-redesign" +stage: intent +schema: 3 +status: accepted +owner: codex +created: 2026-08-30 +source: #intent +risk: low +approved_by: "#decision-and-gates" +approved_at: "2026-08-30" +--- + +# Intent: Redesign the Memory settings workspace + +## Problem + +The user supplied a rendered Memory settings screenshot and asked for the page to be redesigned +because its hierarchy is cluttered and inconsistent with adjacent settings pages. The desired +outcome is a restrained macOS settings surface that preserves the existing Memory workflows while +making the page header, behavior summary, filters, list, and inspector read as one coherent system. +The user explicitly requested an ImageGen design pass before implementation and rejected a +flamboyant visual direction. + +## Proposed outcome + +The user supplied a rendered Memory settings screenshot and asked for the page to be redesigned + +## Affected users and systems + +Migrated from legacy change.md. + +## Constraints + +Intent and design direction are accepted by the user's 2026-08-30 implementation request and +attached screenshot. No permission to create a PR, merge, publish, or release is implied. + +## Out of scope + +Not recorded in the legacy single-file Artifact. + +## Success signals + +See Spec acceptance criteria. + +## Open questions + +None recorded in migration. + +## Decision + +Intent and design direction are accepted by the user's 2026-08-30 implementation request and +attached screenshot. No permission to create a PR, merge, publish, or release is implied. diff --git a/docs/sdlc/changes/2026-08-30-memory-settings-redesign/plan.md b/docs/sdlc/changes/2026-08-30-memory-settings-redesign/plan.md new file mode 100644 index 00000000..5ebda0ac --- /dev/null +++ b/docs/sdlc/changes/2026-08-30-memory-settings-redesign/plan.md @@ -0,0 +1,56 @@ +--- +id: "2026-08-30-memory-settings-redesign" +stage: plan +schema: 3 +status: accepted +owner: codex +created: 2026-08-30 +based_on: spec.md +risk: low +scope: apps/desktop, docs/design/system.md +approved_by: "#decision-and-gates" +approved_at: "2026-08-30" +--- + +# Plan: Redesign the Memory settings workspace + +## Files and ownership + +apps/desktop, docs/design/system.md + +## Order of work + +Reuse the shared page header, introduce one workbench wrapper around the existing controls and +panes, express its geometry in the existing layout specification, and restyle only the Memory +surface. Preserve data loading, editing, batch actions, policy controls, and dialog behavior. Add a +focused layout contract, then verify the running renderer against the ImageGen concept in light, +dark, standard, and narrow states. Rollback is the inverse source change. + +## Test-first proof + +See legacy Verification section. + +## Visual or integration proof + +See legacy Verification section. + +## Risks and mitigations + +See legacy Decision and gates. + +## Rollback + +See legacy Review and release. + +## Deviations + +The Memory page now composes the shared `PageHeader`, a flat policy disclosure, and one workbench +containing status, views, filters, list, and inspector. The workbench uses semantic hairlines and a +neutral inspector surface. Standard width keeps all eight views on one row; at 800px and below, +status and view controls wrap while filters use two columns. Data loading, policy controls, batch +actions, editing, and the existing narrow detail dialog are unchanged. + +## Decision + +Intent and design direction are accepted by the user's 2026-08-30 implementation request and +attached screenshot. No permission to create a PR, merge, publish, or release is implied. diff --git a/docs/sdlc/changes/2026-08-30-memory-settings-redesign/spec.md b/docs/sdlc/changes/2026-08-30-memory-settings-redesign/spec.md new file mode 100644 index 00000000..f96de3aa --- /dev/null +++ b/docs/sdlc/changes/2026-08-30-memory-settings-redesign/spec.md @@ -0,0 +1,63 @@ +--- +id: "2026-08-30-memory-settings-redesign" +stage: spec +schema: 3 +status: accepted +owner: codex +created: 2026-08-30 +based_on: intent.md +risk: low +approved_by: "#decision-and-gates" +approved_at: "2026-08-30" +--- + +# Spec: Redesign the Memory settings workspace + +## Requirements + +The task-session ImageGen concept `exec-7d022327-2e17-4113-bd6f-e80b78207060.png` is the visual +reference. Keep the repository's 768px settings content column and semantic design tokens. Reuse +the shared page-header anatomy, retain one flat behavior disclosure, and group status, views, +filters, list, and details inside one workbench surface. Use semantic hairlines for structure, +reserve blue for interactive emphasis, and give the list and inspector the same neutral surface. +Keep all eight existing view buttons and use compact spacing so the final Conflicts view remains +reachable without changing the filter contract. + +At viewport widths at or below 1024px, keep the existing list-only layout and detail dialog. At +800px and below, stack the page header actions and use the existing compact two-column filter grid. + +## User experience + +Not separately recorded in legacy change.md. + +## Technical design + +See Requirements and legacy Git history. + +## Security and privacy + +See migrated Decision and gates. + +## Alternatives and non-goals + +Not separately recorded in legacy change.md. + +## Areas of concern + +Intent and design direction are accepted by the user's 2026-08-30 implementation request and +attached screenshot. No permission to create a PR, merge, publish, or release is implied. + +## Acceptance criteria + +- [x] AC-1: The Memory page uses the shared page header and aligns project selection with New memory. +- [x] AC-2: Memory behavior remains expandable and visually subordinate to the main workbench. +- [x] AC-3: Status, views, search, filters, list, and inspector form one flat grouped surface. +- [x] AC-4: The empty inspector no longer uses a blue-tinted panel and both empty states are centered. +- [x] AC-5: All existing filter modes remain reachable, including conflicts through Needs attention. +- [x] AC-6: Standard, narrow, light, and dark rendered states have no clipping or horizontal overflow. +- [x] AC-7: Focused behavior, layout, design-system, renderer, SDLC, and diff checks pass. + +## Decision + +Intent and design direction are accepted by the user's 2026-08-30 implementation request and +attached screenshot. No permission to create a PR, merge, publish, or release is implied. diff --git a/docs/sdlc/changes/2026-08-30-memory-settings-redesign/change.md b/docs/sdlc/changes/2026-08-30-memory-settings-redesign/verification.md similarity index 50% rename from docs/sdlc/changes/2026-08-30-memory-settings-redesign/change.md rename to docs/sdlc/changes/2026-08-30-memory-settings-redesign/verification.md index 7b8aa6ea..6af8590f 100644 --- a/docs/sdlc/changes/2026-08-30-memory-settings-redesign/change.md +++ b/docs/sdlc/changes/2026-08-30-memory-settings-redesign/verification.md @@ -1,80 +1,63 @@ --- -id: change-2026-08-30-memory-settings-redesign -kind: change -schema: 2 -status: verified -risk: low +id: "2026-08-30-memory-settings-redesign" +stage: verification +schema: 3 +status: passed owner: codex -approvers: "#decision-and-gates" -approved_at: 2026-08-30 created: 2026-08-30 -updated: 2026-08-31 -source: "#intent" -inputs: "#spec" -outputs: "#build" -scope: apps/desktop, docs/design/system.md -next_trigger: PR #182 merge verification +based_on: plan.md +commit: "" verification_mode: owner -verified_by: codex -verified_at: 2026-08-30 +verified_by: "codex" +verified_at: "2026-08-30" +release_target: none +release_identity: "" --- -# Redesign the Memory settings workspace +# Verification: Redesign the Memory settings workspace -## Intent +## Automated checks -The user supplied a rendered Memory settings screenshot and asked for the page to be redesigned -because its hierarchy is cluttered and inconsistent with adjacent settings pages. The desired -outcome is a restrained macOS settings surface that preserves the existing Memory workflows while -making the page header, behavior summary, filters, list, and inspector read as one coherent system. -The user explicitly requested an ImageGen design pass before implementation and rejected a -flamboyant visual direction. - -## Spec - -The task-session ImageGen concept `exec-7d022327-2e17-4113-bd6f-e80b78207060.png` is the visual -reference. Keep the repository's 768px settings content column and semantic design tokens. Reuse -the shared page-header anatomy, retain one flat behavior disclosure, and group status, views, -filters, list, and details inside one workbench surface. Use semantic hairlines for structure, -reserve blue for interactive emphasis, and give the list and inspector the same neutral surface. -Keep all eight existing view buttons and use compact spacing so the final Conflicts view remains -reachable without changing the filter contract. - -At viewport widths at or below 1024px, keep the existing list-only layout and detail dialog. At -800px and below, stack the page header actions and use the existing compact two-column filter grid. - -### Acceptance criteria - -- [x] AC-1: The Memory page uses the shared page header and aligns project selection with New memory. -- [x] AC-2: Memory behavior remains expandable and visually subordinate to the main workbench. -- [x] AC-3: Status, views, search, filters, list, and inspector form one flat grouped surface. -- [x] AC-4: The empty inspector no longer uses a blue-tinted panel and both empty states are centered. -- [x] AC-5: All existing filter modes remain reachable, including conflicts through Needs attention. -- [x] AC-6: Standard, narrow, light, and dark rendered states have no clipping or horizontal overflow. -- [x] AC-7: Focused behavior, layout, design-system, renderer, SDLC, and diff checks pass. - -## Decision and gates - -Intent and design direction are accepted by the user's 2026-08-30 implementation request and -attached screenshot. No permission to create a PR, merge, publish, or release is implied. +- `bun test tests/settingsLayoutContract.test.ts tests/settingsMemoryPolicyRendered.test.tsx` — + 20 passed, 0 failed. The existing Base UI harness emitted non-failing `act(...)` warnings. +- `bun run check:design` — passed with 0 new violations; legacy debt remains 657. +- `bun run build:renderer` — passed design-source checks, TypeScript, Vite production build, and + generated-design checks. The existing large-chunk advisory remains non-failing. +- In-app Browser at `http://127.0.0.1:1420/` — verified meaningful Memory content, no framework + overlay, and no console warnings or errors at 1280x720 light and dark, 800x600 narrow dark, and + the ImageGen concept's native 1536x1024 size. +- At 1280px, the 704px workbench had zero internal or body overflow, all eight view buttons were + visible, and the detail pane remained inline. At 800px, the 461px workbench, view row, and status + row each had matching client and scroll widths; all eight views were inside the wrapper, filters + rendered in two columns, and details moved to the existing dialog path. +- Selecting Pinned changed its `aria-pressed` state to `true`, cleared All to `false`, preserved the + zero-result state, and produced no console errors. The browser appearance was restored to System + and the temporary viewport override was reset after QA. +- After human review identified rounded ends on the selected-view underline, the inset button + shadow was replaced by an independent 2px indicator. In-app Browser computed its `::after` + radius as `0px` and the rendered 1280x720 screenshot showed square ends under All. +- ImageGen fidelity review covered copy, hierarchy, type, palette, icons, spacing, surface model, + and responsive behavior. Above-the-fold copy is unchanged. The implementation intentionally + retains the repository's 768px settings column and persisted sidebar width instead of the + concept image's over-wide shell rendering; no other material visual mismatch remains. +- `bun script/verify/sdlc.ts` — passed; task-scoped `git diff --check` — passed. -## Plan +Verdict: verified. -Reuse the shared page header, introduce one workbench wrapper around the existing controls and -panes, express its geometry in the existing layout specification, and restyle only the Memory -surface. Preserve data loading, editing, batch actions, policy controls, and dialog behavior. Add a -focused layout contract, then verify the running renderer against the ImageGen concept in light, -dark, standard, and narrow states. Rollback is the inverse source change. +### Acceptance evidence -## Build +- AC-1: PASS — rendered inspection and focused layout coverage verified the shared page header and aligned project/action controls. Evidence: `Verification record above`. +- AC-2: PASS — the recorded light/dark screenshots retain the subordinate expandable Memory behavior disclosure. Evidence: `Verification record above`. +- AC-3: PASS — `bun test tests/settingsLayoutContract.test.ts tests/settingsMemoryPolicyRendered.test.tsx` covered the grouped workbench structure. +- AC-4: PASS — rendered inspection verified neutral centered list and inspector empty states. Evidence: `Verification record above`. +- AC-5: PASS — focused rendered tests and interaction QA kept all eight views and Needs attention reachable. Evidence: `Verification record above`. +- AC-6: PASS — the 1280px, 800px, and 1536px light/dark matrix recorded zero clipping and horizontal overflow. Evidence: `Verification record above`. +- AC-7: PASS — focused tests, `bun run check:design`, `bun run build:renderer`, `bun script/verify/sdlc.ts`, and `git diff --check` passed. -The Memory page now composes the shared `PageHeader`, a flat policy disclosure, and one workbench -containing status, views, filters, list, and inspector. The workbench uses semantic hairlines and a -neutral inspector surface. Standard width keeps all eight views on one row; at 800px and below, -status and view controls wrap while filters use two columns. Data loading, policy controls, batch -actions, editing, and the existing narrow detail dialog are unchanged. +Residual risk: verification covers the recorded desktop viewport matrix and repository design +contract; no versioned release or external production observation was requested. -## Verification +## Behavioral evidence - `bun test tests/settingsLayoutContract.test.ts tests/settingsMemoryPolicyRendered.test.tsx` — 20 passed, 0 failed. The existing Base UI harness emitted non-failing `act(...)` warnings. @@ -115,6 +98,22 @@ Verdict: verified. Residual risk: verification covers the recorded desktop viewport matrix and repository design contract; no versioned release or external production observation was requested. +## Visual evidence + +See bundle evidence/ when present. + +## Security and privacy evidence + +Not separately recorded unless present in legacy Verification. + +## Deviations and residual risk + +Residual risk: verification covers the recorded desktop viewport matrix and repository design + +## Verdict + +Verdict: verified.. + ## Review and release PR [#182](https://github.com/IchenDEV/codeTwo/pull/182) contains the verified change. The user's diff --git a/docs/sdlc/changes/2026-08-30-plugin-connectors/change.md b/docs/sdlc/changes/2026-08-30-plugin-connectors/change.md deleted file mode 100644 index f3562914..00000000 --- a/docs/sdlc/changes/2026-08-30-plugin-connectors/change.md +++ /dev/null @@ -1,208 +0,0 @@ ---- -id: change-2026-08-30-plugin-connectors -kind: change -schema: 2 -status: executing -risk: high -owner: codex -approvers: chenli -approved_at: 2026-08-30 -created: 2026-08-30 -updated: 2026-08-31 -source: user request in this task, "需要提升扩展plugin 模型" -inputs: the C2 process runtime model, host-rendered UI contributions, and the Feishu collaboration extension -outputs: a manifest-declared connector contribution invoked through one owned runtime command -scope: community/plugins/feishu, apps/desktop, crates/plugins, docs/reference/plugin-standard.md -next_trigger: free or isolate port 1420 from the separate /Users/chenli/projects/codeTwo renderer and rerun real-window verification -verification_mode: independent -verified_by: pending -verified_at: pending ---- - -# Add connector contributions to the extension model - -## Intent - -The Feishu collaboration experience currently depends on the desktop recognizing one installed -bundle by name and calling its `feishu.*` commands directly. That makes a community extension look -integrated while keeping its discovery and routing inside product-specific host code. The user -requested a stronger extension model so rich collaboration integrations remain community plugins. - -## Spec - -C2 Plugin Standard 1.2 adds host-rendered connector descriptors. A connector declares only a stable -bundle-local id, a provider identifier, one command owned by the same runtime, and the capabilities -that are implemented now. The host invokes that command with an operation and input; the -bundle owns provider-specific authentication and data access. Connector code cannot inject React or -HTML and cannot invoke another bundle's command. - -The initial capabilities cover connection, conversations, documents, tables, messaging, and turn -notifications. The existing Feishu surface becomes the first provider adapter: it is discovered -through the descriptor rather than the bundle name, and all host calls pass through the connector -invocation command. A connector for another provider cannot be rendered by the Feishu adapter. -Only C2 Plugin Standard 1.2 bundles and installed records are accepted. - -### Acceptance criteria - -- [x] AC-1: A valid 1.2 bundle can declare a connector whose command is statically declared by the same - runtime; unknown capabilities, commands, fields, and duplicate ids fail closed. -- [x] AC-2: C2 accepts only Plugin Standard 1.2; 1.0 and 1.1 manifests and installed records fail closed. -- [x] AC-3: Installed bundle inventory, catalog counts, and desktop bridge expose connector - descriptors without starting an untrusted runtime. -- [x] AC-4: Connector invocation verifies enabled/trusted state, contribution ownership, command ownership, - and caller realm before dispatching `{ operation, input }`. -- [x] AC-5: The desktop discovers the Feishu collaboration surface from an active connector and contains no - plugin-name check or direct `feishu.*` command call for that surface. -- [x] AC-6: The community Feishu bundle declares the connector and implements its single operation dispatcher - as its only public runtime command. -- [x] AC-7: Before Feishu authorization, the rail shows no contact, document, or Base groups; it presents - only a concise sign-in prompt whose action opens the Feishu bundle's plugin settings. -- [x] AC-8: Feishu app setup and account authorization live in the Feishu plugin details rather than the - collaboration workspace; successful authorization restores the existing resource directory. -- [ ] AC-9: The authorization boundary is covered in English and Chinese and checked in the rendered desktop. -- [x] AC-10: Conversation messages render the sender display name and avatar resolved by the connector; internal - Feishu identifiers appear only as a last-resort fallback when no user profile is available. -- [ ] AC-11: Focused Rust, renderer, community-plugin, build, SDLC, and real-window checks pass. - -## Decision and gates - -The user's direct implementation request approves this Intent and Spec, with chenli as the named -approver. The user later authorized PR #185 and explicitly authorized its merge on 2026-08-31. -No publication, deployment, or release is authorized. - -## Plan - -Extend the manifest parser and installed model, add one ownership-checked connector invocation command, -project active descriptors into the renderer, migrate Feishu discovery and calls to that seam, and add -contract tests at the parser, runtime, bridge, and rendered-surface levels. Rollback removes the 1.2 -descriptor support and restores the previous Feishu-specific host lookup. - -For the authorization state, keep provider controls host-rendered but mount them only inside the owning -bundle's plugin details. The collaboration rail is a resource directory after authorization, not a -second setup surface. - -## Build - -- Added the 1.2 manifest, installed-bundle, inventory, catalog, validation CLI, - bridge, and localization contracts for connector contributions. -- Added `plugins.invoke_connector`, which checks bundle enablement and trust, contribution and command - ownership, runtime realm, input shape, and capability-to-operation namespace before dispatching the - standard `{ operation, input }` envelope. -- Moved the Feishu desktop surface to active connector discovery with `provider: feishu`; all - provider calls now use standard operations through the connector facade. -- Updated the community Feishu bundle to C2 Plugin Standard 1.2 and version 0.3.0, removed its obsolete - rail UI action, and reduced its public command surface to the connector dispatcher. -- Ponytail Full removed the one-value connector `kind`, unused label/description/order metadata, - speculative reference/forwarding capabilities, per-connector policy components, and the redundant - renderer-side enabled/trusted lookup and unused context payload. Bundle enablement remains the - single product policy gate. -- Per the user's explicit instruction, removed C2 Plugin Standard 1.0/1.1 parsing and installed-record - compatibility. Runtime commands and contribution arrays are now required installed data, and all - checked-in C2 packs declare 1.2. -- Added a host-owned plugin-details extension point and moved Feishu app creation, account authorization, - reauthorization, and disconnect controls into the owning community bundle's plugin details. The - unauthorized rail and workspace now expose only a concise sign-in route and no resource groups. -- Extended the Feishu connector message result with `senderName` and `senderAvatarUrl`. The community - adapter resolves every unique human sender in one Contacts batch, falls back to the basic-name batch - when profile visibility blocks avatars, and leaves app/bot senders on the existing last-resort label. - The desktop now uses that identity in the conversation, circular avatar, and Agent handoff prompt. - -## Verification - -- `bun test ./tests/pluginModel.test.ts ./tests/pluginContributions.test.ts - ./tests/pluginCatalog.test.ts ./tests/feishuWorkspaceRendered.test.tsx`: 22 passed, 0 failed, - 321 assertions after the Ponytail reduction. The rendered tests emit existing React `act(...)` - warnings. -- `bun run build:renderer`: passed design-system source/dist checks, TypeScript, and the Vite production - build. Vite retained its existing large-chunk warning. -- Authorization-state regression run on 2026-08-31: the Feishu workspace and plugin-manager rendered - suites passed 28 tests / 0 failures, including English and Chinese unauthorized states, absence of all - three resource groups, exact plugin selection, settings-host authorization controls, and the preserved - authorized directory. `bunx tsc --noEmit`, `git diff --check`, and `bun run build:renderer` passed; - the build retained only the existing large-chunk warning. -- Sender-identity regression run on 2026-08-31: the focused desktop rendered and prompt suites passed - 13 tests / 0 failures, including a red-to-green case that rejects `Member · ` when the - connector supplies a name and avatar. `bunx tsc --noEmit` and `bun run build:renderer` passed; the - build retained only the existing large-chunk warning. -- Community adapter 0.5.1 passed `npm run check` (69 tests, typecheck, source/client/bundle builds) and - `CODETWO_RUNTIME_BUNDLE=1 npx vitest run tests/codetwo-runtime.spec.ts` (11 tests). The packaged-runtime - test confirms a single tenant-authenticated Contacts batch returns `林小满` and her avatar for both - messages, rather than exposing `ou_lin`; C2's validator accepted version 0.5.1 with one connector. -- Draft-PR preflight on 2026-08-31: the eight affected desktop suites passed 94 tests / 0 failures; - `DOCS_RS=1 cargo check -p codetwo-plugins --tests` passed; and - `DOCS_RS=1 cargo test -p codetwo-plugins --lib` passed 38 tests / 0 failures. -- Community bundle `npx vitest run tests/codetwo-runtime.spec.ts`: 9 passed; `npm run -s build` passed; - C2's validator accepted version 0.3.0 with one static runtime command, no UI actions, and one - connector. The runtime and its tests now use only `feishu.connector.invoke`; the private legacy - command aliases were deleted. -- `git diff --check`: passed. -- `DOCS_RS=1 cargo check -p codetwo-plugins`: passed, compiling the new Rust manifest and command - contracts while intentionally skipping the Ghostty native build. -- `DOCS_RS=1 cargo check -p codetwo-plugins --tests`: passed, including the updated integration-test - fixtures under the current-only installed-record contract. -- `DOCS_RS=1 cargo test -p codetwo-plugins --lib`: 37 passed, including the 1.2 connector parser, - ownership validation, and capability-to-operation policy. This mode does not link the native - terminal library. -- The native integration-test binaries currently fail to link because the local Ghostty symbols are - unavailable. Their sources type-check under `cargo check --tests`, but this run does not claim a - linked integration-test pass. -- Installed the minimized community bundle through `codetwo-plugins`' real local-bundle install path - while the Core was stopped. Installed-record readback shows version 0.3.0 / C2 Plugin Standard 1.2, - exactly one public runtime command, `feishu.connector.invoke`, the four-field `provider: feishu` - connector descriptor, no UI action, and the preserved trusted/enabled state. -- Against the packaged desktop Core and default data directory, `plugins.list` surfaced that installed - connector. `plugins.invoke_connector` successfully dispatched `connection.status` and - `resources.list` through the community runtime: the existing Feishu account was connected and the - result contained real direct contacts, groups, documents, and Base resources. -- Rebuilt, packaged, and launched `C2-dev` from the canonical `script/build_and_run.sh` path. The new - launcher and Core remain alive, and the Core is the only process owning the default data directory. -- Read-only real-window inspection found a separate launcher from another worktree with the same - `dev.codetwo.app.dev` bundle id. Name-based inspection selected that stale window; full-path - inspection selected this build but found its renderer blank, with only native window controls in - the accessibility tree. The unrelated old launcher was not terminated, so left-rail rendering is - not accepted yet. -- The 2026-08-31 real-window retry found that port 1420 is owned by PID 30184 from - `/Users/chenli/projects/codeTwo/apps/desktop`, while this worktree's Electrobun/Core processes are - under `/Users/chenli/.codex/worktrees/a685/codeTwo`. The current C2 window therefore loads the other - checkout's renderer and still exposes its old account dialog. That user-owned renderer was not stopped - or replaced, so this checkout's new authorization surface remains unverified in a native window. - -Verdict: partial. Renderer tests, the current-only manifest and installed-record model, the minimized -source bundle, and the community runtime pass. Real-window behavior remains unverified because the -current renderer is blank while a same-bundle window from another worktree is also present, and the -native integration-test binaries do not currently link in this environment. - -### Acceptance evidence - -- AC-1: PASS — `Verification record above` preserves the original passing evidence. -- AC-2: PASS — `Verification record above` preserves the original passing evidence. -- AC-3: PASS — `Verification record above` preserves the original passing evidence. -- AC-4: PASS — `Verification record above` preserves the original passing evidence. -- AC-5: PASS — `Verification record above` preserves the original passing evidence. -- AC-6: PASS — `Verification record above` preserves the original passing evidence. -- AC-7: PASS — `Verification record above` preserves the original passing evidence. -- AC-8: PASS — `Verification record above` preserves the original passing evidence. -- AC-9: BLOCKED — `Verification record above` preserves the original unresolved criterion. -- AC-10: PASS — `Verification record above` preserves the original passing evidence. -- AC-11: BLOCKED — `Verification record above` preserves the original unresolved criterion. - -Residual risk: the community source no longer contains legacy command aliases, but the already-running -default desktop profile still owns its installed copy. Replacing that copy safely requires the next -explicit stop/install/restart window. Separately, restore the Ghostty native link environment and clear -the same-bundle desktop collision before accepting native integration and left-rail rendering. - -## Review and release - -Approval: implementation approved by chenli through the user request. -Draft PR: https://github.com/IchenDEV/codeTwo/pull/185 -Merge approval: explicitly granted by chenli on 2026-08-31. -Release target: none. -Release identity: not applicable until released. -Smoke evidence: not applicable until released. -Rollback: remove connector contributions and restore the previous host-specific Feishu routing. -No release: no release was requested. - -## Feedback - -The user requested `ponytail full`; the response removed unused connector concepts rather than adding -another abstraction or compatibility layer. diff --git a/docs/sdlc/changes/2026-08-30-plugin-connectors/intent.md b/docs/sdlc/changes/2026-08-30-plugin-connectors/intent.md new file mode 100644 index 00000000..04af9799 --- /dev/null +++ b/docs/sdlc/changes/2026-08-30-plugin-connectors/intent.md @@ -0,0 +1,53 @@ +--- +id: "2026-08-30-plugin-connectors" +stage: intent +schema: 3 +status: accepted +owner: codex +created: 2026-08-30 +source: user request in this task, "需要提升扩展plugin 模型" +risk: high +approved_by: "chenli" +approved_at: "2026-08-30" +--- + +# Intent: Add connector contributions to the extension model + +## Problem + +The Feishu collaboration experience currently depends on the desktop recognizing one installed +bundle by name and calling its `feishu.*` commands directly. That makes a community extension look +integrated while keeping its discovery and routing inside product-specific host code. The user +requested a stronger extension model so rich collaboration integrations remain community plugins. + +## Proposed outcome + +The Feishu collaboration experience currently depends on the desktop recognizing one installed + +## Affected users and systems + +Migrated from legacy change.md. + +## Constraints + +The user's direct implementation request approves this Intent and Spec, with chenli as the named +approver. The user later authorized PR #185 and explicitly authorized its merge on 2026-08-31. +No publication, deployment, or release is authorized. + +## Out of scope + +Not recorded in the legacy single-file Artifact. + +## Success signals + +See Spec acceptance criteria. + +## Open questions + +None recorded in migration. + +## Decision + +The user's direct implementation request approves this Intent and Spec, with chenli as the named +approver. The user later authorized PR #185 and explicitly authorized its merge on 2026-08-31. +No publication, deployment, or release is authorized. diff --git a/docs/sdlc/changes/2026-08-30-plugin-connectors/plan.md b/docs/sdlc/changes/2026-08-30-plugin-connectors/plan.md new file mode 100644 index 00000000..b41e860c --- /dev/null +++ b/docs/sdlc/changes/2026-08-30-plugin-connectors/plan.md @@ -0,0 +1,78 @@ +--- +id: "2026-08-30-plugin-connectors" +stage: plan +schema: 3 +status: accepted +owner: codex +created: 2026-08-30 +based_on: spec.md +risk: high +scope: community/plugins/feishu, apps/desktop, crates/plugins, docs/reference/plugin-standard.md +approved_by: "chenli" +approved_at: "2026-08-30" +--- + +# Plan: Add connector contributions to the extension model + +## Files and ownership + +community/plugins/feishu, apps/desktop, crates/plugins, docs/reference/plugin-standard.md + +## Order of work + +Extend the manifest parser and installed model, add one ownership-checked connector invocation command, +project active descriptors into the renderer, migrate Feishu discovery and calls to that seam, and add +contract tests at the parser, runtime, bridge, and rendered-surface levels. Rollback removes the 1.2 +descriptor support and restores the previous Feishu-specific host lookup. + +For the authorization state, keep provider controls host-rendered but mount them only inside the owning +bundle's plugin details. The collaboration rail is a resource directory after authorization, not a +second setup surface. + +## Test-first proof + +See legacy Verification section. + +## Visual or integration proof + +See legacy Verification section. + +## Risks and mitigations + +See legacy Decision and gates. + +## Rollback + +See legacy Review and release. + +## Deviations + +- Added the 1.2 manifest, installed-bundle, inventory, catalog, validation CLI, + bridge, and localization contracts for connector contributions. +- Added `plugins.invoke_connector`, which checks bundle enablement and trust, contribution and command + ownership, runtime realm, input shape, and capability-to-operation namespace before dispatching the + standard `{ operation, input }` envelope. +- Moved the Feishu desktop surface to active connector discovery with `provider: feishu`; all + provider calls now use standard operations through the connector facade. +- Updated the community Feishu bundle to C2 Plugin Standard 1.2 and version 0.3.0, removed its obsolete + rail UI action, and reduced its public command surface to the connector dispatcher. +- Ponytail Full removed the one-value connector `kind`, unused label/description/order metadata, + speculative reference/forwarding capabilities, per-connector policy components, and the redundant + renderer-side enabled/trusted lookup and unused context payload. Bundle enablement remains the + single product policy gate. +- Per the user's explicit instruction, removed C2 Plugin Standard 1.0/1.1 parsing and installed-record + compatibility. Runtime commands and contribution arrays are now required installed data, and all + checked-in C2 packs declare 1.2. +- Added a host-owned plugin-details extension point and moved Feishu app creation, account authorization, + reauthorization, and disconnect controls into the owning community bundle's plugin details. The + unauthorized rail and workspace now expose only a concise sign-in route and no resource groups. +- Extended the Feishu connector message result with `senderName` and `senderAvatarUrl`. The community + adapter resolves every unique human sender in one Contacts batch, falls back to the basic-name batch + when profile visibility blocks avatars, and leaves app/bot senders on the existing last-resort label. + The desktop now uses that identity in the conversation, circular avatar, and Agent handoff prompt. + +## Decision + +The user's direct implementation request approves this Intent and Spec, with chenli as the named +approver. The user later authorized PR #185 and explicitly authorized its merge on 2026-08-31. +No publication, deployment, or release is authorized. diff --git a/docs/sdlc/changes/2026-08-30-plugin-connectors/spec.md b/docs/sdlc/changes/2026-08-30-plugin-connectors/spec.md new file mode 100644 index 00000000..622b10ae --- /dev/null +++ b/docs/sdlc/changes/2026-08-30-plugin-connectors/spec.md @@ -0,0 +1,78 @@ +--- +id: "2026-08-30-plugin-connectors" +stage: spec +schema: 3 +status: accepted +owner: codex +created: 2026-08-30 +based_on: intent.md +risk: high +approved_by: "chenli" +approved_at: "2026-08-30" +--- + +# Spec: Add connector contributions to the extension model + +## Requirements + +C2 Plugin Standard 1.2 adds host-rendered connector descriptors. A connector declares only a stable +bundle-local id, a provider identifier, one command owned by the same runtime, and the capabilities +that are implemented now. The host invokes that command with an operation and input; the +bundle owns provider-specific authentication and data access. Connector code cannot inject React or +HTML and cannot invoke another bundle's command. + +The initial capabilities cover connection, conversations, documents, tables, messaging, and turn +notifications. The existing Feishu surface becomes the first provider adapter: it is discovered +through the descriptor rather than the bundle name, and all host calls pass through the connector +invocation command. A connector for another provider cannot be rendered by the Feishu adapter. +Only C2 Plugin Standard 1.2 bundles and installed records are accepted. + +## User experience + +Not separately recorded in legacy change.md. + +## Technical design + +See Requirements and legacy Git history. + +## Security and privacy + +See migrated Decision and gates. + +## Alternatives and non-goals + +Not separately recorded in legacy change.md. + +## Areas of concern + +The user's direct implementation request approves this Intent and Spec, with chenli as the named +approver. The user later authorized PR #185 and explicitly authorized its merge on 2026-08-31. +No publication, deployment, or release is authorized. + +## Acceptance criteria + +- [x] AC-1: A valid 1.2 bundle can declare a connector whose command is statically declared by the same + runtime; unknown capabilities, commands, fields, and duplicate ids fail closed. +- [x] AC-2: C2 accepts only Plugin Standard 1.2; 1.0 and 1.1 manifests and installed records fail closed. +- [x] AC-3: Installed bundle inventory, catalog counts, and desktop bridge expose connector + descriptors without starting an untrusted runtime. +- [x] AC-4: Connector invocation verifies enabled/trusted state, contribution ownership, command ownership, + and caller realm before dispatching `{ operation, input }`. +- [x] AC-5: The desktop discovers the Feishu collaboration surface from an active connector and contains no + plugin-name check or direct `feishu.*` command call for that surface. +- [x] AC-6: The community Feishu bundle declares the connector and implements its single operation dispatcher + as its only public runtime command. +- [x] AC-7: Before Feishu authorization, the rail shows no contact, document, or Base groups; it presents + only a concise sign-in prompt whose action opens the Feishu bundle's plugin settings. +- [x] AC-8: Feishu app setup and account authorization live in the Feishu plugin details rather than the + collaboration workspace; successful authorization restores the existing resource directory. +- [ ] AC-9: The authorization boundary is covered in English and Chinese and checked in the rendered desktop. +- [x] AC-10: Conversation messages render the sender display name and avatar resolved by the connector; internal + Feishu identifiers appear only as a last-resort fallback when no user profile is available. +- [ ] AC-11: Focused Rust, renderer, community-plugin, build, SDLC, and real-window checks pass. + +## Decision + +The user's direct implementation request approves this Intent and Spec, with chenli as the named +approver. The user later authorized PR #185 and explicitly authorized its merge on 2026-08-31. +No publication, deployment, or release is authorized. diff --git a/docs/sdlc/changes/2026-08-30-plugin-connectors/verification.md b/docs/sdlc/changes/2026-08-30-plugin-connectors/verification.md new file mode 100644 index 00000000..007310bb --- /dev/null +++ b/docs/sdlc/changes/2026-08-30-plugin-connectors/verification.md @@ -0,0 +1,217 @@ +--- +id: "2026-08-30-plugin-connectors" +stage: verification +schema: 3 +status: pending +owner: codex +created: 2026-08-30 +based_on: plan.md +commit: "" +verification_mode: independent +verified_by: "" +verified_at: "" +release_target: none +release_identity: "not applicable until released." +--- + +# Verification: Add connector contributions to the extension model + +## Automated checks + +- `bun test ./tests/pluginModel.test.ts ./tests/pluginContributions.test.ts + ./tests/pluginCatalog.test.ts ./tests/feishuWorkspaceRendered.test.tsx`: 22 passed, 0 failed, + 321 assertions after the Ponytail reduction. The rendered tests emit existing React `act(...)` + warnings. +- `bun run build:renderer`: passed design-system source/dist checks, TypeScript, and the Vite production + build. Vite retained its existing large-chunk warning. +- Authorization-state regression run on 2026-08-31: the Feishu workspace and plugin-manager rendered + suites passed 28 tests / 0 failures, including English and Chinese unauthorized states, absence of all + three resource groups, exact plugin selection, settings-host authorization controls, and the preserved + authorized directory. `bunx tsc --noEmit`, `git diff --check`, and `bun run build:renderer` passed; + the build retained only the existing large-chunk warning. +- Sender-identity regression run on 2026-08-31: the focused desktop rendered and prompt suites passed + 13 tests / 0 failures, including a red-to-green case that rejects `Member · ` when the + connector supplies a name and avatar. `bunx tsc --noEmit` and `bun run build:renderer` passed; the + build retained only the existing large-chunk warning. +- Community adapter 0.5.1 passed `npm run check` (69 tests, typecheck, source/client/bundle builds) and + `CODETWO_RUNTIME_BUNDLE=1 npx vitest run tests/codetwo-runtime.spec.ts` (11 tests). The packaged-runtime + test confirms a single tenant-authenticated Contacts batch returns `林小满` and her avatar for both + messages, rather than exposing `ou_lin`; C2's validator accepted version 0.5.1 with one connector. +- Draft-PR preflight on 2026-08-31: the eight affected desktop suites passed 94 tests / 0 failures; + `DOCS_RS=1 cargo check -p codetwo-plugins --tests` passed; and + `DOCS_RS=1 cargo test -p codetwo-plugins --lib` passed 38 tests / 0 failures. +- Community bundle `npx vitest run tests/codetwo-runtime.spec.ts`: 9 passed; `npm run -s build` passed; + C2's validator accepted version 0.3.0 with one static runtime command, no UI actions, and one + connector. The runtime and its tests now use only `feishu.connector.invoke`; the private legacy + command aliases were deleted. +- `git diff --check`: passed. +- `DOCS_RS=1 cargo check -p codetwo-plugins`: passed, compiling the new Rust manifest and command + contracts while intentionally skipping the Ghostty native build. +- `DOCS_RS=1 cargo check -p codetwo-plugins --tests`: passed, including the updated integration-test + fixtures under the current-only installed-record contract. +- `DOCS_RS=1 cargo test -p codetwo-plugins --lib`: 37 passed, including the 1.2 connector parser, + ownership validation, and capability-to-operation policy. This mode does not link the native + terminal library. +- The native integration-test binaries currently fail to link because the local Ghostty symbols are + unavailable. Their sources type-check under `cargo check --tests`, but this run does not claim a + linked integration-test pass. +- Installed the minimized community bundle through `codetwo-plugins`' real local-bundle install path + while the Core was stopped. Installed-record readback shows version 0.3.0 / C2 Plugin Standard 1.2, + exactly one public runtime command, `feishu.connector.invoke`, the four-field `provider: feishu` + connector descriptor, no UI action, and the preserved trusted/enabled state. +- Against the packaged desktop Core and default data directory, `plugins.list` surfaced that installed + connector. `plugins.invoke_connector` successfully dispatched `connection.status` and + `resources.list` through the community runtime: the existing Feishu account was connected and the + result contained real direct contacts, groups, documents, and Base resources. +- Rebuilt, packaged, and launched `C2-dev` from the canonical `script/build_and_run.sh` path. The new + launcher and Core remain alive, and the Core is the only process owning the default data directory. +- Read-only real-window inspection found a separate launcher from another worktree with the same + `dev.codetwo.app.dev` bundle id. Name-based inspection selected that stale window; full-path + inspection selected this build but found its renderer blank, with only native window controls in + the accessibility tree. The unrelated old launcher was not terminated, so left-rail rendering is + not accepted yet. +- The 2026-08-31 real-window retry found that port 1420 is owned by PID 30184 from + `/Users/chenli/projects/codeTwo/apps/desktop`, while this worktree's Electrobun/Core processes are + under `/Users/chenli/.codex/worktrees/a685/codeTwo`. The current C2 window therefore loads the other + checkout's renderer and still exposes its old account dialog. That user-owned renderer was not stopped + or replaced, so this checkout's new authorization surface remains unverified in a native window. + +Verdict: partial. Renderer tests, the current-only manifest and installed-record model, the minimized +source bundle, and the community runtime pass. Real-window behavior remains unverified because the +current renderer is blank while a same-bundle window from another worktree is also present, and the +native integration-test binaries do not currently link in this environment. + +### Acceptance evidence + +- AC-1: PASS — `Verification record above` preserves the original passing evidence. +- AC-2: PASS — `Verification record above` preserves the original passing evidence. +- AC-3: PASS — `Verification record above` preserves the original passing evidence. +- AC-4: PASS — `Verification record above` preserves the original passing evidence. +- AC-5: PASS — `Verification record above` preserves the original passing evidence. +- AC-6: PASS — `Verification record above` preserves the original passing evidence. +- AC-7: PASS — `Verification record above` preserves the original passing evidence. +- AC-8: PASS — `Verification record above` preserves the original passing evidence. +- AC-9: BLOCKED — `Verification record above` preserves the original unresolved criterion. +- AC-10: PASS — `Verification record above` preserves the original passing evidence. +- AC-11: BLOCKED — `Verification record above` preserves the original unresolved criterion. + +Residual risk: the community source no longer contains legacy command aliases, but the already-running +default desktop profile still owns its installed copy. Replacing that copy safely requires the next +explicit stop/install/restart window. Separately, restore the Ghostty native link environment and clear +the same-bundle desktop collision before accepting native integration and left-rail rendering. + +## Behavioral evidence + +- `bun test ./tests/pluginModel.test.ts ./tests/pluginContributions.test.ts + ./tests/pluginCatalog.test.ts ./tests/feishuWorkspaceRendered.test.tsx`: 22 passed, 0 failed, + 321 assertions after the Ponytail reduction. The rendered tests emit existing React `act(...)` + warnings. +- `bun run build:renderer`: passed design-system source/dist checks, TypeScript, and the Vite production + build. Vite retained its existing large-chunk warning. +- Authorization-state regression run on 2026-08-31: the Feishu workspace and plugin-manager rendered + suites passed 28 tests / 0 failures, including English and Chinese unauthorized states, absence of all + three resource groups, exact plugin selection, settings-host authorization controls, and the preserved + authorized directory. `bunx tsc --noEmit`, `git diff --check`, and `bun run build:renderer` passed; + the build retained only the existing large-chunk warning. +- Sender-identity regression run on 2026-08-31: the focused desktop rendered and prompt suites passed + 13 tests / 0 failures, including a red-to-green case that rejects `Member · ` when the + connector supplies a name and avatar. `bunx tsc --noEmit` and `bun run build:renderer` passed; the + build retained only the existing large-chunk warning. +- Community adapter 0.5.1 passed `npm run check` (69 tests, typecheck, source/client/bundle builds) and + `CODETWO_RUNTIME_BUNDLE=1 npx vitest run tests/codetwo-runtime.spec.ts` (11 tests). The packaged-runtime + test confirms a single tenant-authenticated Contacts batch returns `林小满` and her avatar for both + messages, rather than exposing `ou_lin`; C2's validator accepted version 0.5.1 with one connector. +- Draft-PR preflight on 2026-08-31: the eight affected desktop suites passed 94 tests / 0 failures; + `DOCS_RS=1 cargo check -p codetwo-plugins --tests` passed; and + `DOCS_RS=1 cargo test -p codetwo-plugins --lib` passed 38 tests / 0 failures. +- Community bundle `npx vitest run tests/codetwo-runtime.spec.ts`: 9 passed; `npm run -s build` passed; + C2's validator accepted version 0.3.0 with one static runtime command, no UI actions, and one + connector. The runtime and its tests now use only `feishu.connector.invoke`; the private legacy + command aliases were deleted. +- `git diff --check`: passed. +- `DOCS_RS=1 cargo check -p codetwo-plugins`: passed, compiling the new Rust manifest and command + contracts while intentionally skipping the Ghostty native build. +- `DOCS_RS=1 cargo check -p codetwo-plugins --tests`: passed, including the updated integration-test + fixtures under the current-only installed-record contract. +- `DOCS_RS=1 cargo test -p codetwo-plugins --lib`: 37 passed, including the 1.2 connector parser, + ownership validation, and capability-to-operation policy. This mode does not link the native + terminal library. +- The native integration-test binaries currently fail to link because the local Ghostty symbols are + unavailable. Their sources type-check under `cargo check --tests`, but this run does not claim a + linked integration-test pass. +- Installed the minimized community bundle through `codetwo-plugins`' real local-bundle install path + while the Core was stopped. Installed-record readback shows version 0.3.0 / C2 Plugin Standard 1.2, + exactly one public runtime command, `feishu.connector.invoke`, the four-field `provider: feishu` + connector descriptor, no UI action, and the preserved trusted/enabled state. +- Against the packaged desktop Core and default data directory, `plugins.list` surfaced that installed + connector. `plugins.invoke_connector` successfully dispatched `connection.status` and + `resources.list` through the community runtime: the existing Feishu account was connected and the + result contained real direct contacts, groups, documents, and Base resources. +- Rebuilt, packaged, and launched `C2-dev` from the canonical `script/build_and_run.sh` path. The new + launcher and Core remain alive, and the Core is the only process owning the default data directory. +- Read-only real-window inspection found a separate launcher from another worktree with the same + `dev.codetwo.app.dev` bundle id. Name-based inspection selected that stale window; full-path + inspection selected this build but found its renderer blank, with only native window controls in + the accessibility tree. The unrelated old launcher was not terminated, so left-rail rendering is + not accepted yet. +- The 2026-08-31 real-window retry found that port 1420 is owned by PID 30184 from + `/Users/chenli/projects/codeTwo/apps/desktop`, while this worktree's Electrobun/Core processes are + under `/Users/chenli/.codex/worktrees/a685/codeTwo`. The current C2 window therefore loads the other + checkout's renderer and still exposes its old account dialog. That user-owned renderer was not stopped + or replaced, so this checkout's new authorization surface remains unverified in a native window. + +Verdict: partial. Renderer tests, the current-only manifest and installed-record model, the minimized +source bundle, and the community runtime pass. Real-window behavior remains unverified because the +current renderer is blank while a same-bundle window from another worktree is also present, and the +native integration-test binaries do not currently link in this environment. + +### Acceptance evidence + +- AC-1: PASS — `Verification record above` preserves the original passing evidence. +- AC-2: PASS — `Verification record above` preserves the original passing evidence. +- AC-3: PASS — `Verification record above` preserves the original passing evidence. +- AC-4: PASS — `Verification record above` preserves the original passing evidence. +- AC-5: PASS — `Verification record above` preserves the original passing evidence. +- AC-6: PASS — `Verification record above` preserves the original passing evidence. +- AC-7: PASS — `Verification record above` preserves the original passing evidence. +- AC-8: PASS — `Verification record above` preserves the original passing evidence. +- AC-9: BLOCKED — `Verification record above` preserves the original unresolved criterion. +- AC-10: PASS — `Verification record above` preserves the original passing evidence. +- AC-11: BLOCKED — `Verification record above` preserves the original unresolved criterion. + +Residual risk: the community source no longer contains legacy command aliases, but the already-running +default desktop profile still owns its installed copy. Replacing that copy safely requires the next +explicit stop/install/restart window. Separately, restore the Ghostty native link environment and clear +the same-bundle desktop collision before accepting native integration and left-rail rendering. + +## Visual evidence + +See bundle evidence/ when present. + +## Security and privacy evidence + +Not separately recorded unless present in legacy Verification. + +## Deviations and residual risk + +Residual risk: the community source no longer contains legacy command aliases, but the already-running + +## Verdict + +Verdict: partial. Renderer tests, the current-only manifest and installed-record model, the minimized. + +## Review and release + +Approval: implementation approved by chenli through the user request. +Draft PR: https://github.com/IchenDEV/codeTwo/pull/185 +Merge approval: explicitly granted by chenli on 2026-08-31. +Release target: none. +Release identity: not applicable until released. +Smoke evidence: not applicable until released. +Rollback: remove connector contributions and restore the previous host-specific Feishu routing. +No release: no release was requested. + +## Feedback + +The user requested `ponytail full`; the response removed unused connector concepts rather than adding +another abstraction or compatibility layer. diff --git a/docs/sdlc/changes/2026-08-30-quiet-session-rail-items/intent.md b/docs/sdlc/changes/2026-08-30-quiet-session-rail-items/intent.md new file mode 100644 index 00000000..1aeff826 --- /dev/null +++ b/docs/sdlc/changes/2026-08-30-quiet-session-rail-items/intent.md @@ -0,0 +1,54 @@ +--- +id: "2026-08-30-quiet-session-rail-items" +stage: intent +schema: 3 +status: accepted +owner: codex +created: 2026-08-30 +source: user-supplied sidebar reference and PR #183 +risk: low +approved_by: "userthe 2026-08-30 sidebar requests and explicit PR merge authorization" +approved_at: "2026-08-30" +--- + +# Intent: Quiet the session rail items + +## Problem + +The user supplied a Codex-style sidebar reference on 2026-08-30 and asked to improve the CodeTwo +sidebar items so they stay clean and demand less attention. They clarified that the row remains a +three-level hierarchy when a latest-conversation preview exists: title, latest conversation, then +project/workspace. When no useful preview exists, only the title and workspace appear. Provider, +routine completion, age, and persistent controls should not turn each idle row into a status card. + +## Proposed outcome + +The user supplied a Codex-style sidebar reference on 2026-08-30 and asked to improve the CodeTwo + +## Affected users and systems + +Migrated from legacy change.md. + +## Constraints + +Intent and design acceptance come directly from the user's 2026-08-30 request and supplied +reference. The change is limited to the session item hierarchy and its focused regression tests. +No PR, merge, publication, or release permission is implied. + +## Out of scope + +Not recorded in the legacy single-file Artifact. + +## Success signals + +See Spec acceptance criteria. + +## Open questions + +None recorded in migration. + +## Decision + +Intent and design acceptance come directly from the user's 2026-08-30 request and supplied +reference. The change is limited to the session item hierarchy and its focused regression tests. +No PR, merge, publication, or release permission is implied. diff --git a/docs/sdlc/changes/2026-08-30-quiet-session-rail-items/plan.md b/docs/sdlc/changes/2026-08-30-quiet-session-rail-items/plan.md new file mode 100644 index 00000000..8bdba87b --- /dev/null +++ b/docs/sdlc/changes/2026-08-30-quiet-session-rail-items/plan.md @@ -0,0 +1,60 @@ +--- +id: "2026-08-30-quiet-session-rail-items" +stage: plan +schema: 3 +status: accepted +owner: codex +created: 2026-08-30 +based_on: spec.md +risk: low +scope: apps/desktop +approved_by: "userthe 2026-08-30 sidebar requests and explicit PR merge authorization" +approved_at: "2026-08-30" +--- + +# Plan: Quiet the session rail items + +## Files and ownership + +apps/desktop + +## Order of work + +Refine the existing row in place, reuse the existing Button, context-menu, semantic status, and +selection-group primitives, and keep the rail's current width contract. Keep useful preview +copy as the conditional middle line, replace the visible provider/completed footer with workspace +identity, disclose actions on hover or focus, and retain urgent activity at the trailing edge. +Update only the focused rendered tests that protect this behavior, then validate source, renderer, +and lifecycle gates. Rollback is the inverse component and test change. + +## Test-first proof + +See legacy Verification section. + +## Visual or integration proof + +See legacy Verification section. + +## Risks and mitigations + +See legacy Decision and gates. + +## Rollback + +See legacy Review and release. + +## Deviations + +The session row now renders a conditional title/preview/workspace hierarchy. Useful latest +conversation text is a visible, truncated middle line and remains the row's accessible description +and native hover title. Empty, punctuation-only, or title-repeating previews are omitted, so those +rows collapse to title/workspace. Provider branding, age, and routine completed state remain out of +the resting row. Running, awaiting-input, and failed states use compact semantic indicators. Pin, +rename, and archive/restore controls appear on hover, keyboard focus, or popup-open state and remain +present in the existing native and rendered context menus. + +## Decision + +Intent and design acceptance come directly from the user's 2026-08-30 request and supplied +reference. The change is limited to the session item hierarchy and its focused regression tests. +No PR, merge, publication, or release permission is implied. diff --git a/docs/sdlc/changes/2026-08-30-quiet-session-rail-items/spec.md b/docs/sdlc/changes/2026-08-30-quiet-session-rail-items/spec.md new file mode 100644 index 00000000..225d8326 --- /dev/null +++ b/docs/sdlc/changes/2026-08-30-quiet-session-rail-items/spec.md @@ -0,0 +1,65 @@ +--- +id: "2026-08-30-quiet-session-rail-items" +stage: spec +schema: 3 +status: accepted +owner: codex +created: 2026-08-30 +based_on: intent.md +risk: low +approved_by: "userthe 2026-08-30 sidebar requests and explicit PR merge authorization" +approved_at: "2026-08-30" +--- + +# Spec: Quiet the session rail items + +## Requirements + +Each session row uses the existing source-list selection treatment and a conditional content stack: +title first, a useful latest-conversation preview second, and project/workspace identity last. The +middle line is omitted only when it has no meaningful text or merely repeats the title. Routine +completed state, provider branding, age, and action buttons do not compete in the resting visual +state. Running, awaiting-input, and failed states remain visible as compact semantic indicators. +Row actions remain available on pointer hover, keyboard focus, and the existing context menu. + +## User experience + +Not separately recorded in legacy change.md. + +## Technical design + +See Requirements and legacy Git history. + +## Security and privacy + +See migrated Decision and gates. + +## Alternatives and non-goals + +Not separately recorded in legacy change.md. + +## Areas of concern + +Intent and design acceptance come directly from the user's 2026-08-30 request and supplied +reference. The change is limited to the session item hierarchy and its focused regression tests. +No PR, merge, publication, or release permission is implied. + +## Acceptance criteria + +- [x] AC-1: Rows with a useful latest conversation show three ordered lines: title, preview, workspace. +- [x] AC-2: Rows without a useful preview collapse to two ordered lines: title and workspace. +- [x] AC-3: Completed text, provider branding, age, and persistent action chrome are absent from the + resting visual hierarchy. +- [x] AC-4: Running, awaiting-input, and failed sessions retain a compact, accessible state indicator; + completed sessions stay visually quiet. +- [x] AC-5: Rename, pin, archive/restore, selection, arrow-key navigation, and keyboard/native context + menus preserve their behavior and accessible names. +- [x] AC-6: Hover, focus, popup-open, and selected surfaces use the existing neutral source-list tokens in + light, dark, and constrained rail widths without clipping. +- [x] AC-7: Focused rendered tests, the design-system check, SDLC check, and real renderer inspection pass. + +## Decision + +Intent and design acceptance come directly from the user's 2026-08-30 request and supplied +reference. The change is limited to the session item hierarchy and its focused regression tests. +No PR, merge, publication, or release permission is implied. diff --git a/docs/sdlc/changes/2026-08-30-quiet-session-rail-items/change.md b/docs/sdlc/changes/2026-08-30-quiet-session-rail-items/verification.md similarity index 50% rename from docs/sdlc/changes/2026-08-30-quiet-session-rail-items/change.md rename to docs/sdlc/changes/2026-08-30-quiet-session-rail-items/verification.md index 05789d62..edd357d9 100644 --- a/docs/sdlc/changes/2026-08-30-quiet-session-rail-items/change.md +++ b/docs/sdlc/changes/2026-08-30-quiet-session-rail-items/verification.md @@ -1,83 +1,62 @@ --- -id: change-2026-08-30-quiet-session-rail-items -kind: change -schema: 2 -status: closed -risk: low +id: "2026-08-30-quiet-session-rail-items" +stage: verification +schema: 3 +status: passed owner: codex -approvers: user via the 2026-08-30 sidebar requests and explicit PR merge authorization -approved_at: 2026-08-30 created: 2026-08-30 -updated: 2026-08-31 -source: user-supplied sidebar reference and PR #183 -inputs: accepted conditional row-hierarchy and visual-noise constraints -outputs: merge commit e3744874 and focused renderer verification evidence -scope: apps/desktop -next_trigger: new session-rail feedback or a regression report +based_on: plan.md +commit: "" verification_mode: owner -verified_by: codex -verified_at: 2026-08-30 +verified_by: "codex" +verified_at: "2026-08-30" +release_target: none; this was a repository integration, not a versioned product release +release_identity: "" --- -# Quiet the session rail items +# Verification: Quiet the session rail items -## Intent +## Automated checks -The user supplied a Codex-style sidebar reference on 2026-08-30 and asked to improve the CodeTwo -sidebar items so they stay clean and demand less attention. They clarified that the row remains a -three-level hierarchy when a latest-conversation preview exists: title, latest conversation, then -project/workspace. When no useful preview exists, only the title and workspace appear. Provider, -routine completion, age, and persistent controls should not turn each idle row into a status card. - -## Spec - -Each session row uses the existing source-list selection treatment and a conditional content stack: -title first, a useful latest-conversation preview second, and project/workspace identity last. The -middle line is omitted only when it has no meaningful text or merely repeats the title. Routine -completed state, provider branding, age, and action buttons do not compete in the resting visual -state. Running, awaiting-input, and failed states remain visible as compact semantic indicators. -Row actions remain available on pointer hover, keyboard focus, and the existing context menu. - -### Acceptance criteria - -- [x] AC-1: Rows with a useful latest conversation show three ordered lines: title, preview, workspace. -- [x] AC-2: Rows without a useful preview collapse to two ordered lines: title and workspace. -- [x] AC-3: Completed text, provider branding, age, and persistent action chrome are absent from the - resting visual hierarchy. -- [x] AC-4: Running, awaiting-input, and failed sessions retain a compact, accessible state indicator; - completed sessions stay visually quiet. -- [x] AC-5: Rename, pin, archive/restore, selection, arrow-key navigation, and keyboard/native context - menus preserve their behavior and accessible names. -- [x] AC-6: Hover, focus, popup-open, and selected surfaces use the existing neutral source-list tokens in - light, dark, and constrained rail widths without clipping. -- [x] AC-7: Focused rendered tests, the design-system check, SDLC check, and real renderer inspection pass. - -## Decision and gates - -Intent and design acceptance come directly from the user's 2026-08-30 request and supplied -reference. The change is limited to the session item hierarchy and its focused regression tests. -No PR, merge, publication, or release permission is implied. +Verdict: verified. -## Plan +### Acceptance evidence -Refine the existing row in place, reuse the existing Button, context-menu, semantic status, and -selection-group primitives, and keep the rail's current width contract. Keep useful preview -copy as the conditional middle line, replace the visible provider/completed footer with workspace -identity, disclose actions on hover or focus, and retain urgent activity at the trailing edge. -Update only the focused rendered tests that protect this behavior, then validate source, renderer, -and lifecycle gates. Rollback is the inverse component and test change. +- AC-1: PASS — `bun test tests/sessionRailRendered.test.tsx` and renderer inspection verified title, preview, workspace ordering. +- AC-2: PASS — the same focused coverage verified two-line collapse when the preview is empty or redundant. Evidence: `Verification record above`. +- AC-3: PASS — rendered inspection confirmed completed text, provider branding, age, and resting action chrome were absent. Evidence: `Verification record above`. +- AC-4: PASS — focused tests retained compact accessible running, awaiting-input, and failed indicators while completed rows stayed quiet. Evidence: `Verification record above`. +- AC-5: PASS — `sessionRailRendered.test.tsx` retained rename, pin, archive/restore, selection, arrow navigation, and context menus. +- AC-6: PASS — recorded light/dark and 220px inspection verified neutral source-list states without horizontal overflow. Evidence: `Verification record above`. +- AC-7: PASS — the focused test, `bun run build:renderer`, `bun script/verify/sdlc.ts`, real renderer inspection, and `git diff --check` passed after two recorded build corrections. -## Build +- Failed iteration: `bun run build:renderer` stopped in the source design check because the first + row draft used raw `h-5`; the design checker required a semantic control-height utility. The row + was corrected to the existing `h-control-mini` token before the build was rerun. +- Failed iteration: the next renderer build passed the source design check with 0 new violations, + then TypeScript found the now-unused `providerLabel` import left by removing visible provider + branding. The unused import was removed before the next build. +- `bun test tests/sessionRailRendered.test.tsx`: 16 tests passed with 174 assertions. The existing + Base UI `act(...)` environment warnings remain non-failing and are outside this visual change. +- `bun run build:renderer`: passed TypeScript, Vite production build, source and generated-output + design checks after the hierarchy correction. The source check reported 0 new violations, 656 + legacy findings, and 20 contrast ratios; the generated-output check found 35 semantic selectors. + Vite built in 21.62 seconds. +- Real renderer inspection confirmed exact line order `title`, `preview`, `workspace` for useful + previews and `title`, `workspace` otherwise. Three-line rows measured 72 pixels high; two-line + rows measured 54 pixels. Both stayed free of horizontal overflow at the standard width and the + supported 220-pixel rail minimum. The earlier light/dark selection and action-disclosure checks + remain applicable because the correction only restores a semantic muted-text content line. + Selecting another row updated `aria-current`; the browser console reported no warnings or errors. +- Only the Vite renderer was started for inspection after the process/port preflight; no second Core + was launched alongside the live CodeTwo instance. The development-only preview fixture was + removed after inspection and is not part of the final source tree. +- `bun script/verify/sdlc.ts` revalidated the migrated Artifact, and `git diff --check` passed. -The session row now renders a conditional title/preview/workspace hierarchy. Useful latest -conversation text is a visible, truncated middle line and remains the row's accessible description -and native hover title. Empty, punctuation-only, or title-repeating previews are omitted, so those -rows collapse to title/workspace. Provider branding, age, and routine completed state remain out of -the resting row. Running, awaiting-input, and failed states use compact semantic indicators. Pin, -rename, and archive/restore controls appear on hover, keyboard focus, or popup-open state and remain -present in the existing native and rendered context menus. +Residual risk: the captured inspection covers the supported sidebar widths and themes, but not +future row content shapes introduced after PR #183. -## Verification +## Behavioral evidence Verdict: verified. @@ -117,6 +96,22 @@ Verdict: verified. Residual risk: the captured inspection covers the supported sidebar widths and themes, but not future row content shapes introduced after PR #183. +## Visual evidence + +See bundle evidence/ when present. + +## Security and privacy evidence + +Not separately recorded unless present in legacy Verification. + +## Deviations and residual risk + +Residual risk: the captured inspection covers the supported sidebar widths and themes, but not + +## Verdict + +Verdict: verified.. + ## Review and release Approval: the user explicitly authorized creating and merging the repository pull request on diff --git a/docs/sdlc/changes/2026-08-31-align-selectable-row-icons/change.md b/docs/sdlc/changes/2026-08-31-align-selectable-row-icons/change.md deleted file mode 100644 index 2b788cc4..00000000 --- a/docs/sdlc/changes/2026-08-31-align-selectable-row-icons/change.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -id: change-2026-08-31-align-selectable-row-icons -kind: change -schema: 2 -status: verified -risk: low -owner: codex -approvers: [user via the 2026-08-31 direct icon-alignment request] -approved_at: 2026-08-31 -created: 2026-08-31 -updated: 2026-08-31 -source: direct user feedback that the icon is crooked and not aligned -inputs: rendered Provider picker and shared SelectableRow layout -outputs: first-line-aligned selection indicators and leading icons -scope: apps/desktop/src/components/business/selectable-row.tsx, apps/desktop/tests/designSystemBusinessComponents.test.tsx, docs/sdlc/changes/2026-08-31-align-selectable-row-icons/change.md -next_trigger: human review and feedback -verification_mode: owner -verified_by: codex -verified_at: 2026-08-31 ---- - -# Align selectable-row icons with their labels - -## Intent - -The user reported that the icon in the recently rendered Provider picker looked crooked and out of -alignment. Browser geometry confirmed that description-bearing `SelectableRow` children were -top-aligned: the 14 px provider mark sat 3.5 px above the center of the 21 px first-line label, and -the availability dot touched the provider mark with zero spacing. The desired result is a stable, -visually centered first-line icon column without redesigning the menu or changing provider state. -This request does not authorize a pull request, merge, release, or deployment. - -## Spec - -The selection indicator and leading content use a line-height-sized alignment box so their visual -centers match the row's first-line label whether or not a description exists. Multiple leading -elements use the existing inline gap token, separating the Provider availability dot from its -brand mark. Selection, disabled behavior, accessible names, descriptions, and provider behavior -remain unchanged. - -### Acceptance criteria - -- [x] AC-1: In description-bearing selectable rows, the selection indicator and provider mark are - centered on the first-line label rather than its top edge. -- [x] AC-2: The Provider availability dot and brand mark have visible tokenized spacing while all - rows retain consistent text and icon columns. -- [x] AC-3: Focused/full desktop tests, renderer build, desktop/narrow Browser inspection, and - repository lifecycle checks pass. - -## Decision and gates - -The user directly accepted this low-risk visual correction on 2026-08-31. No security, -data-migration, release, or production Gate applies. Human review remains required before merge, -and no external delivery action is authorized. - -## Plan - -1. Give the indicator and leading slots line-height-sized centering boxes and tokenized child gap. -2. Extend the shared component test to lock the alignment contract. -3. Run desktop tests/build and compare Browser geometry and screenshots at desktop and narrow - widths, then complete repository lifecycle checks. - -Rollback reverts the shared alignment classes and their focused assertions. - -## Build - -Completed. The shared selection-indicator and leading slots now use a `1lh`-high alignment box, -which follows the actual first-line text height instead of aligning smaller glyphs to its top edge. -The leading slot also applies the existing `gap-inline` token between multiple children. The -component test locks both layout classes without adding runtime state or rendering work. - -## Verification - -Verdict: verified. - -### Acceptance evidence - -- AC-1: PASS — Browser `evaluate()` geometry on the same rendered Provider picker measured the provider mark - 3.5 px and the selection indicator 2.5 px above the first-line label before the change. After - the change, indicator, leading slot, status dot, provider mark, and label shared the exact same - center line on Claude Code, Codex, Grok, and Cursor rows. -- AC-2: PASS — computed layout reported a 4 px `gap-inline` between the 6 px availability dot and - 14 px provider mark, with stable indicator and text columns. Desktop and 560x760 screenshots are - `/tmp/codetwo-provider-icons-aligned-desktop.png` and - `/tmp/codetwo-provider-icons-aligned-narrow.png`. -- AC-3: PASS — `bun test tests/designSystemBusinessComponents.test.tsx` passed 8 tests with 56 - expectations; after rebasing onto the latest `origin/main`, full `bun test` passed 774 tests with - 3,682 expectations and zero failures; - `bunx tsc --noEmit` and `bun run build:renderer` passed. Browser checks at desktop and 560x760 - verified page identity, meaningful content, no framework overlay, no horizontal overflow, and no - console warning/error. Repository lifecycle checks are recorded by the final Gate run after this - Artifact update. - -Residual risk: Browser validation covers the shared production renderer rather than restarting the -user's already-running native desktop application. Other rows using `SelectableRow` inherit the -same semantic first-line alignment, which is intentional. - -## Review and release - -Review handoff: [Draft PR #204](https://github.com/IchenDEV/codeTwo/pull/204). -Approval: pending human review. -Release target: none. -Release identity: not applicable until released. -Smoke evidence: not applicable until released. -Rollback: revert this change to restore the previous top-aligned icon layout. -No release: the current request authorizes only local implementation and verification. - -Preparing this section does not authorize merge, deployment, release, or production mutation. - -## Feedback - -No post-change feedback exists yet. diff --git a/docs/sdlc/changes/2026-08-31-align-selectable-row-icons/intent.md b/docs/sdlc/changes/2026-08-31-align-selectable-row-icons/intent.md new file mode 100644 index 00000000..d2e63781 --- /dev/null +++ b/docs/sdlc/changes/2026-08-31-align-selectable-row-icons/intent.md @@ -0,0 +1,55 @@ +--- +id: "2026-08-31-align-selectable-row-icons" +stage: intent +schema: 3 +status: accepted +owner: codex +created: 2026-08-31 +source: direct user feedback that the icon is crooked and not aligned +risk: low +approved_by: "[user via the 2026-08-31 direct icon-alignment request]" +approved_at: "2026-08-31" +--- + +# Intent: Align selectable-row icons with their labels + +## Problem + +The user reported that the icon in the recently rendered Provider picker looked crooked and out of +alignment. Browser geometry confirmed that description-bearing `SelectableRow` children were +top-aligned: the 14 px provider mark sat 3.5 px above the center of the 21 px first-line label, and +the availability dot touched the provider mark with zero spacing. The desired result is a stable, +visually centered first-line icon column without redesigning the menu or changing provider state. +This request does not authorize a pull request, merge, release, or deployment. + +## Proposed outcome + +The user reported that the icon in the recently rendered Provider picker looked crooked and out of + +## Affected users and systems + +Migrated from legacy change.md. + +## Constraints + +The user directly accepted this low-risk visual correction on 2026-08-31. No security, +data-migration, release, or production Gate applies. Human review remains required before merge, +and no external delivery action is authorized. + +## Out of scope + +Not recorded in the legacy single-file Artifact. + +## Success signals + +See Spec acceptance criteria. + +## Open questions + +None recorded in migration. + +## Decision + +The user directly accepted this low-risk visual correction on 2026-08-31. No security, +data-migration, release, or production Gate applies. Human review remains required before merge, +and no external delivery action is authorized. diff --git a/docs/sdlc/changes/2026-08-31-align-selectable-row-icons/plan.md b/docs/sdlc/changes/2026-08-31-align-selectable-row-icons/plan.md new file mode 100644 index 00000000..03714ba3 --- /dev/null +++ b/docs/sdlc/changes/2026-08-31-align-selectable-row-icons/plan.md @@ -0,0 +1,57 @@ +--- +id: "2026-08-31-align-selectable-row-icons" +stage: plan +schema: 3 +status: accepted +owner: codex +created: 2026-08-31 +based_on: spec.md +risk: low +scope: apps/desktop/src/components/business/selectable-row.tsx, apps/desktop/tests/designSystemBusinessComponents.test.tsx, docs/sdlc/changes/2026-08-31-align-selectable-row-icons/change.md +approved_by: "[user via the 2026-08-31 direct icon-alignment request]" +approved_at: "2026-08-31" +--- + +# Plan: Align selectable-row icons with their labels + +## Files and ownership + +apps/desktop/src/components/business/selectable-row.tsx, apps/desktop/tests/designSystemBusinessComponents.test.tsx, docs/sdlc/changes/2026-08-31-align-selectable-row-icons/change.md + +## Order of work + +1. Give the indicator and leading slots line-height-sized centering boxes and tokenized child gap. +2. Extend the shared component test to lock the alignment contract. +3. Run desktop tests/build and compare Browser geometry and screenshots at desktop and narrow + widths, then complete repository lifecycle checks. + +Rollback reverts the shared alignment classes and their focused assertions. + +## Test-first proof + +See legacy Verification section. + +## Visual or integration proof + +See legacy Verification section. + +## Risks and mitigations + +See legacy Decision and gates. + +## Rollback + +See legacy Review and release. + +## Deviations + +Completed. The shared selection-indicator and leading slots now use a `1lh`-high alignment box, +which follows the actual first-line text height instead of aligning smaller glyphs to its top edge. +The leading slot also applies the existing `gap-inline` token between multiple children. The +component test locks both layout classes without adding runtime state or rendering work. + +## Decision + +The user directly accepted this low-risk visual correction on 2026-08-31. No security, +data-migration, release, or production Gate applies. Human review remains required before merge, +and no external delivery action is authorized. diff --git a/docs/sdlc/changes/2026-08-31-align-selectable-row-icons/spec.md b/docs/sdlc/changes/2026-08-31-align-selectable-row-icons/spec.md new file mode 100644 index 00000000..4ec2ae12 --- /dev/null +++ b/docs/sdlc/changes/2026-08-31-align-selectable-row-icons/spec.md @@ -0,0 +1,59 @@ +--- +id: "2026-08-31-align-selectable-row-icons" +stage: spec +schema: 3 +status: accepted +owner: codex +created: 2026-08-31 +based_on: intent.md +risk: low +approved_by: "[user via the 2026-08-31 direct icon-alignment request]" +approved_at: "2026-08-31" +--- + +# Spec: Align selectable-row icons with their labels + +## Requirements + +The selection indicator and leading content use a line-height-sized alignment box so their visual +centers match the row's first-line label whether or not a description exists. Multiple leading +elements use the existing inline gap token, separating the Provider availability dot from its +brand mark. Selection, disabled behavior, accessible names, descriptions, and provider behavior +remain unchanged. + +## User experience + +Not separately recorded in legacy change.md. + +## Technical design + +See Requirements and legacy Git history. + +## Security and privacy + +See migrated Decision and gates. + +## Alternatives and non-goals + +Not separately recorded in legacy change.md. + +## Areas of concern + +The user directly accepted this low-risk visual correction on 2026-08-31. No security, +data-migration, release, or production Gate applies. Human review remains required before merge, +and no external delivery action is authorized. + +## Acceptance criteria + +- [x] AC-1: In description-bearing selectable rows, the selection indicator and provider mark are + centered on the first-line label rather than its top edge. +- [x] AC-2: The Provider availability dot and brand mark have visible tokenized spacing while all + rows retain consistent text and icon columns. +- [x] AC-3: Focused/full desktop tests, renderer build, desktop/narrow Browser inspection, and + repository lifecycle checks pass. + +## Decision + +The user directly accepted this low-risk visual correction on 2026-08-31. No security, +data-migration, release, or production Gate applies. Human review remains required before merge, +and no external delivery action is authorized. diff --git a/docs/sdlc/changes/2026-08-31-align-selectable-row-icons/verification.md b/docs/sdlc/changes/2026-08-31-align-selectable-row-icons/verification.md new file mode 100644 index 00000000..2e3e1cf6 --- /dev/null +++ b/docs/sdlc/changes/2026-08-31-align-selectable-row-icons/verification.md @@ -0,0 +1,101 @@ +--- +id: "2026-08-31-align-selectable-row-icons" +stage: verification +schema: 3 +status: passed +owner: codex +created: 2026-08-31 +based_on: plan.md +commit: "" +verification_mode: owner +verified_by: "codex" +verified_at: "2026-08-31" +release_target: none +release_identity: "not applicable until released." +--- + +# Verification: Align selectable-row icons with their labels + +## Automated checks + +Verdict: verified. + +### Acceptance evidence + +- AC-1: PASS — Browser `evaluate()` geometry on the same rendered Provider picker measured the provider mark + 3.5 px and the selection indicator 2.5 px above the first-line label before the change. After + the change, indicator, leading slot, status dot, provider mark, and label shared the exact same + center line on Claude Code, Codex, Grok, and Cursor rows. +- AC-2: PASS — computed layout reported a 4 px `gap-inline` between the 6 px availability dot and + 14 px provider mark, with stable indicator and text columns. Desktop and 560x760 screenshots are + `/tmp/codetwo-provider-icons-aligned-desktop.png` and + `/tmp/codetwo-provider-icons-aligned-narrow.png`. +- AC-3: PASS — `bun test tests/designSystemBusinessComponents.test.tsx` passed 8 tests with 56 + expectations; after rebasing onto the latest `origin/main`, full `bun test` passed 774 tests with + 3,682 expectations and zero failures; + `bunx tsc --noEmit` and `bun run build:renderer` passed. Browser checks at desktop and 560x760 + verified page identity, meaningful content, no framework overlay, no horizontal overflow, and no + console warning/error. Repository lifecycle checks are recorded by the final Gate run after this + Artifact update. + +Residual risk: Browser validation covers the shared production renderer rather than restarting the +user's already-running native desktop application. Other rows using `SelectableRow` inherit the +same semantic first-line alignment, which is intentional. + +## Behavioral evidence + +Verdict: verified. + +### Acceptance evidence + +- AC-1: PASS — Browser `evaluate()` geometry on the same rendered Provider picker measured the provider mark + 3.5 px and the selection indicator 2.5 px above the first-line label before the change. After + the change, indicator, leading slot, status dot, provider mark, and label shared the exact same + center line on Claude Code, Codex, Grok, and Cursor rows. +- AC-2: PASS — computed layout reported a 4 px `gap-inline` between the 6 px availability dot and + 14 px provider mark, with stable indicator and text columns. Desktop and 560x760 screenshots are + `/tmp/codetwo-provider-icons-aligned-desktop.png` and + `/tmp/codetwo-provider-icons-aligned-narrow.png`. +- AC-3: PASS — `bun test tests/designSystemBusinessComponents.test.tsx` passed 8 tests with 56 + expectations; after rebasing onto the latest `origin/main`, full `bun test` passed 774 tests with + 3,682 expectations and zero failures; + `bunx tsc --noEmit` and `bun run build:renderer` passed. Browser checks at desktop and 560x760 + verified page identity, meaningful content, no framework overlay, no horizontal overflow, and no + console warning/error. Repository lifecycle checks are recorded by the final Gate run after this + Artifact update. + +Residual risk: Browser validation covers the shared production renderer rather than restarting the +user's already-running native desktop application. Other rows using `SelectableRow` inherit the +same semantic first-line alignment, which is intentional. + +## Visual evidence + +See bundle evidence/ when present. + +## Security and privacy evidence + +Not separately recorded unless present in legacy Verification. + +## Deviations and residual risk + +Residual risk: Browser validation covers the shared production renderer rather than restarting the + +## Verdict + +Verdict: verified.. + +## Review and release + +Review handoff: [Draft PR #204](https://github.com/IchenDEV/codeTwo/pull/204). +Approval: [user via the 2026-08-31 direct icon-alignment request] approved on 2026-08-31. human review. +Release target: none. +Release identity: not applicable until released. +Smoke evidence: not applicable until released. +Rollback: revert this change to restore the previous top-aligned icon layout. +No release: the current request authorizes only local implementation and verification. + +Preparing this section does not authorize merge, deployment, release, or production mutation. + +## Feedback + +No post-change feedback exists yet. diff --git a/docs/sdlc/changes/2026-08-31-codex-appearance-controls/change.md b/docs/sdlc/changes/2026-08-31-codex-appearance-controls/change.md deleted file mode 100644 index 2ffad3c4..00000000 --- a/docs/sdlc/changes/2026-08-31-codex-appearance-controls/change.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -id: change-2026-08-31-codex-appearance-controls -kind: change -schema: 2 -status: verified -risk: medium -owner: codex -approvers: [user] -approved_at: 2026-08-31 -created: 2026-08-31 -updated: 2026-08-31 -source: direct user request in the current task on 2026-08-31 after a screenshot comparison — “补齐codex功能” -inputs: the supplied Codex Appearance screenshot, the current C2 Appearance page, and the existing appearance persistence contract -outputs: scheme-specific theme controls plus persisted cursor, motion, and diff-marker preferences with rendered verification -scope: apps/desktop/src/appearance.ts, apps/desktop/src/theme.tsx, apps/desktop/src/settings, apps/desktop/src/i18n/strings.ts, apps/desktop/src/styles.css, apps/desktop/src/design, apps/desktop/src/canvas/styles.css, apps/desktop/src/git, apps/desktop/src/files/FileViewer.tsx, apps/desktop/tests/appearanceSettings.test.tsx, apps/desktop/tests/gitState.test.ts, apps/desktop/tests/githubPullRequestPanelRendered.test.tsx, apps/desktop/tests/settingsLayoutContract.test.ts, docs/sdlc/changes/2026-08-31-codex-appearance-controls -next_trigger: human review and feedback -verification_mode: owner -verified_by: codex -verified_at: 2026-08-31 ---- - -# Complete the Codex-aligned Appearance controls - -## Intent - -The current C2 Appearance page already offers schemes, a reusable theme library, editable light -and dark colors, global typography, panel opacity, and contrast. Compared with the supplied Codex -Appearance screenshot, C2 cannot tune font family, font weight, panel treatment, and contrast -independently for light and dark schemes, and it has no user controls for pointer cursors, reduced -motion, or diff markers. - -The desired outcome is to retain C2's stronger theme-library workflow while adding those useful -Codex controls as real persisted behavior. Existing users must keep their current visual choices -after migration. A Dock-icon picker is not part of this change because the repository contains one -approved icon family and Electrobun 1.18.1 exposes only build-time application icons; inventing a -second icon or displaying a nonfunctional picker would not satisfy the request. - -## Spec - -- Appearance persistence advances to schema version 3. Version-2 global font, opacity, and contrast - values migrate into both light and dark scheme profiles without changing the rendered result. -- Light and dark scheme profiles independently own interface font and weight, code font and weight, - panel opacity, and contrast. The active resolved scheme selects the applied profile. -- Interface and code font sizes remain global preferences, matching the supplied Codex behavior. -- “Use pointer cursors” changes pointer styling for interactive controls without affecting resize, - drag, text-edit, or disabled cursors. -- “Reduce motion” supports System, On, and Off. System follows macOS, On suppresses decorative - transitions regardless of macOS, and Off preserves motion even when macOS requests reduction. -- “Diff markers” supports Color and +/-. Color uses semantic add/delete color treatment without - redundant prefix glyphs; +/- uses explicit prefix glyphs without relying on color. -- Controls use the existing C2 setting rows, switches, select menus, range controls, focus styles, - responsive grouping, and bilingual strings. No new runtime dependency is added. -- Existing theme JSON format, theme library, pet settings, color scheme selection, and Restore - defaults remain backward compatible. - -### Acceptance criteria - -- [x] AC-1: Light and dark font family/weight, panel opacity, and contrast values can be changed - independently, persist, and apply when the resolved scheme changes. -- [x] AC-2: Pointer-cursor and reduced-motion controls visibly change interactive cursor and motion - behavior for all three supported preference states without breaking drag/resize affordances. -- [x] AC-3: Diff-marker controls switch both local Git and GitHub PR previews between color-only and - explicit +/- presentations, with neither mode relying only on an inaccessible hidden state. -- [x] AC-4: Version-1/2 appearance data migrates to version 3 without losing current theme, pet, - font-size, font-family, panel-opacity, or contrast choices; theme import/export remains valid. -- [x] AC-5: Targeted tests, renderer lint/type/build, repository lifecycle checks, and rendered - light, dark, and narrow Appearance-page inspection pass. - -## Decision and gates - -The user directly approved Intent and implementation through the current request. Codex owns the -implementation and verification. Dock-icon artwork/design, merge, release, deployment, production, -and external messaging remain separate human Gates and are not authorized here. - -Apple HIG Settings, Accessibility, Color, Typography, Sliders, Toggles, and Motion guidance informs -the native control semantics: settings stay comprehensible, controls have visible labels and focus, -system preferences remain available, and color is not the only diff cue in the +/- mode. - -## Plan - -1. Add a version-3 appearance profile model and deterministic migration from existing settings. -2. Apply the resolved light/dark profile, pointer, motion, font-weight, and diff-marker state at the - document root. -3. Extend the Appearance page with scheme-specific groups and Codex preference controls using the - current C2 component system and translations. -4. Update diff rendering and reduced-motion selectors to honor explicit user preferences. -5. Add migration/interaction/rendering coverage, run repository Gates, and capture rendered light, - dark, and narrow evidence. - -Rollback is a source revert; persisted version-3 data is additive and old builds ignore the new -fields while retaining the existing storage key. No network, provider, database, or release change -is involved. - -## Build - -Appearance persistence now uses version 3. Each light/dark profile owns its interface and code font -family and weight, panel opacity, and contrast, while sizes remain shared. Version-1/2 values are -copied into both profiles during migration, so the active appearance does not change unexpectedly. -The resolved profile is applied to the document and Monaco editor. - -The Appearance page now exposes the two typography and surface profiles, pointer-cursor, System / -On / Off reduced-motion, and Color / +/- diff-marker controls with English and Chinese labels. -Local Git and GitHub PR diff lines share an accessible marker/content presentation. Explicit motion -preferences override the system media query without changing drag, resize, text, or disabled -cursors. No dependency, provider, database, network, or theme-document format changed. - -## Verification - -Verdict: verified. - -Browser inspection used the in-app Browser against the renderer at `http://localhost:1421/`. -Appearance rendered correctly in light and dark modes and at a narrow 820x900 viewport, with no -horizontal overflow, framework overlay, or console warning/error. Real interaction showed the -active dark font weight applying as 500 while light remained 400, pointer cursor switching between -`pointer` and `default`, and explicit motion switching transition duration from `0.12s` to -`0.00001s`. Restore defaults returned pointer, motion, diff mode, weight, and opacity to their -documented values. - -### Acceptance evidence - -- AC-1: PASS — `cd apps/desktop && bun test tests/appearanceSettings.test.tsx` proves independent - persistence and runtime application; rendered interaction confirmed dark weight 500 while light - stayed 400 when switching schemes. -- AC-2: PASS — `cd apps/desktop && bun test tests/appearanceSettings.test.tsx` covers every root - preference value; rendered interaction confirmed pointer and motion changes, while scoped CSS - preserves text, drag, resize, and disabled cursors. -- AC-3: PASS — `cd apps/desktop && bun test tests/gitState.test.ts` and - `bun test tests/githubPullRequestPanelRendered.test.tsx` assert separate visible markers, - content, and added/removed accessible labels; both modes are selected from the shared root state. -- AC-4: PASS — `cd apps/desktop && bun test tests/appearanceSettings.test.tsx` covers version-1/2 - migration, defaults, persisted profiles, and existing theme data; `cd apps/desktop && bun test` - passed 794 tests in 137 files with 3,783 expectations. -- AC-5: PASS — `bunx tsc --noEmit`, `bun run lint`, and `bun run build:renderer` passed; Browser - light/dark/narrow inspection passed; `bun script/verify/docs.ts`, `bun script/verify/sdlc.ts`, and - `bun script/verify/sdlc.ts --worktree` passed. - -Residual risk: the preference state applies within the renderer process; a future native Dock-icon -picker still requires approved alternate artwork and a supported runtime integration. The existing -Vite large-chunk warning and React test `act(...)` notices remain pre-existing, non-failing signals. - -## Review and release - -Review handoff: [Draft PR #207](https://github.com/IchenDEV/codeTwo/pull/207). -Approval: pending human review of the verified Appearance page. -Release target: none. -Release identity: not applicable until released. -Smoke evidence: not applicable until released. -Rollback: revert this change's appearance model, controls, presentation styles, tests, and Artifact. -No release: no merge, release, or deployment was requested. - -Preparing this section does not authorize merge, deployment, release, or production mutation. - -## Feedback - -No post-implementation feedback exists yet. diff --git a/docs/sdlc/changes/2026-08-31-codex-appearance-controls/intent.md b/docs/sdlc/changes/2026-08-31-codex-appearance-controls/intent.md new file mode 100644 index 00000000..50f7d4fd --- /dev/null +++ b/docs/sdlc/changes/2026-08-31-codex-appearance-controls/intent.md @@ -0,0 +1,68 @@ +--- +id: "2026-08-31-codex-appearance-controls" +stage: intent +schema: 3 +status: accepted +owner: codex +created: 2026-08-31 +source: direct user request in the current task on 2026-08-31 after a screenshot comparison — “补齐codex功能” +risk: medium +approved_by: "[user]" +approved_at: "2026-08-31" +--- + +# Intent: Complete the Codex-aligned Appearance controls + +## Problem + +The current C2 Appearance page already offers schemes, a reusable theme library, editable light +and dark colors, global typography, panel opacity, and contrast. Compared with the supplied Codex +Appearance screenshot, C2 cannot tune font family, font weight, panel treatment, and contrast +independently for light and dark schemes, and it has no user controls for pointer cursors, reduced +motion, or diff markers. + +The desired outcome is to retain C2's stronger theme-library workflow while adding those useful +Codex controls as real persisted behavior. Existing users must keep their current visual choices +after migration. A Dock-icon picker is not part of this change because the repository contains one +approved icon family and Electrobun 1.18.1 exposes only build-time application icons; inventing a +second icon or displaying a nonfunctional picker would not satisfy the request. + +## Proposed outcome + +The current C2 Appearance page already offers schemes, a reusable theme library, editable light + +## Affected users and systems + +Migrated from legacy change.md. + +## Constraints + +The user directly approved Intent and implementation through the current request. Codex owns the +implementation and verification. Dock-icon artwork/design, merge, release, deployment, production, +and external messaging remain separate human Gates and are not authorized here. + +Apple HIG Settings, Accessibility, Color, Typography, Sliders, Toggles, and Motion guidance informs +the native control semantics: settings stay comprehensible, controls have visible labels and focus, +system preferences remain available, and color is not the only diff cue in the +/- mode. + +## Out of scope + +Not recorded in the legacy single-file Artifact. + +## Success signals + +See Spec acceptance criteria. + +## Open questions + +None recorded in migration. + +## Decision + +The user directly approved Intent and implementation through the current request. Codex owns the +implementation and verification. Dock-icon artwork/design, merge, release, deployment, production, +and external messaging remain separate human Gates and are not authorized here. + +Apple HIG Settings, Accessibility, Color, Typography, Sliders, Toggles, and Motion guidance informs +the native control semantics: settings stay comprehensible, controls have visible labels and focus, +system preferences remain available, and color is not the only diff cue in the +/- mode. diff --git a/docs/sdlc/changes/2026-08-31-codex-appearance-controls/plan.md b/docs/sdlc/changes/2026-08-31-codex-appearance-controls/plan.md new file mode 100644 index 00000000..9a44bed1 --- /dev/null +++ b/docs/sdlc/changes/2026-08-31-codex-appearance-controls/plan.md @@ -0,0 +1,73 @@ +--- +id: "2026-08-31-codex-appearance-controls" +stage: plan +schema: 3 +status: accepted +owner: codex +created: 2026-08-31 +based_on: spec.md +risk: medium +scope: apps/desktop/src/appearance.ts, apps/desktop/src/theme.tsx, apps/desktop/src/settings, apps/desktop/src/i18n/strings.ts, apps/desktop/src/styles.css, apps/desktop/src/design, apps/desktop/src/canvas/styles.css, apps/desktop/src/git, apps/desktop/src/files/FileViewer.tsx, apps/desktop/tests/appearanceSettings.test.tsx, apps/desktop/tests/gitState.test.ts, apps/desktop/tests/githubPullRequestPanelRendered.test.tsx, apps/desktop/tests/settingsLayoutContract.test.ts, docs/sdlc/changes/2026-08-31-codex-appearance-controls +approved_by: "[user]" +approved_at: "2026-08-31" +--- + +# Plan: Complete the Codex-aligned Appearance controls + +## Files and ownership + +apps/desktop/src/appearance.ts, apps/desktop/src/theme.tsx, apps/desktop/src/settings, apps/desktop/src/i18n/strings.ts, apps/desktop/src/styles.css, apps/desktop/src/design, apps/desktop/src/canvas/styles.css, apps/desktop/src/git, apps/desktop/src/files/FileViewer.tsx, apps/desktop/tests/appearanceSettings.test.tsx, apps/desktop/tests/gitState.test.ts, apps/desktop/tests/githubPullRequestPanelRendered.test.tsx, apps/desktop/tests/settingsLayoutContract.test.ts, docs/sdlc/changes/2026-08-31-codex-appearance-controls + +## Order of work + +1. Add a version-3 appearance profile model and deterministic migration from existing settings. +2. Apply the resolved light/dark profile, pointer, motion, font-weight, and diff-marker state at the + document root. +3. Extend the Appearance page with scheme-specific groups and Codex preference controls using the + current C2 component system and translations. +4. Update diff rendering and reduced-motion selectors to honor explicit user preferences. +5. Add migration/interaction/rendering coverage, run repository Gates, and capture rendered light, + dark, and narrow evidence. + +Rollback is a source revert; persisted version-3 data is additive and old builds ignore the new +fields while retaining the existing storage key. No network, provider, database, or release change +is involved. + +## Test-first proof + +See legacy Verification section. + +## Visual or integration proof + +See legacy Verification section. + +## Risks and mitigations + +See legacy Decision and gates. + +## Rollback + +See legacy Review and release. + +## Deviations + +Appearance persistence now uses version 3. Each light/dark profile owns its interface and code font +family and weight, panel opacity, and contrast, while sizes remain shared. Version-1/2 values are +copied into both profiles during migration, so the active appearance does not change unexpectedly. +The resolved profile is applied to the document and Monaco editor. + +The Appearance page now exposes the two typography and surface profiles, pointer-cursor, System / +On / Off reduced-motion, and Color / +/- diff-marker controls with English and Chinese labels. +Local Git and GitHub PR diff lines share an accessible marker/content presentation. Explicit motion +preferences override the system media query without changing drag, resize, text, or disabled +cursors. No dependency, provider, database, network, or theme-document format changed. + +## Decision + +The user directly approved Intent and implementation through the current request. Codex owns the +implementation and verification. Dock-icon artwork/design, merge, release, deployment, production, +and external messaging remain separate human Gates and are not authorized here. + +Apple HIG Settings, Accessibility, Color, Typography, Sliders, Toggles, and Motion guidance informs +the native control semantics: settings stay comprehensible, controls have visible labels and focus, +system preferences remain available, and color is not the only diff cue in the +/- mode. diff --git a/docs/sdlc/changes/2026-08-31-codex-appearance-controls/spec.md b/docs/sdlc/changes/2026-08-31-codex-appearance-controls/spec.md new file mode 100644 index 00000000..a5c82986 --- /dev/null +++ b/docs/sdlc/changes/2026-08-31-codex-appearance-controls/spec.md @@ -0,0 +1,81 @@ +--- +id: "2026-08-31-codex-appearance-controls" +stage: spec +schema: 3 +status: accepted +owner: codex +created: 2026-08-31 +based_on: intent.md +risk: medium +approved_by: "[user]" +approved_at: "2026-08-31" +--- + +# Spec: Complete the Codex-aligned Appearance controls + +## Requirements + +- Appearance persistence advances to schema version 3. Version-2 global font, opacity, and contrast + values migrate into both light and dark scheme profiles without changing the rendered result. +- Light and dark scheme profiles independently own interface font and weight, code font and weight, + panel opacity, and contrast. The active resolved scheme selects the applied profile. +- Interface and code font sizes remain global preferences, matching the supplied Codex behavior. +- “Use pointer cursors” changes pointer styling for interactive controls without affecting resize, + drag, text-edit, or disabled cursors. +- “Reduce motion” supports System, On, and Off. System follows macOS, On suppresses decorative + transitions regardless of macOS, and Off preserves motion even when macOS requests reduction. +- “Diff markers” supports Color and +/-. Color uses semantic add/delete color treatment without + redundant prefix glyphs; +/- uses explicit prefix glyphs without relying on color. +- Controls use the existing C2 setting rows, switches, select menus, range controls, focus styles, + responsive grouping, and bilingual strings. No new runtime dependency is added. +- Existing theme JSON format, theme library, pet settings, color scheme selection, and Restore + defaults remain backward compatible. + +## User experience + +Not separately recorded in legacy change.md. + +## Technical design + +See Requirements and legacy Git history. + +## Security and privacy + +See migrated Decision and gates. + +## Alternatives and non-goals + +Not separately recorded in legacy change.md. + +## Areas of concern + +The user directly approved Intent and implementation through the current request. Codex owns the +implementation and verification. Dock-icon artwork/design, merge, release, deployment, production, +and external messaging remain separate human Gates and are not authorized here. + +Apple HIG Settings, Accessibility, Color, Typography, Sliders, Toggles, and Motion guidance informs +the native control semantics: settings stay comprehensible, controls have visible labels and focus, +system preferences remain available, and color is not the only diff cue in the +/- mode. + +## Acceptance criteria + +- [x] AC-1: Light and dark font family/weight, panel opacity, and contrast values can be changed + independently, persist, and apply when the resolved scheme changes. +- [x] AC-2: Pointer-cursor and reduced-motion controls visibly change interactive cursor and motion + behavior for all three supported preference states without breaking drag/resize affordances. +- [x] AC-3: Diff-marker controls switch both local Git and GitHub PR previews between color-only and + explicit +/- presentations, with neither mode relying only on an inaccessible hidden state. +- [x] AC-4: Version-1/2 appearance data migrates to version 3 without losing current theme, pet, + font-size, font-family, panel-opacity, or contrast choices; theme import/export remains valid. +- [x] AC-5: Targeted tests, renderer lint/type/build, repository lifecycle checks, and rendered + light, dark, and narrow Appearance-page inspection pass. + +## Decision + +The user directly approved Intent and implementation through the current request. Codex owns the +implementation and verification. Dock-icon artwork/design, merge, release, deployment, production, +and external messaging remain separate human Gates and are not authorized here. + +Apple HIG Settings, Accessibility, Color, Typography, Sliders, Toggles, and Motion guidance informs +the native control semantics: settings stay comprehensible, controls have visible labels and focus, +system preferences remain available, and color is not the only diff cue in the +/- mode. diff --git a/docs/sdlc/changes/2026-08-31-codex-appearance-controls/verification.md b/docs/sdlc/changes/2026-08-31-codex-appearance-controls/verification.md new file mode 100644 index 00000000..265f42f5 --- /dev/null +++ b/docs/sdlc/changes/2026-08-31-codex-appearance-controls/verification.md @@ -0,0 +1,117 @@ +--- +id: "2026-08-31-codex-appearance-controls" +stage: verification +schema: 3 +status: passed +owner: codex +created: 2026-08-31 +based_on: plan.md +commit: "" +verification_mode: owner +verified_by: "codex" +verified_at: "2026-08-31" +release_target: none +release_identity: "not applicable until released." +--- + +# Verification: Complete the Codex-aligned Appearance controls + +## Automated checks + +Verdict: verified. + +Browser inspection used the in-app Browser against the renderer at `http://localhost:1421/`. +Appearance rendered correctly in light and dark modes and at a narrow 820x900 viewport, with no +horizontal overflow, framework overlay, or console warning/error. Real interaction showed the +active dark font weight applying as 500 while light remained 400, pointer cursor switching between +`pointer` and `default`, and explicit motion switching transition duration from `0.12s` to +`0.00001s`. Restore defaults returned pointer, motion, diff mode, weight, and opacity to their +documented values. + +### Acceptance evidence + +- AC-1: PASS — `cd apps/desktop && bun test tests/appearanceSettings.test.tsx` proves independent + persistence and runtime application; rendered interaction confirmed dark weight 500 while light + stayed 400 when switching schemes. +- AC-2: PASS — `cd apps/desktop && bun test tests/appearanceSettings.test.tsx` covers every root + preference value; rendered interaction confirmed pointer and motion changes, while scoped CSS + preserves text, drag, resize, and disabled cursors. +- AC-3: PASS — `cd apps/desktop && bun test tests/gitState.test.ts` and + `bun test tests/githubPullRequestPanelRendered.test.tsx` assert separate visible markers, + content, and added/removed accessible labels; both modes are selected from the shared root state. +- AC-4: PASS — `cd apps/desktop && bun test tests/appearanceSettings.test.tsx` covers version-1/2 + migration, defaults, persisted profiles, and existing theme data; `cd apps/desktop && bun test` + passed 794 tests in 137 files with 3,783 expectations. +- AC-5: PASS — `bunx tsc --noEmit`, `bun run lint`, and `bun run build:renderer` passed; Browser + light/dark/narrow inspection passed; `bun script/verify/docs.ts`, `bun script/verify/sdlc.ts`, and + `bun script/verify/sdlc.ts --worktree` passed. + +Residual risk: the preference state applies within the renderer process; a future native Dock-icon +picker still requires approved alternate artwork and a supported runtime integration. The existing +Vite large-chunk warning and React test `act(...)` notices remain pre-existing, non-failing signals. + +## Behavioral evidence + +Verdict: verified. + +Browser inspection used the in-app Browser against the renderer at `http://localhost:1421/`. +Appearance rendered correctly in light and dark modes and at a narrow 820x900 viewport, with no +horizontal overflow, framework overlay, or console warning/error. Real interaction showed the +active dark font weight applying as 500 while light remained 400, pointer cursor switching between +`pointer` and `default`, and explicit motion switching transition duration from `0.12s` to +`0.00001s`. Restore defaults returned pointer, motion, diff mode, weight, and opacity to their +documented values. + +### Acceptance evidence + +- AC-1: PASS — `cd apps/desktop && bun test tests/appearanceSettings.test.tsx` proves independent + persistence and runtime application; rendered interaction confirmed dark weight 500 while light + stayed 400 when switching schemes. +- AC-2: PASS — `cd apps/desktop && bun test tests/appearanceSettings.test.tsx` covers every root + preference value; rendered interaction confirmed pointer and motion changes, while scoped CSS + preserves text, drag, resize, and disabled cursors. +- AC-3: PASS — `cd apps/desktop && bun test tests/gitState.test.ts` and + `bun test tests/githubPullRequestPanelRendered.test.tsx` assert separate visible markers, + content, and added/removed accessible labels; both modes are selected from the shared root state. +- AC-4: PASS — `cd apps/desktop && bun test tests/appearanceSettings.test.tsx` covers version-1/2 + migration, defaults, persisted profiles, and existing theme data; `cd apps/desktop && bun test` + passed 794 tests in 137 files with 3,783 expectations. +- AC-5: PASS — `bunx tsc --noEmit`, `bun run lint`, and `bun run build:renderer` passed; Browser + light/dark/narrow inspection passed; `bun script/verify/docs.ts`, `bun script/verify/sdlc.ts`, and + `bun script/verify/sdlc.ts --worktree` passed. + +Residual risk: the preference state applies within the renderer process; a future native Dock-icon +picker still requires approved alternate artwork and a supported runtime integration. The existing +Vite large-chunk warning and React test `act(...)` notices remain pre-existing, non-failing signals. + +## Visual evidence + +See bundle evidence/ when present. + +## Security and privacy evidence + +Not separately recorded unless present in legacy Verification. + +## Deviations and residual risk + +Residual risk: the preference state applies within the renderer process; a future native Dock-icon + +## Verdict + +Verdict: verified.. + +## Review and release + +Review handoff: [Draft PR #207](https://github.com/IchenDEV/codeTwo/pull/207). +Approval: [user] approved on 2026-08-31. human review of the verified Appearance page. +Release target: none. +Release identity: not applicable until released. +Smoke evidence: not applicable until released. +Rollback: revert this change's appearance model, controls, presentation styles, tests, and Artifact. +No release: no merge, release, or deployment was requested. + +Preparing this section does not authorize merge, deployment, release, or production mutation. + +## Feedback + +No post-implementation feedback exists yet. diff --git a/docs/sdlc/changes/2026-08-31-codex-design-system/change.md b/docs/sdlc/changes/2026-08-31-codex-design-system/change.md deleted file mode 100644 index d57344b3..00000000 --- a/docs/sdlc/changes/2026-08-31-codex-design-system/change.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -id: change-2026-08-31-codex-design-system -kind: change -schema: 2 -status: verified -risk: medium -owner: codex -approvers: [user] -approved_at: 2026-08-31 -created: 2026-08-31 -updated: 2026-08-31 -source: direct user requests and visual feedback in the 2026-08-31 design-system review -inputs: docs/design/system.md, docs/archive/research/codex-app-typography-layout-2026-08-31.md, and the live component preview -outputs: Codex-aligned typography and theme tokens, shared controls and business patterns, migrated desktop call sites, lint enforcement, and an expanded design-system preview -scope: apps/desktop/src, apps/desktop/tests, apps/desktop/eslint.config.mjs, docs/design/system.md, docs/archive/research/codex-app-typography-layout-2026-08-31.md -next_trigger: deterministic verification completes and the Draft PR is ready for human design review -verification_mode: owner -verified_by: codex -verified_at: 2026-08-31 ---- - -# Align the desktop design system with Codex - -## Intent - -The desktop UI mixed compact legacy metrics, page-local colors and radii, raw controls, manual -widget roles, native title tooltips, and one-off card or menu surfaces. The user asked to match the -comfortable density of the Codex desktop app, centralize every component under one theme system, -lighten heavy surfaces and shadows, and add restrained translucent material to transient menus. - -The desired result is one semantic typography and geometry engine, one theme contract for light -and dark appearance, and shared primitives or business patterns at product call sites. Provider -protocols, persistence, data migrations, releases, and deployment are out of scope. - -## Spec - -The accepted product law is [the C2 design system](../../../design/system.md), informed by the -[Codex typography inventory](../../../archive/research/codex-app-typography-layout-2026-08-31.md). -Persistent planes remain quiet and solid. Menus, popovers, tooltips, and dialogs use the shared -raised-material tokens with restrained translucency, blur, hairline, and shadow. Typography, -spacing, radii, control heights, state colors, and accessibility preferences resolve through shared -tokens and components. Product-owned buttons, textareas, tabs, radio choices, selectable rows, and -notices must use the managed component layer. - -Standard ESLint and Stylelint rules enforce source-level boundaries. Repository-specific scanners, -generated debt baselines, and broad allowlists are intentionally not part of the final architecture. - -### Acceptance criteria - -- [x] AC-1: `bun run lint` rejects raw product buttons and textareas, inline radii, and restricted - radius utilities while the maintained source passes. -- [x] AC-2: Type checking and the desktop test suite pass with the latest `main` functionality - preserved. -- [x] AC-3: The renderer production build succeeds and emits the semantic theme and typography - utilities. -- [x] AC-4: The repository lifecycle and diff checks pass with no stale scanner or debt-baseline - dependency. -- [x] AC-5: The design preview remains available for human review in light and dark appearance; - merge and release remain separate human Gates. - -## Decision and gates - -The user approved Intent and iterative implementation in the current conversation. The accepted -design direction is the Codex desktop density with the user's color, shadow, and glass feedback. -Security, data, merge, release, deployment, and production Gates are not granted by this change. - -## Plan - -1. Define semantic typography, theme, spacing, geometry, elevation, and accessibility tokens. -2. Deepen shared primitives and business patterns, then migrate confirmed unmanaged callers. -3. Rebase onto current `main`, preserve newer application behavior, and express enforceable rules - through ESLint and Stylelint. -4. Run lint, types, tests, build, lifecycle, diff, and rendered-preview checks. -5. Publish a Draft PR for human design review without merging it. - -## Build - -Implementation is complete on `codex/codex-aligned-design-system`. Material changes include the -semantic typography and theme modules, comfortable control geometry, shared TooltipButton, -RadioGroup and ChoiceRow families, shared selectable/detail patterns, translucent raised layers, -and product call-site migrations. During rebase, the obsolete custom design checker and its -allowlist/baseline were removed in favor of the current repository lint architecture. - -## Verification - -Verdict: verified. - -The implementation satisfies the accepted source, type, test, build, lifecycle, and review-surface -criteria. Merge, release, and deployment remain outside this verdict. - -### Acceptance evidence - -- AC-1: PASS — `bun run lint` passed. ESLint and Stylelint report zero warnings, and product JSX has no raw - `