Add Devil's Advocate Analysis (2026-04-03)

docs/devils-advocate/2026-04-03.md

@@ -0,0 +1,25 @@
+# Devil's Advocate Analysis of reibitto/command-center
+**Date: April 3, 2026**
+**Focus: Repository Structure, Organization, and Content**
+
+## 1. Repository Structure & Organization
+- **Modular vs. Complex Build System**: The project uses a highly modular SBT setup with files like `project/Build.scala`, `project/OS.scala`, `project/Plugins.scala`, `project/SwtInfo.scala`, and `project/V.scala`. While this follows Scala best practices for dependency management, it introduces significant complexity for new contributors. The build itself is platform-dependent, as logic for platform-specific dependencies (like SWT) is baked directly into these Scala build files. This "build-time OS detection" can be opaque and hard to debug.
+- **Directory Fragmentation**: The repository has both a `bin/` and a `tools/` directory at the top level. Consolidating these would improve clarity—using `bin/` for executable wrappers and `tools/` for build-time helpers or auxiliary source code.
+- **Platform-Specific Tools Placement**: The `tools/macos` directory contains raw Swift source code (`main.swift`). This is poorly integrated into the main build process. The README requires manual compilation and placement of the `cc-tools` executable. A better approach would be to automate this compilation within the SBT build or provide a pre-compiled binary via a clearer release mechanism.
+
+## 2. Content & Implementation Analysis
+- **OS Support Discrepancies**: The project claims to be "cross-platform" but key features are platform-restricted (e.g., Window Manager for Windows only, SuspendProcessCommand for macOS only). This creates a fragmented user experience, especially for Linux users who may find the "cross-platform" label misleading for their specific use case.
+- **Plugin Activation Ambiguity**: The README mentions enabling optional plugins via environment variables (`COMMAND_CENTER_PLUGINS`) or SBT options. However, the `application.conf` lists commands in a hardcoded format. It’s unclear whether editing the config is sufficient or if the environment variable is a strict prerequisite for loading the code, leading to potential implementation issues for users.
+- **Compatibility Issues (Terminal Emulator vs. Native CLI)**: While marketed as a "CLI-based launcher," certain features (like the Kanji stroke order plugin) require the built-in terminal emulator because native terminal clients don’t support the necessary visual rendering. This creates a contradiction: the tool is CLI-based but not fully compatible with standard CLI environments (iTerm2, Terminal.app).
+- **Configuration Search Order Conflicts**: The README lists a global config (`~/.command-center/application.conf`) as having higher precedence than the local repository config (`./application.conf`). In a development or testing environment, this can lead to "silent" configuration conflicts where changes in the repository are ignored because of a pre-existing global config.
+
+## 3. CI/CD & Testing
+- **Lack of Cross-Platform CI**: The project’s CI (`.github/workflows/scala.yml`) only runs on `ubuntu-latest`. For a tool that relies heavily on OS-specific implementations for its core features, this is a major gap. Platform-specific regressions (on macOS/Windows) are currently not caught by automated testing.
+- **Basic Automation**: The CI performs only basic checks (`fmtCheck` and `test`). There is no automated release pipeline, Docker build, or native image (GraalVM) generation, despite native image support being a key selling point in the README.
+
+## 4. Recommendations
+- **Consolidate `bin/` and `tools/`** to simplify repository structure.
+- **Automate Platform-Specific Tool Builds** (e.g., the macOS Swift tool) within the main SBT project to lower the barrier for installation.
+- **Expand CI Matrix** to include `macos-latest` and `windows-latest` to ensure true cross-platform stability.
+- **Clarify Configuration Precedence** in the README and potentially warn users if a global config is overriding a local one.
+- **Enhance Release Automation** to include native image builds for all supported platforms.

docs/devils-advocate/2026-04-08.md

