light-project-structure

プロジェクト構造のライフサイクル

可視のプロジェクトツリーと、その移行を裏付ける証拠を管理します。ディレクトリが整然としているからといって、再現可能な研究ができると誤解しないでください。

既存リポジトリを移行する前に、 references/project-lifecycle-resource-map.md を読んでください。ここでは、アーティファクト、ポリシー、アクセスレベル、出所情報、スキル間の所有範囲を定義しています。 小規模プロファイルの最小要件には references/structure-profiles.json を、明示的なプロジェクト／ファイルポリシーには templates/project-policy.template.json を使用してください。 引き渡し前に scripts/structure_governance_gate.py を実行し、プロファイルの選択、既存プロジェクトの読み取り専用の安全性、テンプレートの残存項目、シークレットスキャン、環境の診断、認可との紐付け、適用済みマニフェストとの紐付け、ロールバックの証拠を検証してください。

絶対に守るべき境界

1. インベントリ作成は読み取り専用のアクセスとして扱い、移動の認可とみなさないでください。
2. 上書き、削除、git rm --cached の実行、DVC の初期化、設定の書き換え、シンボリックリンクの自動移動は絶対に行わないでください。
3. --force を同意として扱わないでください。このライフサイクルに強制バイパスはありません。
4. .light/ の内容はすべて保持してください。passport、project card、decision log、version history、terminology、handoff files を作成または編集できるのは memory-pm だけです。
5. 不明な事実は UNKNOWN のままにしてください。data/raw のようなパスがあっても、サイズ、機密性、不変性、再計算可能性、Git ポリシーの根拠にはなりません。
6. このオーバーレイを DAG ノードにしないでください。light.findings.v1 は出力せず、STAGE_GATES、ROUTES、ステージ番号、逆方向エッジも追加しないでください。
7. 構造への準拠によって、データ品質、実験の再現性、統計的妥当性、論文の品質が証明されるわけではないことを明記してください。
8. テンプレートのプレースホルダーが未解決のまま、シークレットスキャンの検出項目が未処理のまま、または必須の Python／R／環境チェックが欠けた状態で、生成または移行したツリーを出荷してはいけません。

モードの選択

状況	モード
対象が空で、ユーザーが開始用のツリーを希望している	明示的なプロファイルを1つ指定して scaffold
既存リポジトリ、モノレポのパッケージ、または Git 管理外のディレクトリ	intake を実行し、判断の段階で停止
ユーザーが計画を確認したうえで、正確な移動を承認した	認可を作成してから apply
適用済みの移動を取り消す必要がある	適用済みマニフェストから rollback

空でないディレクトリに scaffold を実行しないでください。R、論文のみ、複数言語、カスタム、またはモノレポのプロジェクトに、固定の23ディレクトリツリーを後付けしないでください。

フェーズ 1 — 受付と要件

以下を収集するか、UNKNOWN として保持します。

• プロジェクトの種類、および選択されたルートが Git ルート、モノレポのサブルート、非 Git ディレクトリのいずれか；
• 成果物、計算環境、データ量、リモートストレージ、共同作業者、CI、ライセンス、保持期間；
• Git ルート、ブランチ、追跡対象／未追跡／無視状態、未コミットの変更、サブモジュール、シンボリックリンク、大容量ファイル、機密パスの兆候。

確認された技術シグネチャーとユーザーが宣言した成果物に基づき、最小のプロファイルを選択します。

• python-research
• r-research
• mixed-research
• paper-only
• existing-custom

プロファイルは拡張可能な最小要件であり、コンプライアンスの判定ではありません。 選択されたプロファイルは、プロジェクトについての根拠にはなりません。intake は確認されたファイル／設定のシグナルをポリシーで宣言された成果物の種類とは別に記録し、プロファイルを推奨します。また、別のプロファイルが具体的な profile_selection_reason なしで選択されている場合、ガバナンスゲートを失敗させます。

ポリシーテンプレートをソースルートの外部にコピーし、既知のプロジェクト情報を記入して、根拠がある場合にのみファイルルールを追加します。正当に追跡対象とする成果物には、小規模な公開用フィクスチャー、レビュー済みのゴールデンファイル、DVC ポインター、論文の最終図版、リリース成果物、またはプロジェクトポリシーで必要とされる監査証拠が含まれます。大容量または機密性のあるソースデータ、モデル、結果は通常、DVC／オブジェクトストレージで管理する必要がありますが、ディレクトリ名だけで判断せず、決定が必要です。

