natsukium/felis

Watch

[1.0 Review] リリース凍結物（crate version / spec REQ / docs / 成果物 / audit）の最終確認 #9

New issue

Closed

opened 2026-09-03 16:04:17 +09:00 by natsukium · 1 comment

natsukium commented

2026-09-03 16:04:17 +09:00

Owner

背景

1.0 リリースは単にタグを打つことではなく、CRATE_VERSION / PROTOCOL_VERSION / 仕様文書 / リリース成果物の契約を凍結すること。reference/workspace.md の Versioning 節に「二つの version 軸（crate version と protocol version）は別物」と明記されているが、1.0 で何を凍結し何を additive にするかの最終確認が必要。backlog.md にも多数の deferred 項目が残っている。

現状の問題 / 凍結前に決めるべき点

1. crate version `0.1.0` のまま 1.0 を打つか

現行: 11 crate 全て 0.1.0、workspace publish = false。felis-protocol は将来 crates.io 公開を想定し 0.1.0 のままで wire の PROTOCOL_MAJOR=1 / MINOR=5 と独立。

1.0 で:

felis-protocol を 1.0.0 に上げ、他 crate は 0.1.0 のままにするか。
全 crate を 1.0.0 に揃えるか。
それとも全 crate を 0.1.0 のまま tag v1.0.0 を打つか（workspace version と git tag を分離）。

reference/workspace.md の「Revisit if felis-protocol is published」節を 1.0 でどう更新するか。

2. spec REQ-XXX の凍結と ledger