@@ -0,0 +1,26 @@
+# Devil's Advocate Analysis of Command Center Repository Structure
+**Date:** 2026-04-08
+**Focus:** Repository structure, organization, and internal content inconsistencies.
+
+## 1. Repository Structure & Organization
+* **Directory Overlap (`bin/` vs `tools/`):** The repository maintains both a `bin/` directory (containing `cc-tools`) and a `tools/` directory. It is unclear if these are meant to be user-facing scripts vs. developer-only utilities. Consolidating these or clearly documenting the distinction would reduce ambiguity.
+* **Submodule Complexity:** The `extras/experimental` directory appears to be handled differently than other internal modules (like `extras/ject`). Mixing git submodules with standard project directories can lead to "hidden" dependencies and CI/CD synchronization issues.
+* **Documentation Gaps:** While the `README.md` is comprehensive regarding features, it doesn't explicitly map the physical directory structure (e.g., explaining that "plugins" live in `extras/`). This creates a steep learning curve for new developers.
+
+## 2. Content & Implementation Analysis
+* **Naming Inconsistencies:** There is a mismatch between feature naming in the `README.md` (e.g., "Kanji plugin") and module naming in `build.sbt` (e.g., `ject-plugin`). This can cause confusion during configuration or troubleshooting.
+* **Build File Density:** `build.sbt` is becoming a "God File," aggregating main modules, multiple emulator implementations, and conditional plugin loading. As the plugin ecosystem grows, this may become a maintenance bottleneck.
+* **UI Fragmentation:** The existence of `emulator-swing` and `emulator-swt` alongside `emulator-core` suggests significant UI abstraction. A "Devil's Advocate" view asks whether the maintenance cost of supporting two different Java UI toolkits is justified by the user base, or if one should be prioritized.
+
+## 3. Potential Edge Cases & Risks
+* **Platform-Specific "Leaking":** The presence of `tools/macos/` without clear Linux or Windows equivalents suggests the project might be "macOS-first" in practice, despite its "cross-platform" claim. This could lead to implementation issues on other platforms that go unnoticed.
+* **Configuration Silent Failures:** Enabling plugins via flags or environment variables is convenient but lacks a strong "fail-fast" mechanism. A typo in a plugin name could result in it not loading without providing explicit feedback to the user.
+
+## 4. Recommendations
+* **Consolidate Tools:** Merge or clearly define the roles of `bin/` and `tools/`.
+* **Standardize Naming:** Align README feature names with the underlying module names.
+* **Refactor Build:** Consider moving plugin-specific build logic into sub-projects or separate `.sbt` files to keep the root build manageable.
+* **Health Checks:** Implement a "plugin status" command or logging on startup to confirm which optional components successfully loaded.
+
+---
+*Report generated as part of automated repository audit.*

docs/devils-advocate/2026-04-09.md

@@ -0,0 +1,24 @@
+# Devil's Advocate Analysis - April 09, 2026
+
+## 1. Structural Fragmentation and Cognitive Load
+The repository architecture remains overly fragmented. With 10+ top-level modules (core, cli, core-ui, emulator-core, emulator-swing, emulator-swt, extras, tools, bin, etc.), the cognitive load for a new contributor is high. 
+- **The "Bin/Tools" Ambiguity:** The persistent overlap between `bin/` and `tools/` remains a primary point of confusion. This lack of clear ownership for scripts vs. utilities suggests a lack of organizational discipline.
+- **UI Proliferation:** Maintaining separate Swing and SWT implementations indicates a failure to commit to a unified cross-platform UI abstraction, likely leading to bug-ridden feature parity issues.
+
+## 2. Configuration and Plugin Paradoxes
+- **Silent Config Failures:** The current configuration precedence (Environment -> Home -> Local) is a trap for troubleshooting. Without a "status" or "debug" command to show exactly which `application.conf` is active, users are left guessing.
+- **Hidden Plugins:** The "plugin-first" claim is undermined by the lack of a standardized directory or registry. It is unclear which features are core and which are optional, making the system feel monolithic despite its modular claims.
+
+## 3. Implementation Fragility
+- **Language Detection Edge Cases:** Relying on automatic language detection for a command launcher introduces significant entropy. Potential for command misinterpretation is high, especially for developers using mixed-language snippets.
+- **JVM Overhead vs. "Low Resource" Claims:** The choice of the JVM/ZIO stack for a launcher tool inherently conflicts with the "low resource usage" marketing. Cold starts and heap management remain the "elephant in the room" compared to native alternatives.
+- **Testing Blind Spots:** If CI remains Ubuntu-centric, the "cross-platform" badge is effectively a marketing claim rather than a verified technical reality.
+
+## 4. Recommendations
+- Merge `bin/` and `tools/` into a single `scripts/` or `utils/` directory.
+- Standardize the plugin structure (e.g., `plugins/`).
+- Implement a `command-center health` command to audit the active config and system state.
+- Expand CI to include macOS and Windows runners to justify the cross-platform claims.
+
+---
+*Report generated as part of periodic repository audit.*

