小規模事業者向け給与計算準備
支払日前にエラーや漏れをキャッチします。
このスキルは、事業主の給与ルール、POS、タイムクロック、予約システム、HRのエクスポートを、チェック済みの給与計算に変換します：レビューワークブック、証跡、給与システムへのアップロードファイルを作成します。実際の給与計算の提出は行いません。人間がレビューし、提出します。
すべてはこのスキルのフォルダ内の1つのコマンドラインツールで実行されます：
python3 scripts/payroll.py --help # Python 3.10+ と openpyxl が必要（pip install openpyxl）
別の場所で作業する場合は、スキルフォルダの絶対パスを指定して実行します。例：
python3 <skill-dir>/scripts/payroll.py run <period-folder>
基本ルール（最初に読んでください）
payroll.py runのみがALL CLEARを判断します。 Exit 0 かつoutput/evidence.jsonに"status": "ALL CLEAR"がある場合のみがALL CLEARです。自分の数字の読み取りから、実行がクリーン、完了、準備完了と説明しないでください。Exit 2 は NOT CLEAR、exit 1 は BLOCKED です。- レート、しきい値、ウィンドウ、給与種類名を発明しないでください。 事業主が教えていない場合は、空白のままにして実行を停止し、質問させてください。推測した数字は給与支払いになります。
- 事業主の署名済みルールが実行のルールです。 ルールの変更は
payroll_config.jsonに行い、その後Pay Rules Bookを再レンダリングし、再承認します。ワークブックやエクスポートファイルの数値を直接編集しないでください。入力またはルールを修正し、再度実行してください。 - 警告には判断が必要です。 すべての警告は、入力が修正されるか、
period.jsonに誰が決定し、なぜ決定したかの確認記録（acknowledged_warnings）が記録されるまで、ALL CLEARをブロックします。事業主に代わって確認しないでください。事業主に確認を依頼してください。 - 法的または税務上のアドバイスではありません。 州のプリセットは出発点です。事業主に、時間外労働、最低賃金、病欠、チップ、最終給与のルールについて、給与計算プロバイダーまたは雇用弁護士に確認するように伝えてください。
- 機密データを外部に出さないでください。 エンジンには名前、ID、レート、時間のみが必要です。社会保障番号、銀行口座詳細、生年月日を要求したり保存したりしないでください。エクスポートにそれらが含まれている場合、該当する列をどこにもコピーしないでください。
ワークスペース
<workspace>/
payroll_config.json 事業主のルール（ヒアリングから）
PAY_RULES_BOOK.md / .html ルールを平易な英語で、事業主の承認付き
connectors/ HRIS / 給与プロファイルのオプションの編集済みコピー
history/weeks.json 既に支払い済みの時間と残業時間（実行で書き込まれる）
periods/<start>_<end>/
period.json 日付、月次ウィンドウ、ウィンドウ、証明、ソース、確認
raw/ ダウンロードしたままのエクスポート
inputs/ エンジンが読み取る正規CSV
output/ レビューワークブック、アップロードファイル、実行サマリー、evidence.json
事業主が実際の動作を確認したい場合は、まず架空のサンプルを試してください：payroll.py sample ./demo（スパ）または payroll.py sample ./demo --kind retail（店舗チェーン）、次に approve ./demo --by "<name>"、hris-import、run を demo/periods/ 内の各期間に対して実行します（references/getting-started.md を参照）。事業主のビジネスに最も近いものを選んでください。
事業主の希望がモードを決定します
1. セットアップ（ヒアリング）
事業主に payroll_config.json がまだない場合、または給与の支払い方法を変更したい場合。
- 事業主がどの業種で、どのように給与を支払っているかを尋ねます（
references/questionnaire.mdのstart.1とstart.2）。このツールが対応していない業種固有の要件がある場合は、早い段階で伝えてください（同ファイルの「Not handled yet」列）。 - 残りの質問にどのように答えるかを尋ねます：あなたとのインタビュー、または業種に応じた入力可能なヒアリングワークブック（
payroll.py intake-workbook intake.xlsx --industry <id>、その後compile-intake intake.xlsx payroll_config.json）。 - インタビューの場合、
references/questionnaire.mdに従ってください：一度に1つの質問、給与支払い方法に一致するコアセクションと業種パックのみを対象とし、各セクションをルールとして読み上げてから書き込みます。 references/config-reference.mdに従って設定を書き込みます。payroll.py init <workspace>から開始します。assets/states/から州のプリセットをロードし、事業主に確認してもらいます（references/state-rules.md）。payroll.py validate <workspace>をVALIDと表示されるまで実行します。payroll.py rulebook <workspace>を実行し、すべてのルールIDを事業主と一緒に確認し、修正し、再レンダリングします。- 事業主が同意したら、
payroll.py approve <workspace> --by "<事業主名>"を実行します。
2. 給与期間の開始
payroll.py new-period <workspace> --start YYYY-MM-DD --end YYYY-MM-DD --pay-date YYYY-MM-DD
（月次インセンティブを支払う実行には --monthly を追加；ウィンドウはデフォルトで終了日の暦月になります。--month-start と --month-end で設定も可能です）。
期間は日付順に実行します：2つの期間にまたがる作業週は、前の期間の時間が必要です。最初の期間については、references/config-reference.md の「history」を参照してください。
期間が占める作業週、境界週の警告、systems.pos_reports からのエクスポートチェックリストが出力されます。そのチェックリストを事業主に渡してください。
3. エクスポートを入力に変換
- 人事名簿、給与レート、休暇：
payroll.py hris-import <period> --roster <file> --time-off <file>を、systems.hrisのプロファイルを使用して実行します（references/hris-connectors.md）。output/hris_import_report.mdを読みます。--map field=Headerまたは<workspace>/connectors/のプロファイルのコピーを編集してFAILを修正します。 - POSレポート：各レポートを正規CSVにマッピングします（
references/input-formats.md、references/pos-mapping.md）。ヘッダーテキストでマッピングし、列位置ではマッピングしないでください。すべてのレポートを、独自の印刷された合計とともにperiod.jsonのsourcesに記録し、実行で何も欠落したり重複したりしていないことを証明できるようにします。 - 入力に今期間本当に何もない場合（特定の拠点で誰も休暇を取らなかったなど）、空のファイルの代わりに
period.jsonに証明を記録します。
次に payroll.py check <period> を実行します：READY TO RUN か、修正すべき正確なFAILが表示されます。
4. 実行
payroll.py run <period> を実行します。ゲートを実行し、計算し、すべての入力合計を支払い額と照合し、すべてを独立して再計算（監査）し、前の期間と比較し、給与ファイルを書き込み、ALL CLEAR、NOT CLEAR、またはBLOCKED を出力します。
- BLOCKED： 何も計算されませんでした。FAIL行を修正し（通常は入力の問題）、再度実行します。
- NOT CLEAR： 理由を読みます。入力またはルールを修正します。事業主が受け入れる警告の場合は、その確認を
period.jsonに追加します。再度実行します。NOT CLEARの実行からのアップロードファイルはDO_NOT_UPLOAD_...という名前になります。各実行は、前の実行の出力を最初にクリアします。 - ALL CLEAR：
output/payroll_review_<date>.xlsx、run_summary.html、アップロードファイルを事業主に送ります。Findings と Incentive Notes で事業主が知っておくべきことを指摘します。事業主がレビューし、アップロードします。あなたはアップロードしません。
重要な実行（最初の本番期間、新しい拠点、ルール変更）の場合は、ハンドオフ前に別のエージェントに references/auditor.md を使用して出力をレビューさせることを検討してください。
5. ルールの変更
payroll_config.json を編集し、validate を実行し、ルールブックを再レンダリングし、事業主の承認を再度取得し（approve）、期間を再実行します。ルールブックのフィンガープリントはルール変更ごとに変わるため、古い承認は自動的に検出されます。
参照先
| 目的 | ファイル |
|---|---|
| 業種別のインタビュー質問、それぞれの重要性と既知のギャップ | references/questionnaire.md |
| すべての設定フィールド | references/config-reference.md |
| 正規CSV入力 | references/input-formats.md |
| POSレポートのマッピング（既知のレポートの落とし穴を含む） | references/pos-mapping.md |
| HRおよび給与システムへの接続 | references/hris-connectors.md |
| 州のプリセットと確認すべきこと | references/state-rules.md |
| 各ゲートとチェックの存在理由 | references/lessons.md |
| 独立レビュー用ブリーフ | references/auditor.md |
| スパと小売のサンプルを使った初回ウォークスルー | references/getting-started.md |