次を実行します。

python scripts/scaffold.py intake <root> --out <evidence-dir> \
  --profile mixed-research --policy <project-policy.json>

このコマンドは --out に証拠を書き込み、ソーススナップショットと Git の状態が変化していないことを検証します。

intake は、リソースマップに記載された技術シグネチャー、環境診断、テンプレート残存スキャン、シークレットスキャン、ガバナンスレポートも出力します。ツールのチェックは選択したプロファイルだけでなく、確認済みまたは明示的に宣言された成果物の種類に基づきます。プロジェクトで Python、R、Quarto、DVC、LaTeX、その他のローカルツールが必要な場合は、その要件をポリシーに記録します。追加の臨時チェックが必要な場合に限り、単独の診断コマンドを使用します。

python scripts/structure_governance_gate.py --doctor python r

フェーズ 2 — ドライランをレビューする

リソースマップに記載された受付時の成果物を読みます。以下を確認します。

• すべてのインベントリー行に、位置情報／ハッシュ／サイズ／Git の状態に加え、明示的または UNKNOWN の所有者、生成者、再計算可能性、機密性、分類、対象、ポリシー上の根拠がある；
• 技術シグネチャーが位置情報を示し、確認された証拠を policy.project.artifact_types と区別している；選択されたプロファイルが推奨と一致するか、具体的なユーザーによる上書き理由がある；
• 重複は証拠であり、自動削除の指示ではない；
• シンボリックリンク、既存の対象、複数の項目を単一の対象に移動する操作はブロックされている；
• ../、絶対パス、ドライブ文字、UNC、またはそれ以外のルート外へ逸脱する操作パスは、適用時まで先送りされず、ドライランの計画とガバナンスゲートでブロックされている；
• モノレポのサブルートでは、そのサブルートからの相対パスが使われ、Git ルート全体がプロジェクトとして扱われていない；
• .light/ が保持され、移動アクションがない；
• raw の下にあるというだけで、大容量の追跡対象フィクスチャーが不適切と判定されていない；
• 大容量の再計算可能な成果物、または機密性のある成果物に対して、ストレージポリシーの決定が必要であることが示されている。
• 該当する場合、テンプレートの出所情報、残存プレースホルダースキャン、シークレットスキャン、環境診断が含まれている；.env の無視設定はシークレットスキャンの結果ではない。

以下を提示します。

1. 推奨プロファイルとその理由；
2. 安全なアクション ID；
3. ブロックされた競合と不明点；
4. 移動／名前変更、上書き（非対応）、削除、git rm --cached、設定の書き換え、DVC の初期化について、それぞれ個別の判断；
5. 計画の SHA-256。

その後、停止します。ユーザーに、どのアクション ID を許可するか尋ねます。ユーザーの回答を先に書き込んではいけません。

構成を準備完了として提示する前に、納品バンドルでガバナンスゲートを実行します。

python scripts/structure_governance_gate.py \
  --input templates/project-structure-governance.example.json

同梱の例は意図的にフェイルクローズです。既存の R プロジェクトで scaffold を試み、テンプレートのプレースホルダーを残し、シークレットの値を報告し、R を見落とし、force を使用し、.light/ を移動し、アクション ID を重複させ、削除を適用し、シンボリックリンクを移動し、上書きのリスクを生じさせます。

フェーズ 3 — 認可のバインド

ユーザーが選択した後、認可ドキュメントを作成します:

{
  "schema": "light.project-structure.v2.authorization",
  "authorization_id": "<user-created stable authorization id>",
  "plan_sha256": "<exact migration-plan plan_sha256>",
  "approved_action_ids": ["move-0001"],
  "authorized_by": "<user-supplied identifier>",
  "authorized_at": "<YYYY-MM-DD>"
}

ブロックされたアクションや不明なアクションを含めないでください。authorization_id と authorized_by は、テンプレートのテキストではなく、ユーザーが指定した具体的な値でなければなりません。 authorized_at は未来の日時にできません。変更された計画には新たな 認可が必要です。認可によって上書きを解決したり、シンボリックリンクのブロックを 回避したりすることはできません。

フェーズ 4 — 適用、検証、ロールバック、再適用