docs/devils-advocate/2026-05-14.md

@@ -0,0 +1,26 @@
+# Devil's Advocate Analysis: command-center
+**Date:** 2026-05-14
+
+## 1. Conflicts & Contradictions
+- **Language Policy**: `CLAUDE.md` enforces Korean responses ("모든 응답은 한국어로 작성"), yet the repository structure, code, CI/CD, and many core documentation files are in English. This creates a cognitive load and inconsistency for contributors.
+- **Node.js Versioning**: `.claude/config.json` specifies a minimum Node version of 20, whereas `site/package.json` requires Node 22+. This can lead to local development failures when using the workspace tools.
+- **README Paradox**: The root `README.md` is empty, yet the CI/CD workflow (`deploy-pages.yml`) specifically looks for markers in this file to update the live URL. Furthermore, `CLAUDE.md` refers to README sections that do not exist.
+- **Automation Permissions**: `.claude/config.json` explicitly denies `gh pr merge`, but the `deploy-pages.yml` workflow attempts to automate README updates via PRs, suggesting an intent for automated merging that is blocked at the workspace level.
+
+## 2. Ambiguities
+- **Blueprint vs. Instance**: The ontology is described as "code-anchored" (`ontology-design.md`), but it currently uses `example-*` placeholders and the `projects/` directory is empty. It is unclear if this is a template or a misconfigured live instance.
+- **Glossary Fragmentation**: Glossaries exist at the root level (`wiki/glossary.md`) and within each sub-domain (e.g., `wiki/commerce-catalog/glossary.md`). This risks terminology drift and conflicts across domains.
+- **Data Lifecycle**: The site relies on generated JSON in `site/public/data/`, which is gitignored. The build process for this data is not documented in the root README, and the UI fails silently if this data is missing.
+
+## 3. Implementation Issues
+- **Stale Configuration**: `.claude/config.json` references a `maker-pr` skill which does not exist in the `.claude/skills/` directory.
+- **Error Handling**: `useOntologyLoader()` in the React app swallows fetch errors, potentially leaving users with a blank screen and no diagnostic information when the generated JSON is missing.
+- **Directory Naming**: The `wiki` subdirectories use a mix of English slugs (`commerce-catalog/`) and Korean names (`상품-등록/`). This complicates terminal navigation and URL routing stability.
+
+## 4. Potential Edge Cases
+- **Missing Build Assets**: If a user clones the repo and runs `npm run dev` in the `site` folder without running the root-level data generation, the app will be broken.
+- **CI Auto-Update Failures**: The `deploy-pages.yml` will fail to update the `README.md` if the expected regex markers are not found, which is currently the case.
+- **Ontology Validation**: While `tbox.yaml` defines rules, there is no evidence of a pre-commit or CI check that validates the `abox` YAML files against these rules, allowing malformed ontology data to break the site.
+
+---
+*Generated by Devil's Advocate Analysis Trigger*