@geekbeer/minion 4.2.1 → 4.3.3

package/core/lib/bundled-skills.js

@@ -0,0 +1,94 @@
+/**
+ * Bundled skill deployment.
+ *
+ * Skills shipped inside the `@geekbeer/minion` package (`skills/`) must reach the
+ * LLM skill directories (`~/.claude/skills/`, etc.) for the agent to actually use
+ * them. `minion-cli configure` copies them at setup time, but a plain package
+ * update (`update-agent` = `npm install -g @geekbeer/minion@latest && restart`)
+ * refreshes the files under node_modules WITHOUT re-running configure — so without
+ * this, bundled skill fixes never reach a running minion.
+ *
+ * Unlike rules/roles/docs (which the servers re-copy unconditionally on every
+ * startup because they are purely package-owned), skills can be customized per
+ * workspace via `minion-cli skill push` / `fetch`, which writes into the same
+ * skill directories. Overwriting on every restart would clobber those custom
+ * versions. So this sync is **version-gated**: bundled skills are (re)deployed
+ * only when the package version differs from the last recorded sync. An
+ * `update-agent` bumps the version → defaults refresh once; ordinary restarts
+ * leave HQ-fetched customizations intact.
+ */
+
+const fs = require('fs')
+const path = require('path')
+
+/**
+ * (Re)deploy bundled skills into the given target directories when the package
+ * version has changed since the last sync.
+ *
+ * @param {object} opts
+ * @param {string} opts.packageRoot  Absolute path to the package root (contains `skills/`)
+ * @param {string} opts.version      Current package version (used as the gate key)
+ * @param {string[]} opts.targetDirs Skill directories to deploy into (e.g. ~/.claude/skills)
+ * @param {string} opts.markerPath   File path storing the last-synced version
+ * @param {Console} [opts.logger]    Logger (defaults to console)
+ * @returns {{ synced: boolean, skills?: number, dirs?: number, reason?: string }}
+ */
+function syncBundledSkills({ packageRoot, version, targetDirs, markerPath, logger = console }) {
+  const bundledSkillsDir = path.join(packageRoot, 'skills')
+
+  try {
+    if (!fs.existsSync(bundledSkillsDir)) {
+      return { synced: false, reason: 'no_bundled_skills' }
+    }
+    if (!version) {
+      return { synced: false, reason: 'no_version' }
+    }
+    if (!Array.isArray(targetDirs) || targetDirs.length === 0) {
+      return { synced: false, reason: 'no_target_dirs' }
+    }
+
+    // Version gate: skip if we already deployed this exact version.
+    let lastSynced = null
+    try {
+      lastSynced = fs.readFileSync(markerPath, 'utf8').trim()
+    } catch {
+      /* no marker yet → first deploy */
+    }
+    if (lastSynced === version) {
+      return { synced: false, reason: 'up_to_date' }
+    }
+
+    const skillNames = fs.readdirSync(bundledSkillsDir).filter((name) => {
+      try {
+        return fs.statSync(path.join(bundledSkillsDir, name)).isDirectory()
+      } catch {
+        return false
+      }
+    })
+
+    for (const targetDir of targetDirs) {
+      fs.mkdirSync(targetDir, { recursive: true })
+      for (const name of skillNames) {
+        const src = path.join(bundledSkillsDir, name)
+        const dest = path.join(targetDir, name)
+        // Clean replace so files removed from the bundle don't linger.
+        fs.rmSync(dest, { recursive: true, force: true })
+        fs.cpSync(src, dest, { recursive: true })
+      }
+    }
+
+    fs.mkdirSync(path.dirname(markerPath), { recursive: true })
+    fs.writeFileSync(markerPath, version)
+
+    logger.log(
+      `[Skills] Re-deployed ${skillNames.length} bundled skill(s) to ${targetDirs.length} dir(s) for v${version}` +
+        (lastSynced ? ` (was v${lastSynced})` : ' (first deploy)'),
+    )
+    return { synced: true, skills: skillNames.length, dirs: targetDirs.length }
+  } catch (err) {
+    logger.error(`[Skills] Failed to sync bundled skills: ${err.message}`)
+    return { synced: false, reason: 'error' }
+  }
+}
+
+module.exports = { syncBundledSkills }

package/docs/api-reference.md

@@ -2358,22 +2358,132 @@ POST レスポンス例:
 | 409 | `version_conflict` (他者の編集と衝突)、`name_conflict`、`order_key_collision` (同時挿入の競合、再送可) |
 | 410 | `deck_in_trash` (デッキがゴミ箱にある) |
 
-### Accounting Receipts 🧪 (HQ, experimental)
+### Accounting (HQ, experimental, v4.3.0〜)
 
 `workspaces.feature_flags.experimental_accounting = true` のワークスペース向け。
