よくある質問とトラブルシュート

このページは、Relqis の導入直後と日常運用でよく詰まる点を先回りして整理したものです。

rlq が見つからない

まず 最新の GitHub Release から取得した artifact を展開し、シェルから rlq --help を実行できることを確認してください。nightly build を使いたい場合は Releases 一覧 を参照してください。

• stable を使いたい場合:
  • GitHub Release の正式版 artifact を使う
• 先行確認をしたい場合:
  • nightly artifact を使う

artifact と checksum が揃っていない build は、配布対象として扱わないでください。

rlq skills install を実行したのに DB ができない

これは正常です。skills install は .agents/skills/relqis/ を配置するだけで、会計 DB には触れません。

data/company.db のような SQLite ファイルは、最初の会計操作が走った時点で自動作成されます。

たとえば、存在しない DB に対して次のような read command を実行すると、疎通確認と schema bootstrap を兼ねられます。

rlq --database-path data/company.db fiscal-period list --json

AGENTS.md を出そうとしたら conflict になった

rlq skills install --write-agents-template は、workspace root にすでに AGENTS.md がある場合、既存ファイルを勝手に上書きしません。

対処は次のどちらかです。

• 既存の AGENTS.md を残したい:
  • 同梱テンプレートを参考に手で統合する
• 既存の AGENTS.md を置き換えてよい:
  • 内容を退避したうえで --force を付けて再実行する

AGENTS.md は workspace 固有の運用ファイルです。skills status の managed file には含まれません。

skills status の state が modified / partial / drifted になった

意味は次のとおりです。

• up_to_date:
  • 現在の同梱 skill と managed file が一致している
• drifted:
  • managed file は残っているが、同梱 version と差分がある
• modified:
  • managed file がローカルで変更されている、または manifest が壊れている
• partial:
  • managed file の一部が欠けている
• not_installed:
  • まだ install されていない

modified や partial を解消したいときは、まずローカル変更を確認し、上書きしてよいなら rlq skills install --force を使います。

.agents/skills/relqis/ を直接編集してよいか

基本的には避けてください。ここは rlq skills install が管理する領域で、再 install や update で上書きされます。

• 共通の安全ルールや CLI 運用:
  • bundled skill 側に置く
• workspace 固有の DB path、承認条件、勘定科目の読み替え:
  • AGENTS.md に置く

どのエラーを自動再試行してよいか

自動化では --json を使い、error.category と exit code を見て判断してください。

• invalid_request:
  • 入力や option を直すまで再試行しない
• conflict:
  • optimistic concurrency や local modification を確認してから再試行する
• internal:
  • SQLITE_BUSY / SQLITE_LOCKED のような一時的失敗なら再試行候補

詳細は CLI 出力契約 と、install 済み skill の references/error-recovery.md を参照してください。

SQLite を直接直してよいか

避けてください。Relqis は ledger を唯一の会計 source of truth として扱い、会計状態の変更は rlq 経由で行う前提です。

特に posted entry は不変です。manual/import 起源の normal entry を訂正する場合は、まず entry reverse を使ってください。entry void は duplicate intake など、domain policy が original posted fact の invalidation を明示的に許すケースに限ります。receivable / payable / fixed asset / closing / carryforward などの workflow-owned entry は generic entry reverse の対象ではないので、その owning workflow 側の訂正フローを使ってください。

目安として、duplicate import / duplicate replay / 同じ source fact の二重 post は entry void 側です。金額訂正、勘定科目振替、日付修正、見越計上の戻し、単純な再分類は original fact を帳簿上に残した方が説明しやすいので entry reverse を使ってください。

fixed asset registration の source line を間違えた場合は、まず asset void-registration で fixed-assets ownership を解除してください。これは depreciation history が無く、retire 前の registration にだけ許可されます。その後で source entry を通常の reverse/rebook フローで訂正します。

fixed asset の取得原価だけを増減させたい場合は、source entry を触らず asset adjust-basis を使ってください。これは explicit ledger adjustment と fixed-assets correction history を同時に残すフローで、depreciation への影響は対象 fiscal month-end から将来分にだけ反映されます。

Relqis v1.0 の fixed-assets は cost model と zero-proceeds の full retirement までを対象にしています。revaluation、impairment、partial disposal は dedicated workflow としては扱いません。partial disposal の可能性がある asset は component ごとに分けて登録してください。sale proceeds がある full disposal では、proceeds/gain/loss の仕訳は manual/import posting で別に起票し、asset retire は derecognition side にだけ使ってください。