python scripts/scaffold.py apply \
  --plan <migration-plan.json> \
  --authorization <authorization.json> \
  --manifest-out <applied-manifest.json> \
  --as-of <YYYY-MM-DD>

python scripts/scaffold.py rollback \
  --manifest <applied-manifest.json> \
  --rollback-out <rollback-manifest.json>

apply はソースハッシュと絶対的な包含関係を再検証し、存在しない ターゲットの親を作成し、既存のターゲットを拒否し、通常のファイルのみを移動し、移動前後の SHA-256 を記録し、 正確な計画ファイルと認可ファイルをロケーターおよびファイル SHA-256 でバインドする適用済みマニフェストを書き込みます。 選択されたルートから逸脱したパスは、計画段階ですでにブロック済みとしてマークされているはずです。 それでも適用に到達した場合、適用はフェイルクローズドで失敗します。rollback はターゲット ハッシュを検証し、再出現したソースの上書きを拒否します。 安全な復元のために適用済みマニフェストを使用し、元の計画ファイル/認可ファイルが まだ存在している必要はありません。

ロールバック後:

1. ソーススナップショットと Git ステータスを intake 時と比較します。
2. 未追跡のドラフトと .light/ の内容がバイト単位で同一のままであることを検証します。
3. 認可が依然として意図されたものである場合にのみ再適用します。
4. 未解決の競合と、手動での Git/DVC の判断を分けて報告します。

グリーンフィールドスキャフォールド

空のターゲットでのみ使用してください:

python scripts/scaffold.py scaffold <target> --profile r-research --name <name>

このコマンドはプロファイルとジェネレータのハッシュを .project-structure-provenance.json に記録します。これは一度限りの生成であり、安全な テンプレート更新ではありません。管理されたテンプレートの進化については、Copier や Cruft を評価し、 ローカルの変更と競合をレビューしてください。ドリフト検出がマージの保証であると主張しないでください。

オーナーシップの引き継ぎ

• .light/ メモリが必要な場合は、memory-pm に pm.py init の実行を依頼してください。ここで その作業を行わないでください。
• データ品質、リネージ、リリース設計は data-engineering に引き継いでください。
• 実行マニフェストと実行可能な再現性は experiment-coding に引き継いでください。
• 提供されたリポジトリ/資料の理解は file-reading に任せてください。移動を所有するのは このスキルだけです。
• 有用であれば orchestrator にデリバリーを消費させてください。ゲートを作成しないでください。

検証

スクリプトのセルフテストを実行します:

python scripts/scaffold.py --selftest
python scripts/structure_governance_gate.py --selftest

これは、ソース読み取り専用の intake、追跡対象フィクスチャポリシー、生成された 環境/テンプレート/シークレット/ガバナンスレポート、未追跡ドラフト、.light/ の保持、認可のバインド、適用済みマニフェストの計画/認可ファイルのバインド、 実際の移動/ハッシュの証拠、ロールバック、再適用、非 Git モード、モノレポのサブルート 処理、プロファイルスキャフォールドの冪等性、およびベストエフォートの Windows シンボリックリンク 分岐を検証します。

デリバリーの前に、次を確認してください:

• intake 中にソースの変更が発生していない。
• ユーザーが適用前に競合、不明点、アクション ID、計画ダイジェストを確認した。
• 適用された移動が認可された ID と正確に一致し、移動前後のハッシュがある。
• 適用済みマニフェストが、正確なマイグレーション計画ファイルと認可 ファイルをロケーターおよびファイル SHA-256 でバインドしている。
• ターゲットが上書きされておらず、シンボリックリンクが移動されていない。
• 計画済み/適用済みのソースまたはターゲットパスが、選択されたプロジェクトルートから逸脱していない。
• 未追跡の作業と .light/ の内容が移動とロールバックを経ても存続している。
• フィクスチャ/ゴールデンファイル/DVC ポインターが、パスではなくポリシーによって分類された。
• テンプレート残留スキャン、シークレットスキャン、環境ドクター、プロファイル 理由が存在する。観測された/宣言されたシグネチャがプロファイルを裏付けており、 R/Python の要件は主張される場合にチェックされている。
• structure_governance_gate.py が実際のデリバリーバンドルで合格する。
• テンプレートのソース/バージョン/ハッシュ/パラメータと更新の制限が記録されている。
• デリバリーが、構造によって再現性が証明されるとは主張していない。