-レシート (画像/PDF) の一覧取得・ダウンロード・取引紐付けをBearer認証で行える。
-**典型用途**: 人間が `/accounting/receipts` から大量アップロードした未仕訳レシートを
-ミニオン側で OCR → 仕訳作成 → 紐付け、という記帳ワークフロー。
+**全エンドポイントが accountant ロール必須** — 対象 workspace 内のいずれかのプロジェクトで
+accountant ロールが付与されたミニオンのみアクセスできる (職務分掌の原則)。
+
+不正アクセス時のレスポンス:
+- 403 `{error, code: 'accountant_role_required'}` — ロール無し
+- 403 `{error, code: 'no_projects'}` — workspace にプロジェクトが存在せず検証不能
+- 403 `{error, code: 'feature_disabled'}` — accounting フラグ OFF
+- 401 `{error: 'Missing or invalid Authorization header'}` / `{error: 'Invalid API token'}`
+
+書き込み API は `created_by_minion_id` / `updated_by_minion_id` 列に呼び出し元ミニオン ID を記録する (HQ UI で「ミニオンが書き込み」バッジが表示される)。仕訳の `source` は常に `'ai_generated'` で記録される。
+
+**人間専用操作** (ミニオンから提供しない API):
+
+以下は会計データの根幹に影響するため、ミニオンが自律的に実行することを禁じている。
+ミニオンは [Threads API](#threads-hq) で `@user` メンションして人間に依頼すること。
+
+- 決算期の `close` / `reopen` / 期首残高設定
+- 法人税計算の `finalize` / `journalize` / `reopen`
+- 仕訳・科目・取引先・立替・税計算の `DELETE`
+- 勘定科目の rename / アーカイブ (`PATCH`) — ミニオンは作成 (POST) のみ。編集・アーカイブは人間専用
+- 立替経費の `settle` / `bulk-settle`
+- レシートの `attach` / `detach` (= 仕訳との紐付け)
+
+人間依頼の Threads body 例:
+```json
+{
+  "thread_type": "help",
+  "mentions": ["user"],
+  "title": "法人税計算 FY3 の finalize お願いします",
+  "content": "計算ID xxxx の入力が完了しました。\nHQダッシュボード /accounting/tax-calculations/xxxx でレビュー後、Finalize → Journalize ボタンを押してください。",
+  "context": { "accounting_action": "tax_finalize", "calculation_id": "xxxx" }
+}
+```
+
+#### Books / Periods
+
+| Method | Endpoint | 説明 |
+|--------|----------|-------------|
+| GET | `/api/minion/workspaces/:id/accounting/books` | 帳簿メタ取得 (org_type, currency, accounting_start_date, closed_through 等)。未存在なら自動作成 |
+| GET | `/api/minion/workspaces/:id/accounting/periods` | 決算期一覧 (FY1, FY2, ... と status: open/closed) |
+
+#### Accounts
+
+| Method | Endpoint | 説明 |
+|--------|----------|-------------|
+| GET | `/api/minion/workspaces/:id/accounting/accounts` | 勘定科目一覧。Query: `?type=asset\|liability\|equity\|revenue\|expense`, `?include_archived=true\|false` (default false) |
+| POST | `/api/minion/workspaces/:id/accounting/accounts` | 勘定科目追加。Body: `{ code?, name, type, is_wallet?, sort_order? }` |
+
+#### Counterparties (取引先マスタ)
+
+| Method | Endpoint | 説明 |
+|--------|----------|-------------|
+| GET | `/api/minion/workspaces/:id/accounting/counterparties` | 取引先一覧。Query: `?kind=vendor\|customer\|director\|employee\|other`, `?include_archived=true\|false` |
+| GET | `/api/minion/workspaces/:id/accounting/counterparties/:counterpartyId` | 取引先詳細 + 残高 (`{counterparty, balance: {debit_total, credit_total, net}}`) |
+| POST | `/api/minion/workspaces/:id/accounting/counterparties` | 取引先追加。Body: `{ name, kind, member_id?, default_payable_account_id? }` |
+| PATCH | `/api/minion/workspaces/:id/accounting/counterparties/:counterpartyId` | 取引先更新。Body: `{ name?, kind?, member_id?, default_payable_account_id?, is_archived? }` |
+
+#### Journal Entries (仕訳)
+
+| Method | Endpoint | 説明 |
+|--------|----------|-------------|
+| GET | `/api/minion/workspaces/:id/accounting/entries` | 仕訳一覧。Query: `?from=YYYY-MM-DD&to=YYYY-MM-DD&entry_type=income,expense,...&limit=100&offset=0` |
+| GET | `/api/minion/workspaces/:id/accounting/entries/:entryId` | 仕訳詳細 (lines 込み) |
+| POST | `/api/minion/workspaces/:id/accounting/entries` | 仕訳作成。`source='ai_generated'` で記録。期締め後の日付は 409 `code: 'period_closed'` |
+| PATCH | `/api/minion/workspaces/:id/accounting/entries/:entryId` | 仕訳更新。**`source='ai_generated'` の仕訳のみ更新可** (人間作成仕訳は 409 `code: 'human_owned_entry'`) |
+
+仕訳 Body の形式は `SimpleEntryInput` (income/expense/transfer) と `ManualEntryInput` (manual) があり、後者は明細を直接指定する。詳細は `src/lib/accounting/entry-builder.ts` を参照。
+
+#### Receipts (レシート添付)
 
 | Method | Endpoint | 説明 |
 |--------|----------|-------------|
 | GET | `/api/minion/workspaces/:id/accounting/receipts` | レシート一覧。Query: `?attached=true\|false\|all` (default `false`), `?limit=100` (max 500) |
 | GET | `/api/minion/workspaces/:id/accounting/receipts/:receiptId` | メタデータ |
 | GET | `/api/minion/workspaces/:id/accounting/receipts/:receiptId/download` | 60秒有効な signed URL を返す (`{ url, mime_type, file_name, expires_in_seconds }`) |
-| PATCH | `/api/minion/workspaces/:id/accounting/receipts/:receiptId` | 取引と紐付け / 解除。Body: `{ entry_id: string \| null }`。entry_id 指定時は同じ book に属する取引でないと 400 |
+
+**破壊的変更 (v4.3.0)**: 以前は workspace メンバー全員に開いていたが、accountant ロール必須化。
+attach/detach (`PATCH`) は人間専用化したので、ミニオンが OCR → 仕訳作成した場合は HQ UI から
+ユーザーが添付する運用にする。
 
 レシートのMIME種別は `image/png`, `image/jpeg`, `image/webp`, `image/gif`, `image/heic`, `image/heif`, `application/pdf` のいずれか。
 
-**未実装**: ミニオン向け仕訳作成 API (`POST /api/minion/workspaces/:id/accounting/entries`) は現状未実装。
-OCR後の仕訳作成は、当面ユーザー操作で `/accounting/new` から行うか、HQ管理者向けの Supabase session 経由のみ。
+#### Expense Reimbursements (立替経費)
+
+| Method | Endpoint | 説明 |
+|--------|----------|-------------|
+| GET | `/api/minion/workspaces/:id/accounting/reimbursements` | 立替経費一覧。Query: `?status=settled\|unsettled\|all`, `?counterparty_id=<uuid>`, `?limit=100&offset=0` |
+| POST | `/api/minion/workspaces/:id/accounting/reimbursements` | 立替経費追加。Body: `{ paid_by_counterparty_id, occurred_on, amount, description?, expense_account_id, payable_account_id? }`。仕訳 (借方=expense, 貸方=payable) を自動生成 |
+
+#### Reports (試算表 / B/S / P/L)
+
+| Method | Endpoint | 説明 |
+|--------|----------|-------------|
+| GET | `/api/minion/workspaces/:id/accounting/reports/trial-balance` | 試算表 + B/S + P/L 一括。Query: `?from&to&includeZero=true\|false`。`netAssetBalanceSheet` (正味財産区分付き B/S) は 一般社団法人プロファイルのときのみ含まれる |
+| GET | `/api/minion/workspaces/:id/accounting/reports/income-statement` | P/L のみ (軽量) |
+| GET | `/api/minion/workspaces/:id/accounting/reports/balance-sheet` | B/S のみ (軽量) |
+
+#### Tax Calculations (法人税計算ウィザード)
+
+`org_type=corporation` または `general_incorporated_association` のみ。それ以外は 403 `code: 'org_type_ineligible'`。
+
+| Method | Endpoint | 説明 |
+|--------|----------|-------------|
+| GET | `/api/minion/workspaces/:id/accounting/tax-calculations` | 計算一覧。Query: `?fiscal_period_id=<uuid>&status=draft,finalized,journalized` |
+| GET | `/api/minion/workspaces/:id/accounting/tax-calculations/:calcId` | 詳細 `{calculation, adjustments, components}` |
+| POST | `/api/minion/workspaces/:id/accounting/tax-calculations` | 計算新規作成。Body: `{ fiscal_period_id, notes? }`。6 税目を seed する |
+| PATCH | `/api/minion/workspaces/:id/accounting/tax-calculations/:calcId` | pretax_income / notes 更新 |
+| GET | `/api/minion/workspaces/:id/accounting/tax-calculations/:calcId/pretax-income` | P/L から税引前当期純利益を再計算 (法人税科目は除外) |
+| GET | `/api/minion/workspaces/:id/accounting/tax-calculations/:calcId/ensure-accounts` | 必要4科目 (法人税費用 / 未払 / 仮払 / 未収還付) の存在状況確認 |
+| POST | `/api/minion/workspaces/:id/accounting/tax-calculations/:calcId/ensure-accounts` | 不足4科目をテンプレから自動追加 |
+| POST | `/api/minion/workspaces/:id/accounting/tax-calculations/:calcId/adjustments` | 別表四相当の加算/減算追加。Body: `{ adjustment_type: addition\|deduction, category, amount, description?, sort_order? }`。category は `entertainment_excess` / `depreciation_excess` / `executive_salary_excess` / `reserve_addition` / `dividend_excluded` / `tax_refund_excluded` / `custom` |
+| PATCH | `/api/minion/workspaces/:id/accounting/tax-calculations/:calcId/adjustments/:adjId` | 加算/減算更新 |
+| DELETE | `/api/minion/workspaces/:id/accounting/tax-calculations/:calcId/adjustments/:adjId` | 加算/減算削除 |
+| PATCH | `/api/minion/workspaces/:id/accounting/tax-calculations/:calcId/components/:compId` | 税目別の税率・中間納付・(均等割のみ) 直接税額を更新。`tax_rate` は % 表記 (例 `23.2`)。`calculated_amount` は `tax_type='inhabitant_per_capita'` のみ受理 |
+
+**status 遷移**: ミニオンが触れるのは `draft` のみ。`finalized` / `journalized` 状態の calc を更新しようとすると 409 `code: 'invalid_status'`。reopen も人間専用。
+
+**典型ワークフロー**:
+1. `GET /periods` で期一覧を取得し、対象期 (status='open') の id を選ぶ
+2. `POST /tax-calculations` で新規作成 (pretax_income は P/L から自動取得)
+3. `POST /tax-calculations/:calcId/ensure-accounts` で必要科目を揃える
+4. 国税庁・自治体サイトで税率調査 → `PATCH /components/:compId` で各税目の `tax_rate` を入力
+5. 各税目の中間納付額がある場合 `PATCH /components/:compId` で `prepaid_amount` を入力
+6. 必要なら `POST /adjustments` で別表四相当の加減算を追加 (調査・税理士相談の上)
+7. `POST /api/threads` で人間に finalize 依頼
 

package/docs/task-guides.md

@@ -152,6 +152,25 @@ minion-cli skill list
 minion-cli skill fetch <name>
 ```
 
+`skill fetch` は **HQ レジストリ** から取得する操作です。HQ に push されていないスキルは
+`Skill not found` になります。
+
+### 4. バンドルスキルの配布 (パッケージ同梱スキル)
+
+`@geekbeer/minion` パッケージには既定スキル (例: `accounting-bookkeeping`) が同梱されています。
+これらは **HQ レジストリとは別系統** で、以下のタイミングで `~/.claude/skills/` (および有効な
+他 LLM のスキルディレクトリ) へ自動配備されます:
+
+- `minion-cli configure` 実行時 (初期セットアップ / HQ接続)
+- **パッケージ更新後のエージェント再起動時** (v4.3.3〜) — `update-agent` で `npm install` した後、
+  サーバー起動時に **パッケージのバージョンが変わっていれば** バンドルスキルを再配備する
+  (`~/.minion/skills-sync-version` で前回配備バージョンを記録)
+
+そのため、バンドルスキルの修正を反映するのに `skill fetch` は不要です。`update-agent` →
+再起動だけで最新版が `~/.claude/skills/` に反映されます。HQ にカスタム版を登録している場合は、
+通常の再起動ではそのカスタム版が保持され (バージョン未変更時は再配備しない)、パッケージ更新時
+のみバンドル既定版で上書きされます。ローカルのスキルは `minion-cli skill list --local` で確認できます。
+
 ---
 
 ## DAG ワークフロー (ノード/エッジ形式)

package/linux/server.js

@@ -58,6 +58,10 @@ const { startTerminalProxy, stopTerminalProxy } = require('./terminal-proxy')
 // Config warnings (included in heartbeat)
 const { getConfigWarnings } = require('../core/lib/config-warnings')
 
+// Bundled skill deployment (version-gated, see core/lib/bundled-skills.js)
+const { syncBundledSkills } = require('../core/lib/bundled-skills')
+const { getActiveSkillDirs } = require('../core/llm-plugins/lib/skill-dirs')
+
 // Pull-model daemons (from core/)
 const stepPoller = require('../core/lib/step-poller')
 const dagStepPoller = require('../core/lib/dag-step-poller')
@@ -280,6 +284,25 @@ function syncBundledDocs() {
   }
 }
 
+/**
+ * (Re)deploy bundled skills to the active LLM skill directories when the package
+ * version changed. Lets `update-agent` (npm install + restart) propagate skill
+ * fixes without re-running configure, while preserving HQ-fetched customizations
+ * across ordinary restarts. See core/lib/bundled-skills.js.
+ */
+function syncBundledSkillsOnStartup() {
+  try {
+    syncBundledSkills({
+      packageRoot: PACKAGE_ROOT,
+      version,
+      targetDirs: getActiveSkillDirs(),
+      markerPath: path.join(config.HOME_DIR, '.minion', 'skills-sync-version'),
+    })
+  } catch (err) {
+    console.error(`[Skills] Bundled skill sync skipped: ${err.message}`)
+  }
+}
+
 /**
  * Register all routes (shared + Linux-specific)
  */
@@ -339,6 +362,7 @@ async function start() {
     syncBundledRules()
     syncBundledRoles()
     syncBundledDocs()
+    syncBundledSkillsOnStartup()
     syncPermissions()
     syncTmuxConfig()
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekbeer/minion",
-  "version": "4.2.1",
+  "version": "4.3.3",
   "description": "AI Agent runtime for Minion - manages status and skill deployment on VPS",
   "main": "linux/server.js",
   "bin": {

package/roles/accountant.md

@@ -5,22 +5,31 @@
 ## 責務
 
 - **記帳**: 取引(仕訳)をHQの会計帳簿に正確に記録する
-- **立替経費の処理**: 役員・従業員が立て替えた経費を記帳・精算する
+- **立替経費の処理**: 役員・従業員が立て替えた経費を記帳する(精算の実行は人間に依頼)
 - **取引先マスタの整備**: 仕入先・顧客・役員・従業員などの取引先を整備する
 - **補助元帳の照会**: 取引先別の残高・明細を確認し、PMやユーザーへ報告する
+- **勘定科目の追加**: テンプレートに不足している科目を追加する(rename/アーカイブ/削除は人間専用)
+- **財務諸表の照会・報告**: 試算表・B/S・P/L を取得し、PMやユーザーへ報告する
+- **法人税計算の補助**: 税引前利益の確認・税率調査・別表四加減算の入力を行い、finalize/journalize は人間に依頼する
 
 ## 利用するスキル
 
 会計操作の具体手順とAPI仕様は専用スキルにまとまっています。コアルールにはあえて含めていません(トークン圧迫を避けるため)。
 
-- `/accounting-bookkeeping` — 取引記帳・立替経費・精算・補助元帳の標準フロー
+- `/accounting-bookkeeping` — 取引記帳・立替経費・補助元帳・財務諸表照会・法人税計算の標準フロー
   - 詳細仕様は `~/.claude/skills/accounting-bookkeeping/references/` 配下を必要時に参照
 
-スキルが未配布の場合は `minion-cli skill fetch accounting-bookkeeping` で取得してください。
+このスキルは `@geekbeer/minion` パッケージに同梱されており、セットアップ時およびパッケージ更新後の
+エージェント再起動時に `~/.claude/skills/` へ自動配備されます。通常 `skill fetch` は不要です。
+万一ローカルに存在しない場合は `minion-cli skill list --local` で確認し、HQ にカスタム版を登録している
+場合のみ `minion-cli skill fetch accounting-bookkeeping` で取得してください
+(バンドル版は HQ には登録されていないため、未カスタムだと `Skill not found` になります)。
 
 ## 重要な原則
 
+- **高リスク操作は人間に依頼する。** 決算期の close/reopen、法人税計算の finalize/journalize、各リソースの DELETE、勘定科目の rename/アーカイブ、立替経費の精算(settle)はミニオンに提供されていません。必要な場合は `POST /api/threads` で `@user` メンションして HQ UI 操作を依頼すること。
 - **仕訳の確定済み(closed)期は修正しない。** 締め後の仕訳訂正はPMの承認が必要です。
+- **編集できる仕訳は自分(AI)が作成したものだけ。** 人間作成仕訳の PATCH は 409 `human_owned_entry` で弾かれます。訂正が必要なら人間に依頼。
 - **立替経費は取引先(counterparty)を必ず紐付ける。** 「誰の立替か」を後から照会できるようにするため。
 - **default_payable_account_id 未設定の取引先には立替記帳できない。** API が 422 を返します。先に取引先ページで貸方科目を設定してください。
 - **判断に迷ったら勝手に進めない。** 不明な取引・推測の余地がある仕訳は、threadで PM にエスカレーションすること。

package/rules/core.md

@@ -514,6 +514,68 @@ cp /tmp/report.pdf ~/files/reports/2026-04/report.pdf
 - テキスト成果物 → ローカルメモリ (`POST /api/memory`) に保存
 - バイナリファイル → `~/files/` に保存
 
+## Accounting Operations (会計操作, v4.3.0〜)
+
+会計データは法的責任を伴うため、**accountant ロールを付与されたミニオンのみ** 操作可能。
+
+### アクセス要件
+
+- 対象 workspace 内の **いずれかのプロジェクト** で `accountant` ロールを持っていること
+- workspace で `experimental_accounting` feature flag が ON であること
+- 不在の場合は 403 `code: 'accountant_role_required'` / `'feature_disabled'` が返る
+
+### API
+
+エンドポイントは `/api/minion/workspaces/:id/accounting/*`。詳細は `~/.minion/docs/api-reference.md` の「Accounting」セクションを参照。
+
+主なリソース:
+- **Books / Periods / Reports** — 帳簿メタ、決算期、試算表 / B/S / P/L (照会のみ)
+- **Accounts** — 勘定科目の照会 (GET) と追加 (POST) のみ。rename / アーカイブ / 削除は人間専用
+- **Counterparties** — 取引先マスタの照会・追加・更新 (GET / POST / PATCH。`is_archived` でアーカイブ可)
+- **Journal Entries** — 仕訳の作成 (POST) と AI 生成仕訳の更新 (PATCH)
+- **Receipts** — レシート一覧 / ダウンロード
+- **Expense Reimbursements** — 立替経費の登録
+- **Tax Calculations** — 法人税計算ウィザード (別表四相当の加減算 + 6 税目別税率入力 + 仕訳生成準備)
+
+### 守るべきルール
+
+1. **仕訳は `source='ai_generated'` で自動記録される** — ミニオン経由で作成した仕訳は HQ UI で 🤖 バッジ付きで表示される。人間がレビューしてから承認する前提で動くこと。
+2. **人間作成仕訳 (`source='manual'` / `'import'`) は更新できない** — PATCH すると 409 `code: 'human_owned_entry'`。修正が必要なら人間に依頼する。
+3. **税率はユーザー責任で入力する** — 法人税計算ウィザードの税率欄は国税庁・自治体サイトで最新値を調査して入力すること。本ツールは税率テーブルを持たない。
+
+### 人間専用操作 (ミニオンから提供されない API)
+
+以下はデータの根幹に影響するため、ミニオンが自律実行することを禁止している。
+ミニオンは **threads で `@user` メンション + 計算 ID / 期 ID をリンクして人間に依頼** すること。
+
+| 操作 | 依頼すべき相手 / 方法 |
+|------|---------------------|
+| 決算期の `close` / `reopen` / 期首残高設定 | HQ ダッシュボード `/accounting/periods` から人間が実行 |
+| 法人税計算の `finalize` / `journalize` / `reopen` | `/accounting/tax-calculations/:id` のウィザード末尾ボタン |
+| 仕訳・科目・取引先・税計算の `DELETE` | HQ UI 各リスト画面 |
+| 勘定科目の rename / アーカイブ (`PATCH`) | `/accounting/accounts` から人間が実行 (ミニオンは POST のみ) |
+| 立替経費の `settle` / `bulk-settle` | `/accounting/reimbursements` の精算ボタン |
+| レシートと仕訳の `attach` / `detach` | HQ UI で人間が判断 |
+
+依頼スレッドの body 例:
+```bash
+curl -X POST -H "Authorization: Bearer $API_TOKEN" -H "Content-Type: application/json" \
+  http://localhost:8080/api/threads \
+  -d '{
+    "thread_type": "help",
+    "mentions": ["user"],
+    "title": "法人税計算 FY3 の finalize お願いします",
+    "content": "計算ID XXXX の入力が完了しました。HQダッシュボードでレビュー後、Finalize → Journalize ボタンを押してください。",
+    "context": { "accounting_action": "tax_finalize", "calculation_id": "XXXX" }
+  }'
+```
+
+### 監査と可視化
+
+ミニオン書き込みは以下で記録・可視化される:
+- DB: `created_by_minion_id` / `updated_by_minion_id` 列 (主要 7 テーブル)
+- HQ UI: 仕訳一覧 / 取引先 / 立替経費 / 法人税計算ウィザードの各項目に 🤖 バッジ表示
+
 ## Documentation
 
 API仕様やタスク手順の詳細は以下を参照:

package/skills/accounting-bookkeeping/SKILL.md

@@ -1,17 +1,26 @@
 ---
 name: accounting-bookkeeping
-description: 会計帳簿の記帳・立替経費の処理・補助元帳の照会を行うワークフロー。使用タイミング：(1) 取引を仕訳として記録する時、(2) 役員・従業員の立替経費を記帳・精算する時、(3) 取引先別の残高を確認する時。accountantロールのミニオンが主に使用する。
+description: 会計帳簿の記帳・立替経費の処理・補助元帳の照会・財務諸表の照会・法人税計算の補助を行うワークフロー。使用タイミング：(1) 取引を仕訳として記録する時、(2) 役員・従業員の立替経費を記帳する時、(3) 取引先別の残高を確認する時、(4) 試算表・B/S・P/L を取得して報告する時、(5) 法人税計算ウィザードに入力する時。accountantロールのミニオンが主に使用する。
 ---
 
 # Accounting Bookkeeping
 
 会計帳簿(HQ Accounting API)を操作するためのスキル。複式簿記の整合性を保ちながら、AI(ミニオン)が安全に記帳できるよう設計されている。
 
-## 前提
+## 前提・アクセス要件
 
-- ワークスペースで experimental_accounting feature flag が有効になっていること
-- HQ API は `$HQ_URL/api/accounting/*` で利用可能(authentication は `Authorization: Bearer $API_TOKEN`)
-- 1ワークスペース1帳簿の前提。`GET /books` で帳簿を取得し、勘定科目テンプレートはデフォルトで投入済み
+このスキルが叩くのは **ミニオン専用の会計 API** (`$HQ_URL/api/minion/workspaces/:id/accounting/*`)。
+人間用の `/api/accounting/*` (Supabase セッション認証) とは別系統で、**ミニオンは必ずこちらを使う**こと。
+
+- 認証は `Authorization: Bearer $API_TOKEN`。`:id` は対象 **ワークスペース ID**(パスに含める)
+- 対象 workspace 内の **いずれかのプロジェクト**で `accountant` ロールを持っていること
+  (持たない場合は 403 `code: 'accountant_role_required'`)
+- workspace で `experimental_accounting` feature flag が ON であること
+  (OFF なら 403 `code: 'feature_disabled'`)
+- 1ワークスペース1帳簿の前提。`GET .../books` で帳簿を取得し、勘定科目テンプレートはデフォルトで投入済み
+- 書き込みは `created_by_minion_id` / `updated_by_minion_id` に呼び出し元ミニオン ID が記録され、HQ UI で 🤖 バッジ表示される。仕訳の `source` は常に `'ai_generated'`
+
+API 全体のエンドポイント表は `~/.minion/docs/api-reference.md` の「Accounting」セクションを参照。
 
 ## 語彙
 
@@ -26,12 +35,14 @@ description: 会計帳簿の記帳・立替経費の処理・補助元帳の照
 
 ## 典型フロー
 
+> 以下のパスはすべて `$HQ_URL/api/minion/workspaces/:id/accounting/` を基準とした相対表記。
+
 ### A) 通常取引の記帳
 
 ```
-1. GET /api/accounting/accounts で勘定科目一覧取得
+1. GET /accounts で勘定科目一覧取得
 2. 入金/出金口座(is_wallet=true)と相手勘定(費用 or 収益)を特定
-3. POST /api/accounting/entries でシンプル仕訳を作成
+3. POST /entries でシンプル仕訳を作成
    body: { entry_type: 'expense'|'income', entry_date, amount, wallet_account_id, category_account_id, description }
 ```
 
@@ -41,37 +52,82 @@ description: 会計帳簿の記帳・立替経費の処理・補助元帳の照
 
 ```
 1. 立替者(役員/従業員)の counterparty を確認
-   - GET /api/accounting/counterparties?q=<name>&kind=director,employee
-   - 見つからなければ POST /api/accounting/counterparties で作成
+   - GET /counterparties?kind=director,employee
+   - 見つからなければ POST /counterparties で作成
    - default_payable_account_id が未設定なら PATCH で先に設定する
-2. POST /api/accounting/expense-reimbursements で記帳
+2. POST /reimbursements で記帳
    body: { paid_by_counterparty_id, occurred_on, amount, expense_account_id, description }
    → 内部で「(借)費用 / (貸)立替者の負債科目」の仕訳が自動生成される
-3. レシートがあれば事前に POST /api/accounting/receipts でアップロードし、receipt_ids を渡す
+3. レシートがあれば事前に GET /receipts で対象を確認 (アップロードと仕訳への attach は人間が HQ UI で行う)
 ```
 
 詳細: `references/api-expense-reimbursement.md`
 
-### C) 立替経費の精算
+### B') レシートの照会・OCR
 
 ```
-1. GET /api/accounting/expense-reimbursements?settled=false で未精算リスト取得
-2. POST /api/accounting/expense-reimbursements/<id>/settle で精算
-   body: { settled_on, wallet_account_id }
-   → 内部で「(借)立替者の負債科目 / (貸)現金or預金」の仕訳が自動生成される
+GET /receipts?attached=false        → 未処理(未添付)レシート一覧
+GET /receipts/:receiptId/download   → 60秒有効な signed URL を取得し画像/PDFを読み取り (OCR)
 ```
 
-部分精算は非対応。全額精算のみ。
+読み取った内容から仕訳/立替を作成する。アップロードと仕訳への attach/detach は人間専用。
+詳細: `references/api-receipts.md`
+
+### C) 立替経費の精算 — **人間専用**
+
+精算 (`settle` / `bulk-settle`) は実際の出金を伴うため**ミニオンからは実行できない**。
+未精算リストを `GET /reimbursements?status=unsettled` で把握し、精算が必要な分は
+`POST /api/threads` で `@user` メンションして HQ UI の精算ボタンを依頼すること。
 
 ### D) 補助元帳の照会
 
 ```
-GET /api/accounting/counterparties/<id>/balance
-→ 取引先別の残高(勘定科目ごと)・明細リスト・未精算立替件数を返す
+GET /counterparties/:counterpartyId
+→ 取引先の詳細 + 残高サマリ ({ counterparty, balance: { debit_total, credit_total, net } }) を返す
 ```
 
 詳細: `references/api-counterparties.md`
 
+### E) 財務諸表の照会・報告
+
+```
+GET /reports/trial-balance   → 試算表 + B/S + P/L 一括 (Query: ?from&to&includeZero)
+GET /reports/income-statement → P/L のみ (軽量)
+GET /reports/balance-sheet    → B/S のみ (軽量)
+```
+
+PM やユーザーへの月次報告などで使う。取得した数値は**ノート (`hq note create`)** にまとめて共有するとよい。
+詳細: `references/api-reports-tax.md`
+
+### F) 法人税計算ウィザードの入力補助
+
+`org_type=corporation` / `general_incorporated_association` の帳簿のみ対象 (それ以外は 403 `org_type_ineligible`)。
+ミニオンが触れるのは `draft` 状態のみ。**`finalize` / `journalize` は人間専用**。
+
+```
+1. GET /periods で対象期 (status='open') を選ぶ
+2. POST /tax-calculations で新規作成 (pretax_income は P/L から自動取得)
+3. POST /tax-calculations/:calcId/ensure-accounts で必要4科目を揃える
+4. 国税庁・自治体サイトで最新税率を調査 → PATCH /tax-calculations/:calcId/components/:compId で各税目の tax_rate を入力
+5. 中間納付があれば PATCH /components/:compId で prepaid_amount を入力
+6. 必要なら POST /tax-calculations/:calcId/adjustments で別表四相当の加減算を追加
+7. POST /api/threads で人間に finalize → journalize を依頼
+```
+
+詳細: `references/api-reports-tax.md`
+
+### G) 勘定科目の追加
+
+テンプレートに不足している科目(例: 立替用の「役員借入金」)は追加できる。
+
+```
+POST /accounts
+  body: { name, type: 'asset'|'liability'|'equity'|'revenue'|'expense', code?, is_wallet?, sort_order? }
+```
+
+**科目の rename / アーカイブ / 削除はミニオンからは実行できない**(人間専用)。
+不要・誤った科目の整理が必要な場合は `POST /api/threads` で人間に HQ UI 操作を依頼すること。
+
 ## エラーレスポンスの読み方
 
 会計APIは AI 向けに以下の構造でエラーを返す:
@@ -80,7 +136,7 @@ GET /api/accounting/counterparties/<id>/balance
 {
   "error": "missing_default_payable_account",
   "message": "取引先「山田太郎」に立替用の貸方科目が未設定です",
-  "next_action": "PATCH /api/accounting/counterparties/<id> で default_payable_account_id を設定してください...",
+  "next_action": "PATCH /counterparties/<id> で default_payable_account_id を設定してください...",
   "context": { "counterparty_id": "..." }
 }
 ```
@@ -89,9 +145,26 @@ GET /api/accounting/counterparties/<id>/balance
 
 主要エラーパターンと対処は `references/troubleshooting.md` を参照。
 
+## 人間専用操作 (ミニオンから提供されない)
+
+以下はデータの根幹に影響するため、ミニオンが自律実行することを禁じている。
+必要な場合は `POST /api/threads` で `@user` メンション + 対象 ID をリンクして人間に依頼する。
+
+| 操作 | 依頼先 (HQ UI) |
+|------|---------------|
+| 決算期の close / reopen / 期首残高設定 | `/accounting/periods` |
+| 法人税計算の finalize / journalize / reopen | `/accounting/tax-calculations/:id` ウィザード末尾 |
+| 仕訳・科目・取引先・立替・税計算の DELETE | 各リスト画面 |
+| 科目の rename / アーカイブ (PATCH) | `/accounting/accounts` |
+| 立替経費の settle / bulk-settle | `/accounting/reimbursements` |
+| レシートと仕訳の attach / detach | 各画面 |
+| 人間作成仕訳 (`source='manual'`/`'import'`) の編集 | HQ UI (PATCH は 409 `human_owned_entry`) |
+
 ## 重要な制約
 
-- **確定済み期間(closed)の日付では記帳できない。** 422/409 で拒否される。日付を変えるか PM に再オープン依頼
+- **確定済み期間(closed)の日付では記帳できない。** 409 `period_closed` で拒否される。日付を変えるか PM に再オープン依頼
+- **PATCH できる仕訳は `source='ai_generated'` のものだけ。** 人間作成仕訳は 409 `human_owned_entry`
 - **立替の貸方科目は負債(liability) or 純資産(equity)のみ許容。** 資産勘定の「立替金」(他人のために会社が立て替える勘定)は逆向きなので NG
 - **counterparty マスタは book スコープ。** 別帳簿のIDは使えない
 - **複式簿記の借方=貸方は trigger で強制される。** 自前で計算してから POST すること
+- **税率はユーザー責任で入力する。** 本ツールは税率テーブルを持たない。最新値を調査して入力すること