年次締めと繰越は一度に実行されるか

別操作です。推奨順序は次のとおりです。

1. check close --closing-type year_close
2. close year preview
3. close year run
4. check close --closing-type carryforward
5. carryforward preview
6. carryforward run

先に preview を見て、人が確認してから run してください。

zero-balance 年度では carryforward preview / carryforward run が no-op completion として成功することがあります。この場合は closing run と audit は残りますが、posting request や carryforward entry は生成されません。

月次締め前に未消込の receipt や payment があるとどうなるか

check close --closing-type month_close は、月末時点で未消込の receipt / payment を blocking error として返します。receivable / payable open item は warning で表示されます。

一方で、receivable create / receipt create / payable create / payment create が作った external-domain PostingRequest に ledger entry が無い場合も blocking error です。subledger 上で settled / fully_applied まで進んでいても、ledger が未反映なら close は通りません。

先に次のいずれかで subledger を解消してください。

1. receivable apply
2. payable apply
3. receivable apply-credit-note
4. payable apply-debit-note
5. receivable / payable owned posting は credit/debit note や source document の再起票など、owning workflow 側で補正する
6. linked external-domain posting が pending / rejected / failed のままなら、先に postreq validate と entry post を完了する

月次締め前に銀行未照合や未実行減価償却、税サマリ未確認があるとどうなるか

check close --closing-type month_close では、未照合の bank statement、未実行の減価償却、未確認の tax summary は warning です。月次を provisional に進めることはできます。

ただし final review までに reconcile run、depreciation run、必要なら tax-summary confirm を済ませてください。

year close 前に銀行未照合や tax summary 未確認があるとどうなるか

check close --closing-type year_close では、未照合の bank statement と未確認の tax summary は warning です。year close 自体は進められます。 reconcile reverse で statement line を reopen した場合は、該当 scope の month/year close check で bank warning が再表示されます。

一方で pending fixed-asset depreciation は blocking のままです。先に depreciation run を完了してください。

year close 済みの月を reopen したい

close reopen-month は、fiscal period がすでに year close 済みだと失敗します。先に close reopen-year を実行して fiscal period 全体を reopen してから、必要な月を reopen してください。

carryforward 済みの前期を reopen したい

close reopen-year は、source fiscal period に紐づく carryforward entry を rollback してから year reopen を行います。

ただし rollback の reversal は target fiscal period の開始日で作るため、target period の opening month がまだ open である必要があります。

target opening month が closed なら、そのままでは rollback できません。先に target 側を reopen するか、manual adjustment で吸収するかを運用方針として決めてください。

carryforward check で open item や銀行未照合、税サマリ未確認が表示されない

check close --closing-type carryforward は、subledger settlement、bank reconciliation、pending depreciation、tax summary confirmation などの operational readiness item を意図的に無視します。

ただし、source fiscal period に属する external-domain PostingRequest で ledger entry が無いものは carryforward でも blocking です。ledger が accounting source of truth なので、subledger だけが先行した状態では翌期へ進めません。

reconcile reverse で bank statement line を reopen した後でも、この方針は変わりません。bank warning を再確認したい場合は month_close または year_close の check close を使ってください。

check close の evidence warning が多い

check close は evidence 未添付 entry を origin bucket ごとに分けて表示します。

1. non-system entry は warning
2. system-generated entry は info

system-generated entry も evidence coverage 自体は観測しますが、operator が優先的に見直すべきなのは manual/import/external-domain 側なので、system-generated bucket は一段弱い signal に落としています。

profit-loss show が closing day を含んでもゼロにならない

profit-loss show は既定で entry_type=closing を除外します。operator が年度損益を確認するときに、year-close entry の netting で「その年度の損益がゼロに見える」状態を避けるためです。

closing entry を含めた結果も確認したい場合だけ、--include-closing-entries を付けてください。

例:

1. rlq profit-loss show --from 2026-04-01 --to 2027-03-31 --json
2. rlq profit-loss show --from 2026-04-01 --to 2027-03-31 --include-closing-entries --json

carryforward の目的は year-close 済み残高を翌期へ移すことなので、ここで見るのは year close state、profit/loss closed、carryforward balance の整合性、そして target fiscal period policy です。

target fiscal period policy では、target が source の直後 fiscal period であることと、target opening month が open であることを見ます。