context-probe 0.1.0

package/LICENSE

@@ -0,0 +1,183 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright
+owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities
+that control, are controlled by, or are under common control with that entity.
+For the purposes of this definition, "control" means (i) the power, direct or
+indirect, to cause the direction or management of such entity, whether by
+contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including
+but not limited to software source code, documentation source, and configuration
+files.
+
+"Object" form shall mean any form resulting from mechanical transformation or
+translation of a Source form, including but not limited to compiled object code,
+generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made
+available under the License, as indicated by a copyright notice that is included
+in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that
+is based on (or derived from) the Work and for which the editorial revisions,
+annotations, elaborations, or other modifications represent, as a whole, an
+original work of authorship. For the purposes of this License, Derivative Works
+shall not include works that remain separable from, or merely link (or bind by
+name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version
+of the Work and any modifications or additions to that Work or Derivative Works
+thereof, that is intentionally submitted to Licensor for inclusion in the Work
+by the copyright owner or by an individual or Legal Entity authorized to submit
+on behalf of the copyright owner. For the purposes of this definition,
+"submitted" means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems, and
+issue tracking systems that are managed by, or on behalf of, the Licensor for
+the purpose of discussing and improving the Work, but excluding communication
+that is conspicuously marked or otherwise designated in writing by the copyright
+owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf
+of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable copyright license to
+reproduce, prepare Derivative Works of, publicly display, publicly perform,
+sublicense, and distribute the Work and such Derivative Works in Source or
+Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License,
+each Contributor hereby grants to You a perpetual, worldwide, non-exclusive,
+no-charge, royalty-free, irrevocable (except as stated in this section) patent
+license to make, have made, use, offer to sell, sell, import, and otherwise
+transfer the Work, where such license applies only to those patent claims
+licensable by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s) with the Work
+to which such Contribution(s) was submitted. If You institute patent litigation
+against any entity (including a cross-claim or counterclaim in a lawsuit)
+alleging that the Work or a Contribution incorporated within the Work
+constitutes direct or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate as of the date
+such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or
+Derivative Works thereof in any medium, with or without modifications, and in
+Source or Object form, provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a copy of
+this License; and
+
+(b) You must cause any modified files to carry prominent notices stating that You
+changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works that You
+distribute, all copyright, patent, trademark, and attribution notices from the
+Source form of the Work, excluding those notices that do not pertain to any part
+of the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its distribution, then
+any Derivative Works that You distribute must include a readable copy of the
+attribution notices contained within such NOTICE file, excluding those notices
+that do not pertain to any part of the Derivative Works, in at least one of the
+following places: within a NOTICE text file distributed as part of the
+Derivative Works; within the Source form or documentation, if provided along with
+the Derivative Works; or, within a display generated by the Derivative Works, if
+and wherever such third-party notices normally appear. The contents of the
+NOTICE file are for informational purposes only and do not modify the License.
+You may add Your own attribution notices within Derivative Works that You
+distribute, alongside or as an addendum to the NOTICE text from the Work,
+provided that such additional attribution notices cannot be construed as
+modifying the License.
+
+You may add Your own copyright statement to Your modifications and may provide
+additional or different license terms and conditions for use, reproduction, or
+distribution of Your modifications, or for any such Derivative Works as a whole,
+provided Your use, reproduction, and distribution of the Work otherwise complies
+with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any
+Contribution intentionally submitted for inclusion in the Work by You to the
+Licensor shall be under the terms and conditions of this License, without any
+additional terms or conditions. Notwithstanding the above, nothing herein shall
+supersede or modify the terms of any separate license agreement you may have
+executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names,
+trademarks, service marks, or product names of the Licensor, except as required
+for reasonable and customary use in describing the origin of the Work and
+reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
+writing, Licensor provides the Work (and each Contributor provides its
+Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied, including, without limitation, any warranties
+or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any risks
+associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in
+contract, tort (including negligence), or otherwise, unless required by
+applicable law (such as deliberate and grossly negligent acts) or agreed to in
+writing, shall any Contributor be liable to You for damages, including any
+direct, indirect, special, incidental, or consequential damages of any character
+arising as a result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill, work stoppage,
+computer failure or malfunction, or any and all other commercial damages or
+losses), even if such Contributor has been advised of the possibility of such
+damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or
+Derivative Works thereof, You may choose to offer, and charge a fee for,
+acceptance of support, warranty, indemnity, or other liability obligations
+and/or rights consistent with this License. However, in accepting such
+obligations, You may act only on Your own behalf and on Your sole responsibility,
+not on behalf of any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability incurred by, or
+claims asserted against, such Contributor by reason of your accepting any such
+warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following boilerplate
+notice, with the fields enclosed by brackets "[]" replaced with your own
+identifying information. (Don't include the brackets!) The text should be
+enclosed in the appropriate comment syntax for the file format. We also
+recommend that a file or class name and description of purpose be included on
+the same "printed page" as the copyright notice for easier identification within
+third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.ja.md

@@ -0,0 +1,323 @@
+# AI支援設計計測プラットフォーム
+
+English version: [README.md](README.md)
+
+AIと決定的な解析器を組み合わせて、設計品質を証拠ベースで計測するための docs-first リポジトリです。現時点ではドメイン設計評価とアーキテクチャ設計評価を中心に実装しており、将来的な評価パック拡張も同じ計測モデルの上に載せられるよう文書を整理しています。
+
+日本語文書を正本とし、英語文書は同じ構成と文書責務を保つ追従版として管理します。
+
+## 読み始め
+
+1. [docs/README.ja.md](docs/README.ja.md)
+2. [docs/guides/user-guide.ja.md](docs/guides/user-guide.ja.md)
+3. [docs/guides/repo-apply-playbook.ja.md](docs/guides/repo-apply-playbook.ja.md)
+4. [docs/concepts/measurement-model.ja.md](docs/concepts/measurement-model.ja.md)
+5. [docs/reference/domain-design-metrics.ja.md](docs/reference/domain-design-metrics.ja.md)
+6. [docs/reference/architecture-design-metrics.ja.md](docs/reference/architecture-design-metrics.ja.md)
+7. [docs/implementation/runtime-and-commands.ja.md](docs/implementation/runtime-and-commands.ja.md)
+
+## 文書構成
+
+- [docs/README.ja.md](docs/README.ja.md): 文書全体の索引
+- [docs/guides/user-guide.ja.md](docs/guides/user-guide.ja.md): 初回利用者向けの最短ガイド
+- [docs/guides/repo-apply-playbook.ja.md](docs/guides/repo-apply-playbook.ja.md): 既存 repo へ適用するための実践ガイド
+- [docs/concepts/](docs/concepts): 概念仕様と計測モデル
+- [docs/reference/](docs/reference): 指標と summary score の読み方
+- [docs/implementation/](docs/implementation): current implementation の計算経路と出力契約
+- [docs/operations/](docs/operations): policy、CI、collector 運用
+- [docs/roadmap/](docs/roadmap): 段階的導入計画と実験メモ
+
+## 最初に覚えるコマンド
+
+- `score.compute`
+- `report.generate`
+- `gate.evaluate`
+- `review.list_unknowns`
+
+## 中核原則
+
+- AIは採点者ではなく、証拠抽出器と曖昧性整理器として使う
+- スコアは固定式と決定的解析で算出する
+- すべての指標に `evidence` `confidence` `unknowns` `provenance` を付ける
+- 組織横断の絶対評価より、候補比較と時系列比較を重視する
+- 評価領域ごとの差分は、共通基盤の上に載る拡張パックとして扱う
+
+## 実装状況
+
+- CLI中心の TypeScript / Node 実装を追加済み
+- Phase 1 相当として、依存解析、境界漏れ検出、進化局所性、スコア計算、レポート、ゲート判定を実装済み
+- Phase 2 の入口として、`doc.extract_*` の external CLI extractor、`trace.*` の証拠付きリンク生成、`review.resolve` の review log 化を追加済み
+- 将来拡張向けに `domain_design` と `architecture_design` の pack 境界を追加済み
+
+## クイックスタート
+
+目的ごとの最短入口は次です。
+
+- CLI を初めて触る: [docs/guides/user-guide.ja.md](docs/guides/user-guide.ja.md)
+- 既存 repo に `context-probe` を適用する: [docs/guides/repo-apply-playbook.ja.md](docs/guides/repo-apply-playbook.ja.md)
+- この repo の self-measurement を運用する: [docs/operations/self-measurement-runbook.ja.md](docs/operations/self-measurement-runbook.ja.md)
+
+```bash
+npm install
+npm run dev -- --help
+```
+
+公開済みパッケージの入口をそのまま試す場合は次を使います。
+
+```bash
+npx context-probe --help
+```
+
+ビルド済み CLI も確認したい場合は次を使います。
+
+```bash
+npm run build
+node dist/src/cli.js --help
+```
+
+### 先に入力 YAML を scaffold する
+
+まだ `--model` や `--constraints` を持っていない場合は、先に scaffold を作り、`result.yaml` をレビューします。
+
+```bash
+npm run dev -- model.scaffold \
+  --repo . \
+  --docs-root docs
+```
+
+```bash
+npm run dev -- constraints.scaffold \
+  --repo .
+```
+
+`constraints.scaffold` は `result.drafts` に architecture 入力のレビュー用スタータードラフトも返します。内容は `scenarioCatalog` `topologyModel` `boundaryMap` で、docs-first な repo では初回スコアリング前の叩き台として使えます。
+
+scaffold の出力はすべて authoritative input ではなく、review-first draft として扱います。新しい repo へ適用するときの安定した最短ルートは次です。
+
+1. `model` と `constraints` を scaffold する
+2. 残す YAML だけを curated 化する
+3. starter の `score.compute` を回す
+4. proxy が重い指標に observation snapshot を足す
+5. assessment を記録する
+
+この流れ全体は [docs/guides/repo-apply-playbook.ja.md](docs/guides/repo-apply-playbook.ja.md) にまとめています。
+
+### ドメイン設計スコアの計測例
+
+```bash
+npm run dev -- score.compute \
+  --repo . \
+  --model config/self-measurement/domain-model.yaml \
+  --policy fixtures/policies/default.yaml \
+  --domain domain_design
+```
+
+文書起点の metric も含めたい場合は `--docs-root docs` を追加します。
+
+### Markdown レポートの生成例
+
+```bash
+npm run dev -- report.generate \
+  --repo . \
+  --model config/self-measurement/domain-model.yaml \
+  --policy fixtures/policies/default.yaml \
+  --domain domain_design \
+  --format md
+```
+
+### アーキテクチャ設計スコアの計測例
+
+```bash
+npm run dev -- score.compute \
+  --repo . \
+  --constraints config/self-measurement/architecture-constraints.yaml \
+  --policy fixtures/policies/default.yaml \
+  --domain architecture_design
+```
+
+アーキテクチャ設計では `--model` ではなく `--constraints` が必須です。
+
+自己計測で `QSF` `TIS` `OAS` `EES` の proxy を減らしたい場合は、`config/self-measurement/` の補助入力も一緒に渡します。
+
+大きい repo では `domain_design` は authoritative run として扱い、full input のまま最後まで待ちます。速く見せるために縮めた profile へ切り替えず、完了後の `status` `result` `unknowns` `diagnostics` `provenance` を読んで判断してください。
+
+CLI を TTY で実行するか `CONTEXT_PROBE_PROGRESS=1` を設定すると、実行中の stage progress が stderr に出ます。これは補助情報で、最終的な JSON response が正本です。
+
+architecture の自己計測前には、measured / derived snapshot を先に更新します。
+
+```bash
+npm run self:architecture:refresh
+```
+
+意図的に固定する `IPS` contract baseline は別コマンドで capture します。
+
+```bash
+npm run self:architecture:baseline
+```
+
+snapshot の鮮度だけを advisory に確認したい場合は次を使います。
+
+```bash
+npm run self:architecture:audit
+```
+
+advisory audit と score smoke をまとめて確認したい場合は次を使います。
+
+```bash
+npm run self:architecture:check
+```
+
+release 前の validation と packaging は [docs/operations/release-preflight.ja.md](docs/operations/release-preflight.ja.md) を参照してください。
+
+```bash
+npm run dev -- score.compute \
+  --domain architecture_design \
+  --repo . \
+  --constraints config/self-measurement/architecture-constraints.yaml \
+  --complexity-export config/self-measurement/architecture-complexity-export.yaml \
+  --boundary-map config/self-measurement/architecture-boundary-map.yaml \
+  --contract-baseline config/self-measurement/architecture-contract-baseline.yaml \
+  --scenario-catalog config/self-measurement/architecture-scenarios.yaml \
+  --scenario-observations config/self-measurement/architecture-scenario-observations.yaml \
+  --topology-model config/self-measurement/architecture-topology.yaml \
+  --runtime-observations config/self-measurement/architecture-runtime-observations.yaml \
+  --telemetry-observations config/self-measurement/architecture-telemetry-observations.yaml \
+  --pattern-runtime-observations config/self-measurement/architecture-pattern-runtime-observations.yaml \
+  --delivery-observations config/self-measurement/architecture-delivery-observations.yaml \
+  --policy fixtures/policies/default.yaml
+```
+
+これらは live collector ではなく reviewable snapshot です。`scenario-observations` はローカル benchmark から作り、`telemetry` `pattern runtime` `delivery` と raw な `architecture-complexity-snapshot.yaml` は curated observation として管理します。`complexity-export` はその complexity snapshot から作る derived artifact です。`npm run self:architecture:refresh` は measured な `scenario-observations` と derived な `boundary-map` を更新し、`npm run self:architecture:complexity` は curated な complexity snapshot から `architecture-complexity-export.yaml` を再生成します。`npm run self:architecture:baseline` は current contract surface を reviewable な `IPS` baseline として capture するための別導線で、baseline delta を保つため `refresh` には含めません。`npm run self:architecture:audit` は CI に載せやすい advisory check で、`npm run self:architecture:check` はその audit と score smoke をまとめて行う運用チェックです。
+
+日常運用では次の順を基本にします。
+
+```bash
+npm run self:architecture:refresh
+npm run self:architecture:complexity
+npm run self:architecture:baseline   # IPS の比較基準を意図的に更新したいときだけ
+npm run self:architecture:check
+```
+
+coverage も品質ゲートに含めます。
+
+```bash
+npm run test:coverage
+```
+
+運用順序の要約は [docs/operations/self-measurement-runbook.ja.md](docs/operations/self-measurement-runbook.ja.md) にまとめています。
+
+このリポジトリ固有の注意として、small CLI codebase なので `ALR` `FCC` `SICR` `SLA` は evidence-limited のまま残りやすく、`PCS` も proxy composite のままです。これらは直ちに不具合を示すというより、自己計測の limitation として読みます。
+
+### source config を使った brownfield evidence の取り込み例
+
+```bash
+npm run dev -- score.compute \
+  --domain architecture_design \
+  --repo fixtures/validation/scoring/qsf/repo \
+  --constraints fixtures/validation/scoring/qsf/constraints.yaml \
+  --policy fixtures/policies/default.yaml \
+  --contract-baseline-source fixtures/examples/architecture-sources/contract-baseline-source.file.yaml \
+  --scenario-catalog fixtures/validation/scoring/qsf/scenarios.yaml \
+  --scenario-observation-source fixtures/examples/architecture-sources/scenario-observation-source.command.yaml \
+  --telemetry-source fixtures/examples/architecture-sources/telemetry-source.command.yaml \
+  --telemetry-normalization-profile fixtures/validation/scoring/oas/raw-normalization-profile.yaml \
+  --complexity-source fixtures/examples/architecture-sources/complexity-source.command.yaml \
+  --profile layered
+```
+
+collector と source config の詳細は [docs/operations/architecture-source-collectors.ja.md](docs/operations/architecture-source-collectors.ja.md) にまとめています。
+
+### 人間レビューが必要な unknowns を一覧する例
+
+```bash
+npm run dev -- review.list_unknowns \
+  --repo . \
+  --model config/self-measurement/domain-model.yaml \
+  --policy fixtures/policies/default.yaml \
+  --domain domain_design
+```
+
+### 高度な例: Codex CLI を使った用語抽出
+
+```bash
+npm run dev -- doc.extract_glossary \
+  --docs-root docs \
+  --extractor cli \
+  --provider codex
+```
+
+### 高度な例: Review log を適用した再抽出
+
+```bash
+npm run dev -- doc.extract_glossary \
+  --docs-root docs \
+  --extractor cli \
+  --provider claude \
+  --review-log path/to/review-log.json \
+  --apply-review-log
+```
+
+## このプロジェクト自身を計測する
+
+自己計測用の最小定義は [config/self-measurement/domain-model.yaml](config/self-measurement/domain-model.yaml)、[config/self-measurement/architecture-constraints.yaml](config/self-measurement/architecture-constraints.yaml)、[config/self-measurement/architecture-complexity-snapshot.yaml](config/self-measurement/architecture-complexity-snapshot.yaml)、[config/self-measurement/architecture-complexity-export.yaml](config/self-measurement/architecture-complexity-export.yaml) に置いています。
+
+### 1. Git 履歴を有効化する
+
+`ELS` は Git 履歴を参照するため、未初期化の環境では warning と低 confidence になります。ローカルでまだ Git を初期化していない場合は次を実行します。
+
+```bash
+git init
+git add .
+git -c user.name="Context Probe" -c user.email="context-probe@example.com" commit -m "chore: initialize context-probe"
+```
+
+### 2. ドメイン設計スコアを出す
+
+```bash
+npm run dev -- score.compute \
+  --domain domain_design \
+  --repo . \
+  --model config/self-measurement/domain-model.yaml \
+  --policy fixtures/policies/default.yaml
+```
+
+### 3. アーキテクチャ設計スコアを出す
+
+```bash
+npm run dev -- score.compute \
+  --domain architecture_design \
+  --repo . \
+  --constraints config/self-measurement/architecture-constraints.yaml \
+  --complexity-export config/self-measurement/architecture-complexity-export.yaml \
+  --boundary-map config/self-measurement/architecture-boundary-map.yaml \
+  --scenario-catalog config/self-measurement/architecture-scenarios.yaml \
+  --scenario-observations config/self-measurement/architecture-scenario-observations.yaml \
+  --topology-model config/self-measurement/architecture-topology.yaml \
+  --runtime-observations config/self-measurement/architecture-runtime-observations.yaml \
+  --telemetry-observations config/self-measurement/architecture-telemetry-observations.yaml \
+  --pattern-runtime-observations config/self-measurement/architecture-pattern-runtime-observations.yaml \
+  --delivery-observations config/self-measurement/architecture-delivery-observations.yaml \
+  --policy fixtures/policies/default.yaml
+```
+
+補助入力を省略すると architecture 側は neutral / proxy fallback が増えるため、自己計測では上のフルセットを基準にしてください。
+
+### 4. Markdown レポートを生成する
+
+```bash
+npm run dev -- report.generate \
+  --domain domain_design \
+  --repo . \
+  --model config/self-measurement/domain-model.yaml \
+  --policy fixtures/policies/default.yaml \
+  --format md
+```
+
+## 検証
+
+```bash
+npm run check
+npm test
+```
+
+`npm test` には `fixtures/validation/extraction/` の curated golden corpus を使った抽出品質検証も含まれます。ここでは `doc.extract_*` `trace.link_terms` `review.list_unknowns` を既存CLIのまま叩き、`must_include` `must_exclude` `must_link_to_code` `max_review_items` で回帰を検知します。