jasveerai88/gst-hst-tracker

gst-hst-tracker — エージェントスキル

目的

カナダのフリーランサーや個人事業主は、スプレッドシートでGST/HSTを追跡し、CRAの$30,000小規模供給者基準を超えた後に気づくことがよくあります。このツールは、日付付き取引台帳を読み取り、以下の情報を生成します。(a) 四半期ごとのGST/HST徴収額、ITC、純税額（T2125形式の収入/経費準備セクション付き）、(b) 閾値テスト: 直近4暦四半期の課税売上と$30,000の制限を比較し、余裕額または超過アラーム、(c) 同じ台帳の州別ビュー: 税制度、徴収額、ITC、州別の純額（州の構成要素はデータがサポートする範囲でのみ表示: QSTは記録された内訳金額と未記録のQC売上の推定値、PST/RSTは税率×売上の暴露推定値）。 純Python標準ライブラリのみを使用; ローカルでのみ動作; 1つの台帳ファイルを読み取り、何も書き込みません。

このツールの誠実さの中核: これは追跡および計算の補助ツールであり、税務アドバイスやCRAへの申告ではありません。すべてのレポートにはその免責事項が記載されており、その出力から作成するものすべてにも同様の免責事項を付ける必要があります。罰金や利息を計算することはありません。

使用すべき場合 / 使用すべきでない場合

使用すべき場合:

• 取引台帳から四半期のGST/HST数値を準備する: 徴収額、ITC、純債務額。
• フリーランサーが$30,000の登録基準にどの程度近いか、または超えたかどうかを確認する。
• 収入と経費のカテゴリをT2125形式の準備ビューに整理して申告シーズンに備える。
• エージェントが信頼できるJSON形式のカナダGST/HST数値を必要とする場合。

使用すべきでない場合:

• ユーザーが税務アドバイス、申告、または義務に関する判断を必要とする場合 — このツールはそれを提供できません。CRAや資格のある会計士を紹介してください。
• 質問が罰金や利息に関する場合 — 計算されません。
• 帳簿がケベック州QST帳簿の場合: QSTはここでは内訳のみです（制限事項を参照）。BC PST / SK PST / MB RSTは州別ビューで暴露推定値としてのみ表示されます — 決して税債務やクレジットとして表示されません。
• 台帳が古い場合: 閾値ウィンドウは最新の取引に固定されるため、古い台帳は古いウィンドウを提供します。日付が古いように見える場合はその旨を伝えてください。

インストール

pipx install git+https://github.com/jasveerai88/gst-hst-tracker
# または: pip install git+https://github.com/jasveerai88/gst-hst-tracker

（PyPIにはありません — git+形式がインストール方法です。）ソースチェックアウトからは、python3 src/gst_hst_tracker.py ... で同等です。

コマンド

# 四半期レポート（JSONまたはCSV入力; 成功時はexit 0）
gst-hst-tracker report LEDGER.json
gst-hst-tracker report LEDGER.csv --json

# 特定の暦四半期または1年間のみ
gst-hst-tracker report LEDGER.json --period 2026-Q1
gst-hst-tracker report LEDGER.json --period 2026

# 小規模供給者アラーム（超過時はexit 1、それ以外は0）
gst-hst-tracker threshold LEDGER.json [--limit 30000]

# 州別ビュー（成功時はexit 0）
gst-hst-tracker provinces LEDGER.json
gst-hst-tracker provinces LEDGER.json --period 2026-Q1 --json

# INR相当額も表示（1 CADあたりのレート）
gst-hst-tracker report LEDGER.json --cad-to-inr 67.97

# 州の税率が変更された場合に上書き
gst-hst-tracker report LEDGER.json --rate NS=15

入力行（JSONリスト、{"transactions": [...]} オブジェクト、または同じヘッダーを持つCSV）: date（YYYY-MM-DD、必須）、kind（income|expense、必須）、description（必須）、amount（税引前CAD、必須、≥ 0）、province（2文字コード、必須）; オプション: tax（請求/支払い済みのGST/HST — 省略すると州の税率から計算; 0はゼロ評価として尊重されます）、qst（QC行のみ; 個別に追跡され、純額には含まれません）、category（経費のみ; T2125形式のグループ化）。

モデル（結果を報告する際に明示してください）

• 暦四半期ごとの純税額 = 収入に対するGST/HST徴収額 − ITC（経費に支払ったGST/HST）。負の純額 = ITCが徴収額を上回る: 還付ポジションであり、手持ち現金ではありません。
• 閾値: 最新取引の四半期で終了する直近4暦四半期における課税供給（収入行のみ）。CRAのテストは 超過 $30,000 — ちょうど$30,000はまだ小規模供給者です（status: "at"、exit 0）。
• 2026年11月時点のデフォルト税率: GST 5%（AB BC MB NT NU SK YT）、HST 13% ON、HST 15% NB/NL/PE、HST 14% NS（2025年4月1日に15%から引き下げ）、QC = GST 5%連邦部分のみ。
• QST（9.975%）は別個のRevenu Québec税です: 提供されたqst金額は内訳合計としてのみ表示され、純額には決して含まれません。
• 州別ビュー（provinces）: 行の州でグループ化された同じ連邦数学。エンコードされた州税（「エンコード済み税率、2026年11月確認 — CRA/州の情報源で確認してください」というスタンプ付き）: QST 9.975%（QC）、PST 7%（BC）、PST 6%（SK）、RST 7%（MB）; HST州には別個の州構成要素はありません。QCは記録されたQST合計と、記録されたqstがないQC収入行の推定値を表示; BC/SK/MBは税率×売上の暴露推定値のみを表示し、州ITCはありません（投入物に対するPST/RSTは一般的にコストです）。四捨五入: 州別の数値はセント単位で四捨五入され、要約はそれらの四捨五入された数値を合計するため、常に州ブロックと一致します。