reference/spec.md に REQ-001..REQ-1206 が RFC2119 レベル付きで列挙。各 REQ は reference/* / explanation/* のいずれかを source とする。1.0 で REQ 番号を凍結（renumber 不可）にするか、将来の追加は末尾に append のみにするか。

reference/ipc.md の minor ledger（各 minor で追加された kind/field/variant と old-peer behavior）が 1.0 時点でどこまで埋まっているか。PROTOCOL_MINOR=5 までの ledger が正確か最終監査が必要。

3. docs の Diátaxis 4象限と twin 則

tutorials/（learning）/ how-to/（task）/ reference/（lookup）/ explanation/（understanding）の4象限と、「subject が twin に分かれたら reference が normative、explanation が rationale」を担う twin 則。docs/README.md が map。

1.0 で docs ツリーを出版（felis-docs の submodule）する際に、twin 間で重複・乖離が無いか最終 grep sweep（doc-cascade skill の手順）が必要。特に reference/cli.md / control-surfaces.md / explanation/architecture/control-surfaces.md の三角が 1.0 で整合しているか。

4. リリース成果物と platform matrix

reference/workspace.md の Build matrix（x86_64-linux / aarch64-linux / aarch64-darwin / x86_64-pc-windows-msvc）と flake.nix の .#windows cross shell。1.0 で配布する成果物:

felis（front-door）+ felis-client（GUI）+ felis-daemon の3バイナリか、felis-cli / felis-client / felis-daemon の crate 名のままか。
nix/hm-module.nix の Home Manager module。
felis-config.schema.json の JSON Schema。
terminfo xterm-felis（reference/terminal-identity.md）。

justfile の nix-build / macos-app / build-windows-msvc が 1.0 の再現ビルドとして機能するか。

5. security audits の凍結

reference/security-audits.md に O_CLOEXEC+O_NOFOLLOW 開口部と felis-protocol purity の standing audit。1.0 で audit 項目を追加（例: FELIS_SOCKET の symlink 解決、SpawnArgs.env の deny list）するか、現行2項目で凍結するか。

6. machine output 契約（`v:1` envelope）

reference/cli.md の envelope（{"v":1, ...}）は CLI output contract の epoch で wire minor では bump しない。felis bridge も同じ v:1。Point（human|json）/ Stream（human|jsonl）/ Exempt の3クラス、terminal object（end / error）、error.kind の closed set（no_match, ambiguous, ...）が 1.0 で凍結。

問い: error.kind の closed set に将来の追加は additive か breaking か。reference/cli.md に「fields may be added within an epoch」とあるが、kind の追加は consumer が branch する値なので breaking に近い。1.0 で kind 追加は minor 扱いにするか major 扱いにするか。

7. backlog の deferred 項目の扱い

backlog.md に多数の Blocked/deferred（例: Windows inherit_handles、--config flag、Kani 未証明、conPTY win32-input-mode、heavy-payload suppression bit）。1.0 で backlog から外す（Won't fix として non-goals.md に昇格）か、1.0 以降の roadmap として残すか。

提案

1.0 リリースチェックリストを docs/backlog.md から独立した docs/howto/release.md または RELEASE_CHECKLIST.md に切り出し、以下を gate にする:
1. just check（fmt + clippy + nextest + deny）green
2. just schema の生成物が stale でない
3. just proto + buf breaking で wire compat 確認
4. reference/spec.md の REQ 番号と reference/ipc.md の ledger の整合
5. reference/security-audits.md の audit 通過
6. 3 platform（Linux/macOS/Windows）の smoke / cross-compile green
crate version 策を reference/workspace.md に明記し、1.0 tag と PROTOCOL_VERSION の関係を CHANGELOG.md の Unreleased → 1.0 に記録。
error.kind の追加ポリシーを reference/cli.md の envelope 節に明記（additive だが consumer は unknown kind を internal 扱いで fallback すべき、等）。

判定基準

1.0 tag 後に cargo publish（felis-protocol）しても semver と protocol version が衝突しないこと。
新 contributor が just --list でリリースに必要な全 gate を発見できること。
1.0 の CHANGELOG.md が、ユーザが felis --version と felis daemon status の出力から「どの build がどの wire を喋るか」を判断できる情報を含むこと。

cc @natsukium

## 背景 1.0 リリースは単にタグを打つことではなく、CRATE_VERSION / PROTOCOL_VERSION / 仕様文書 / リリース成果物の契約を凍結すること。`reference/workspace.md` の Versioning 節に「二つの version 軸（crate version と protocol version）は別物」と明記されているが、1.0 で何を凍結し何を additive にするかの最終確認が必要。`backlog.md` にも多数の deferred 項目が残っている。 ## 現状の問題 / 凍結前に決めるべき点 ### 1. crate version `0.1.0` のまま 1.0 を打つか現行: 11 crate 全て `0.1.0`、workspace `publish = false`。`felis-protocol` は将来 crates.io 公開を想定し `0.1.0` のままで wire の `PROTOCOL_MAJOR=1 / MINOR=5` と独立。 1.0 で: - `felis-protocol` を `1.0.0` に上げ、他 crate は `0.1.0` のままにするか。 - 全 crate を `1.0.0` に揃えるか。 - それとも全 crate を `0.1.0` のまま tag `v1.0.0` を打つか（workspace version と git tag を分離）。 `reference/workspace.md` の「Revisit if `felis-protocol` is published」節を 1.0 でどう更新するか。 ### 2. spec REQ-XXX の凍結と ledger `reference/spec.md` に REQ-001..REQ-1206 が RFC2119 レベル付きで列挙。各 REQ は `reference/*` / `explanation/*` のいずれかを source とする。1.0 で REQ 番号を凍結（renumber 不可）にするか、将来の追加は末尾に append のみにするか。 `reference/ipc.md` の minor ledger（各 minor で追加された kind/field/variant と old-peer behavior）が 1.0 時点でどこまで埋まっているか。`PROTOCOL_MINOR=5` までの ledger が正確か最終監査が必要。 ### 3. docs の Diátaxis 4象限と twin 則 `tutorials/`（learning）/ `how-to/`（task）/ `reference/`（lookup）/ `explanation/`（understanding）の4象限と、「subject が twin に分かれたら reference が normative、explanation が rationale」を担う twin 則。`docs/README.md` が map。 1.0 で docs ツリーを出版（`felis-docs` の submodule）する際に、twin 間で重複・乖離が無いか最終 grep sweep（`doc-cascade` skill の手順）が必要。特に `reference/cli.md` / `control-surfaces.md` / `explanation/architecture/control-surfaces.md` の三角が 1.0 で整合しているか。 ### 4. リリース成果物と platform matrix `reference/workspace.md` の Build matrix（x86_64-linux / aarch64-linux / aarch64-darwin / x86_64-pc-windows-msvc）と `flake.nix` の `.#windows` cross shell。1.0 で配布する成果物: - `felis`（front-door）+ `felis-client`（GUI）+ `felis-daemon` の3バイナリか、`felis-cli` / `felis-client` / `felis-daemon` の crate 名のままか。 - `nix/hm-module.nix` の Home Manager module。 - `felis-config.schema.json` の JSON Schema。 - terminfo `xterm-felis`（`reference/terminal-identity.md`）。 `justfile` の `nix-build` / `macos-app` / `build-windows-msvc` が 1.0 の再現ビルドとして機能するか。 ### 5. security audits の凍結 `reference/security-audits.md` に `O_CLOEXEC+O_NOFOLLOW` 開口部と `felis-protocol` purity の standing audit。1.0 で audit 項目を追加（例: `FELIS_SOCKET` の symlink 解決、`SpawnArgs.env` の deny list）するか、現行2項目で凍結するか。 ### 6. machine output 契約（`v:1` envelope） `reference/cli.md` の envelope（`{"v":1, ...}`）は CLI output contract の epoch で wire minor では bump しない。`felis bridge` も同じ `v:1`。Point（`human|json`）/ Stream（`human|jsonl`）/ Exempt の3クラス、terminal object（`end` / `error`）、`error.kind` の closed set（`no_match, ambiguous, ...`）が 1.0 で凍結。 **問い:** `error.kind` の closed set に将来の追加は additive か breaking か。`reference/cli.md` に「fields may be added within an epoch」とあるが、`kind` の追加は consumer が branch する値なので breaking に近い。1.0 で `kind` 追加は minor 扱いにするか major 扱いにするか。 ### 7. backlog の deferred 項目の扱い `backlog.md` に多数の Blocked/deferred（例: Windows `inherit_handles`、`--config` flag、Kani 未証明、`conPTY win32-input-mode`、`heavy-payload suppression bit`）。1.0 で backlog から外す（Won't fix として `non-goals.md` に昇格）か、1.0 以降の roadmap として残すか。 ## 提案 - 1.0 リリースチェックリストを `docs/backlog.md` から独立した `docs/howto/release.md` または `RELEASE_CHECKLIST.md` に切り出し、以下を gate にする: 1. `just check`（fmt + clippy + nextest + deny）green 2. `just schema` の生成物が stale でない 3. `just proto` + `buf breaking` で wire compat 確認 4. `reference/spec.md` の REQ 番号と `reference/ipc.md` の ledger の整合 5. `reference/security-audits.md` の audit 通過 6. 3 platform（Linux/macOS/Windows）の smoke / cross-compile green - crate version 策を `reference/workspace.md` に明記し、1.0 tag と `PROTOCOL_VERSION` の関係を `CHANGELOG.md` の Unreleased → 1.0 に記録。 - `error.kind` の追加ポリシーを `reference/cli.md` の envelope 節に明記（additive だが consumer は unknown kind を `internal` 扱いで fallback すべき、等）。 ## 判定基準 - 1.0 tag 後に `cargo publish`（`felis-protocol`）しても semver と protocol version が衝突しないこと。 - 新 contributor が `just --list` でリリースに必要な全 gate を発見できること。 - 1.0 の `CHANGELOG.md` が、ユーザが `felis --version` と `felis daemon status` の出力から「どの build がどの wire を喋るか」を判断できる情報を含むこと。 cc @natsukium

natsukium referenced this issue

2026-09-03 16:05:02 +09:00

[1.0 Review] リリース前設計レビュー — 親トラッキング（8件） #11

natsukium referenced this issue

2026-09-03 16:18:01 +09:00

[v0.1/P0] Define immutable build identity and offline version output #17

natsukium referenced this issue

2026-09-03 16:18:01 +09:00

[v0.1/P0] Add a tag-driven immutable release artifact gate #18

natsukium referenced this issue

2026-09-03 16:18:02 +09:00

[v0.1/P0] Make protobuf compatibility checks fail against the CI base #19

natsukium referenced this issue

2026-09-03 16:18:04 +09:00

[v0.1/P1] Simplify the CLI machine contract before freeze #23

natsukium referenced this issue

2026-09-03 16:18:08 +09:00

[v0.1/P1] Publish CLI and bridge JSON schemas with golden conversations #29

natsukium referenced this issue

2026-09-03 16:18:08 +09:00

[v0.1/P1] Reset the first public wire baseline to protocol 2.0 #30

natsukium commented

2026-09-03 16:19:13 +09:00

Author

Owner

Superseded by #17, #18, #19, #29, #30, and the final release task #31. #12 now separates identity, artifacts, compatibility, schemas, wire baseline, and exact-revision publication.