出力JSONスキーマ（--json）

report: tool（"gst-hst-tracker"）、version、command（"report"）、file、currency（"CAD"）、rates（州ごとのrate_pct + ラベル、as_of: "2026-11" のスタンプ付き、QST注記あり）、cad_to_inr（レートまたはnull）、period_filter（文字列またはnull）、periods、totals、disclaimer。

各period: period（例: "2026-Q1"）、quarter（[2026, 1]）、income_total、expense_total、gst_hst_collected、itcs、net_tax_owing、qst_collected、qst_paid、transactions、t2125（gross_business_income、expenses_by_category、total_expenses）。totalsは表示された期間にわたって同じフィールドを合計します。--cad-to-inr を使用すると、金額フィールドに *_inr の兄弟フィールドが追加されます。

threshold: 共通フィールドに加えて、latest_transaction、window_end_quarter、quarters（4つの{quarter, income}エントリ、古いものから順）、rolling_total、limit、headroom（超過時は0）、over_by（超過していない時は0）、crossed（bool）、status（"under" | "at" | "crossed"）、rule、disclaimer。

provinces: 共通フィールドに加えて、provincial_rates（stamp、qst_rate_pct、taxes — 州ごとのfederalラベルとprovincial_tax {name, rate_pct} またはnull）、rounding_rule、provinces、totals、disclaimer。provinces内の各エントリ: province、tax_system（実効税率から構築、例: "GST 5% + PST 7%"）、income_total、expense_total、gst_hst_collected、itcs、net_tax_owing、transactions、およびprovincial — GSTのみおよびHST州ではnull; それ以外は {name, rate_pct, recorded_collected, recorded_paid, recorded_net}（QCは数値、BC/SK/MBはnull — それらについては何も記録されていません）、estimate_base、estimated_on_sales、note。totalsは qst_recorded_collected / qst_recorded_paid / qst_recorded_net および provincial_estimated_on_sales を追加します。

エラー時、stdoutは単一のオブジェクト: {"error": "<message>"}（検証エラーは行を指定: "row 2: ..."）、終了コード2 — --json モードではargparseの使用法エラーも含みます。プレーンテキストやトレースバックは決して出力しません。

終了コード

• report: 0 — レポート計算完了。2 — エラー。
• provinces: 0 — ビュー計算完了。2 — エラー。（exit 1の状態はありません: ビューは情報提供用であり、アラームはthresholdにあります。）
• threshold: 0 — ローリング合計が制限未満またはちょうど制限: これらの数値ではまだ小規模供給者。1 — 閾値超過: ローリング合計が制限を超えており、GST/HST登録が必要です。これは失敗ではなく発見事項です: 目立つように表示してください。2 — エラー: 数値が生成されませんでした; 何も引用しないでください。
• いずれかのコマンドでエラーが発生すると、クリーンなメッセージ（または--json モードでは {"error": ...} オブジェクト）とともに exit 2 で終了します。

エージェントが尊重しなければならない制限事項と誠実さのルール

• 税務アドバイスではなく、申告書でもありません。 このツールの出力をアドバイスや提出済み申告書として提示しないでください。すべての出力に含まれる免責事項は重要です: 作成する要約に必ず添付してください。
• 税率は2026年11月時点のデフォルトであり、ライブの事実ではありません。 「ツールの2026年11月デフォルト」として引用し、上書き可能であることを注記してください。ノバスコシア州は14%です（2025年3月31日までは15%でした） — ユーザーの数値がNSで15%で計算されていた場合、黙って受け入れるのではなく、フラグを立てる価値があります。
• ちょうど$30,000は超過ではありません。 CRAのテストは「$30,000を超える」です。status が "at" の場合、「まだ小規模供給者、余裕額ゼロ」と報告してください — 「登録必須」とは決して報告しないでください。
• threshold からのexit 1はツールが正常に機能していることです。 アラームが作動したことを意味します。ローリング合計、超過額、および登録が必要であることを迅速に、埋もれさせずに報告してください。
• QSTは純額に決して含まれません。 ケベック州の行を要約する場合、QSTを別個の内訳数値として保持してください。徴収したQSTを net_tax_owing に追加したり、支払ったQSTをITCとして扱ったりしないでください。
• 州の推定値は推定値です。 provinces ビューのPST/RST数値および未記録のケベック州売上のQST数値は、エンコードされたテーブルからの税率×売上の推定値です — 決して徴収額、債務額、または申告額として提示せず、税率を引用する際は常にエンコード済み税率のスタンプ（「2026年11月確認 — CRA/州の情報源で確認してください」）を添えてください。このツールでは、投入物に支払ったPST/RSTは決してITCではありません。
• 負の純額は還付ポジションであり、収入ではありません。 受け取ったお金として説明しないでください。
• 罰金と利息は決して計算されません — ユーザーが以前の期間に閾値を超えた場合、それはCRA/会計士との会話です; 金額を推定しないでください。
• ローカルのみ: ツールは指定されたファイルを読み取り、どこにも送信しません。