@papillon6814/pi-gh 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Papillon6814
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,135 @@
-# Temporary Holding Version
+# pi-gh
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+PiからGitHubを操作するTypeScript製の基盤拡張です。個別ツールを別のPi拡張から組み合わせられます。Scaffoldの工程・ウェーブ・専用テンプレートやHerdr操作は、利用側の拡張が担当します。MIT。CLIのbinは提供しません。既存gh-issueflowを削除・変更する必要はありません。
+
+## 要件と導入
+- Node.js >=22.19.0、Pi 1.0.4、認証済みGitHub CLI gh。実機検証はmacOS。
+- 認証情報・tokenをpi-ghへ渡す設定はありません。Projectsには対象Projectへのアクセスと`project`相当の権限が必要です。権限不足時は停止し、自動再認証しません。
+- 新機能を含むnpm版：`pi install npm:@papillon6814/pi-gh@0.2.0`。
+- Developmentだけで使う場合：`pi-profile packages add --profile developer npm:@papillon6814/pi-gh@0.2.0 --replace`、`pi-profile packages install --profile developer`。共通settingsへは追加しません。
+- Profileの割り当て変更後はPiを再起動してください。起動済みプロセスは元のsource指定を保持するため、`/reload`だけでは新しい版の指定へ切り替わりません。
+- ソース利用は`npm install --ignore-scripts && npm run build`後、`pi -e /absolute/path/to/pi-gh`。
+- Piホスト提供APIはpeerで、本体を配布へ含めません。
+
+## 個別ツール（契約バージョン1）
+
+すべての結果に`outputSchema`とマスク済み`structuredContent`があります。対応版・機能は`gh_capabilities`で確認してください。変更ツールも`direct`で登録され、Piの通常のツール検証・hooksを経由して呼べます。
+
+| 名前 | 入力 | 動作 |
+|---|---|---|
+| gh_capabilities | `{}` | contractVersionと対応操作。remoteアクセスなし |
+| gh_issue_validate | draftPath、template/templatePath | オフラインの構造・モデルpolicy検証 |
+| gh_issue_preview | 同上 | 投稿内容・digest。ラベル付きはremote確認 |
+| gh_issue_submit | 同上 | 検証・許可・再確認を経てIssue作成 |
+| gh_labels_validate | changePath | ラベル変更案のオフライン検証 |
+| gh_labels_preview | changePath | 対象・before/after・影響対象・digest |
+| gh_labels_apply | changePath | 検証・許可・再確認を経てラベル変更 |
+| gh_issue_form | template/templatePath | Issue Form YAMLを返す。ファイル上書きなし |
+| gh_issue_get | repo、issue | 指定Issueを取得。PRは拒否 |
+| gh_issue_list | repo、任意state | Issue一覧。stateはopen/closed/all（既定all）。PRは除外 |
+| gh_issue_edit | changePath | 既存Issueのtitle/body更新 |
+| gh_issue_close | changePath | 既存Issueをclose |
+| gh_subissues_list | repo、issue | native子Issue一覧 |
+| gh_subissue_add | changePath | native親子関係の追加 |
+| gh_dependencies_list | repo、issue | 指定Issueのblocked_by一覧 |
+| gh_dependency_add | changePath | 指定Issueをブロックする先行Issueを追加 |
+| gh_project_get | projectId | Projects V2のtitle・field一覧 |
+| gh_project_items | projectId | Projectの項目・field値一覧 |
+| gh_project_add_issue | changePath | 指定IssueをProjectへ登録 |
+| gh_project_field_update | changePath | text/number/date/single-select field値更新 |
+
+パスは実行時cwd基準。標準templateはtask（既定）/parent。独自templatePathと同時指定できません。Epic/Feature/Task専用テンプレートは利用側で用意します。examplesのexample/demoは架空です。
+
+## 別拡張からの呼び出し
+
+利用側は、pi-ghのロードと必要ツールの存在を確認し、不在・版不一致では停止してください。内部`dist/src/*`の直接importは公開SDK契約ではありません。
+
+```typescript
+// 利用側ツールのexecute内。信頼済みpi-ghが同じPiにロードされている前提。
+const capabilities = await ctx.executeTool("gh_capabilities", {});
+if (capabilities.isError) throw new Error("pi-gh unavailable");
+const info = capabilities.result.structuredContent as {
+  data?: { contractVersion?: number; operations?: string[] };
+};
+if (info.data?.contractVersion !== 1 ||
+    !info.data.operations?.includes("gh_issue_get")) {
+  throw new Error("Unsupported pi-gh contract");
+}
+const nested = await ctx.executeTool("gh_issue_get", {
+  repo: "example/demo", issue: 10,
+}, { signal });
+return { ...nested.result, isError: nested.isError };
+```
+
+`ctx.executeTool()`の戻り値は結果そのものではなく`{ result, isError, toolCall }`です。結果をモデルへ返すのは呼び出し側の責務です。Piはネスト呼び出しをhooksへ通します。機能照会は登録が正しいことの保証ではないため、ロードする拡張は信頼済みのものに限ってください。
+
+## 変更JSON
+
+新規Issue・ラベル変更は従来の入力を維持します。新しい変更ツールは`{ changePath: "change.json" }`を受け、以下のJSONを読みます。未知・重複キーやツールとoperationの不一致は拒否します。
+
+| operation | 必須フィールド（version:1、repo以外） | 任意フィールド |
+|---|---|---|
+| issue-edit | issue、title/bodyの少なくとも一方 | — |
+| issue-close | issue | reason: completed（既定）/not_planned |
+| subissue-add | issue（親）、relatedIssue（子） | — |
+| dependency-add | issue（後続）、relatedIssue（先行） | — |
+| project-add-issue | issue、projectId | — |
+| project-field-update | projectId、itemId、fieldId、value | — |
+
+```json
+{"version":1,"repo":"example/demo","operation":"issue-edit","issue":10,"title":"Updated","body":"Revised specification"}
+```
+
+```json
+{"version":1,"repo":"example/demo","operation":"project-field-update","projectId":"PVT_example","itemId":"PVTI_example","fieldId":"PVTSSF_example","value":{"singleSelectOptionId":"option_done"}}
+```
+
+valueは`text`、有限の`number`、実在するISO日付`date`、`singleSelectOptionId`のうち1つ。fieldの種類、Project所属、option所属、項目のIssue/repo所属を照合します。親子・依存追加は同一repo内のみ、自己参照は禁止。入力のIssue番号をGitHubのdatabase ID/node IDへ解決します。従来の`parentIssue`は本文リンクであり、native親子関係は`gh_subissue_add`で別途設定します。
+
+## 人間承認と自動実行許可
+
+既定は従来と同じローカルTUI承認です。全文を読んでApproveを明示選択してください。既定Cancel、Escape/Ctrl-Cは取消。RPC・print/JSON・子エージェントは、対応するローカル許可がなければ変更を拒否します。`approved`フラグやdigestをAIが渡して承認する入口はありません。
+
+所有者が`~/.pi/agent/pi-gh-permissions.json`を配置した場合だけ、許可範囲内の操作を自動実行できます。PiのagentDir/Profileの設定とは独立した、HOME配下の固定パスです。リポジトリ内の設定は許可として読みません。
+
+```json
+{
+  "version": 1,
+  "grants": [{
+    "repo": "example/demo",
+    "operations": ["gh_issue_edit", "gh_issue_close", "gh_project_field_update"],
+    "allowHeadless": true,
+    "allowChild": true,
+    "projectIds": ["PVT_example"]
+  }]
+}
+```
+
+- ファイルは現在のOSユーザー所有・mode 0600以下のregular file。ファイルと親ディレクトリのsymlinkは拒否します。未配置は通常の承認経路へ戻ります。壊れたJSON・権限不備は停止します。
+- repo・operationは完全指定。ワイルドカード不可。Project変更にはprojectIdsの完全一致も必要です。
+- 子にはallowChild、UIのない実行にはallowHeadlessがそれぞれ必要です。省略はfalse。
+- 許可できる操作：`gh_issue_submit`、新しい変更ツール6種、`gh_label_create`、`gh_label_edit`、`gh_issue_labels`。最後の3種は`gh_labels_apply`の操作別許可名です。ラベル削除は自動許可できません。
+- 許可ファイルの内容・inode・modeを固定し、変更前とghプロセス起動直前に再照合します。取り消された許可は再利用しません。許可ファイルは自動生成・変更しません。
+- 許可はこのツール群の境界です。任意のshell/ファイル編集権限を持つAIや同じOSユーザーの悪意あるプロセスを隔離するサンドボックスではありません。
+
+## 安全境界と制限
+
+入力bytes・template・モデルpolicy・関連remote状態を固定し、承認後に再検査します。会話切り替え・tree移動・reload/shutdown・取消で保留中の処理は失効します。変更は同一拡張runtime内で直列化します。別Piプロセス間のロックやGitHub側のatomic compare-and-swapは提供しません。同じ対象の並行編集は避けてください。
+
+秘密検出はヒューリスティックです。decoded文字列・object key・remote metadataもマスクし、秘密候補があれば変更を拒否します。秘密漏洩ゼロ、直接gh実行の防止、チェックと実write間の全競合防止は保証しません。
+
+ghはshellなし・固定argv/stdin・github.com固定。RESTは明示methodとAPI version 2026-03-10、GraphQLは固定queryとJSON variablesを使い、任意endpoint/query入力はありません。各プロセス60秒、各stdio1MiB、cleanup猶予100ms。POSIX所有process groupを停止しますが、Windowsの子孫全体停止は保証しません。新規read操作は最大100ページ・合計1MiB、反復cursor・field値の切り捨てを拒否します。
+
+結果はread/validated/preview/generated/created/applied/noop/rejected/not-started/unknown。`unknown`は変更済みの可能性があります。GitHubを確認するまで再実行しないでください。自動再試行・自動取消はありません。新変更操作は要求した状態を事後確認し、不一致・確認失敗はunknownにします。
+
+Issue用YAMLはfieldsのrequired/options/順序/制限とmodels policyを正本にします。従来の上位tierにはupperTierApprovalが必要ですが、その文字列だけで真正な課金承認は証明できません。テンプレートと利用可能なモデルは別問題です。
+
+対象外：assignee変更、コメント投稿、クロスrepo親子・依存、関係解除、Project作成/削除/field定義/view変更、iteration等のfield更新、一括write、Herdr/Scaffoldの工程判断。
+
+## 開発・検証
+
+`npm run build`、`npm run typecheck`、`npm test`。
+`python3 scripts/test-pi-gh-cli.py --pi /absolute/path/to/pi`は合成HOME・偽gh・loopbackモデルで実PiのTUI/RPC/print・ネスト呼び出し・許可付き子実行・hooksを検証します。実アカウントや実GitHubへの試験投稿はしません。GitHubのライブ変更互換性は未実測です。
+`npm pack`にはentry、compiled core、templates、架空examples、README、LICENSEだけを含め、docs/test/認証は含めません。
+
+GitHub API参照：[sub-issues](https://docs.github.com/en/rest/issues/sub-issues)、[dependencies](https://docs.github.com/en/rest/issues/issue-dependencies)、[Projects V2](https://docs.github.com/en/issues/planning-and-tracking-with-projects/automating-your-project/using-the-api-to-manage-projects)。

package/dist/src/core/approval.d.ts

@@ -0,0 +1,2 @@
+import type { Preview, ValidatedIssue } from './types.js';
+export declare function createPreview(issue: ValidatedIssue): Preview;

package/dist/src/core/approval.js

@@ -0,0 +1,25 @@
+import { createHash } from 'node:crypto';
+import { renderIssue } from './render.js';
+import { maskSecrets } from './secrets.js';
+function canonical(value) {
+    if (Array.isArray(value))
+        return '[' + value.map(canonical).join(',') + ']';
+    if (typeof value === 'object' && value !== null)
+        return '{' + Object.entries(value).filter(([, v]) => v !== undefined).sort(([a], [b]) => a.localeCompare(b, 'en')).map(([k, v]) => JSON.stringify(k) + ':' + canonical(v)).join(',') + '}';
+    return JSON.stringify(value);
+}
+export function createPreview(issue) {
+    const rendered = renderIssue(issue);
+    const sha = (bytes) => createHash('sha256').update(bytes).digest('hex');
+    const digest = sha(canonical({ formatVersion: 1, host: 'github.com', ...rendered, agents: issue.draft.agents, inputs: [issue.draftInput, ...issue.bundle.inputs].map(i => ({ path: i.path, sha256: sha(i.bytes) })) }));
+    let sensitive = false;
+    const mask = (v) => { const m = maskSecrets(v); sensitive ||= m.sensitive; return m.text; };
+    for (const i of [issue.draftInput, ...issue.bundle.inputs])
+        mask(i.bytes.toString('utf8'));
+    const agents = {};
+    for (const [name, a] of Object.entries(issue.draft.agents))
+        agents[mask(name)] = { model: mask(a.model), thinking: mask(a.thinking), reason: mask(a.reason), ...(a.upperTierApproval === undefined ? {} : { upperTierApproval: mask(a.upperTierApproval) }) };
+    const title = mask(rendered.title), body = mask(rendered.body), repo = mask(rendered.repo);
+    const labels = issue.draft.labels?.map(mask);
+    return { repo, title, body, agents, digest, sensitive, ...(labels === undefined ? {} : { labels }) };
+}

package/dist/src/core/data.d.ts

@@ -0,0 +1,19 @@
+import type { CapturedInput } from './types.js';
+export type ParsedData = null | boolean | number | string | ParsedData[] | {
+    [key: string]: ParsedData;
+};
+export declare const MAX_BYTES = 1048576;
+export declare class DataError extends Error {
+    readonly code: string;
+    readonly field: string;
+    constructor(code: string, field: string, message: string);
+}
+export declare function fail(code: string, field: string, message: string): never;
+export declare function record(value: unknown): value is Record<string, unknown>;
+export declare function keys(value: Record<string, unknown>, allowed: readonly string[], field: string): void;
+export declare function nonblank(value: unknown): value is string;
+export declare function validId(value: unknown): value is string;
+export declare function capture(file: string, allowedRoot?: string): Promise<CapturedInput>;
+export declare function text(bytes: Buffer): string;
+export declare function parseYaml(bytes: Buffer): ParsedData;
+export declare function parseJson(bytes: Buffer): ParsedData;

package/dist/src/core/data.js

@@ -0,0 +1,136 @@
+import { open, realpath, stat as pathStat } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { resolve, relative, isAbsolute, sep } from 'node:path';
+import { parseAllDocuments, isAlias, isMap, isSeq } from 'yaml';
+export const MAX_BYTES = 1048576;
+export class DataError extends Error {
+    code;
+    field;
+    constructor(code, field, message) {
+        super(message);
+        this.code = code;
+        this.field = field;
+        this.name = 'DataError';
+    }
+}
+export function fail(code, field, message) { throw new DataError(code, field, message); }
+export function record(value) { return typeof value === 'object' && value !== null && !Array.isArray(value); }
+export function keys(value, allowed, field) {
+    for (const k of Object.keys(value))
+        if (!allowed.includes(k))
+            fail('UNKNOWN_KEY', field, 'Unknown property.');
+}
+export function nonblank(value) { return typeof value === 'string' && value.trim().length > 0; }
+export function validId(value) { return typeof value === 'string' && /^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/.test(value) && !['constructor', 'prototype', '__proto__'].includes(value); }
+export async function capture(file, allowedRoot) {
+    let handle;
+    try {
+        const path = await realpath(resolve(file));
+        const contained = (candidate) => {
+            if (!allowedRoot)
+                return;
+            const rel = relative(allowedRoot, candidate);
+            if (!rel || rel === '..' || rel.startsWith('..' + sep) || isAbsolute(rel))
+                fail('POLICY_OUTSIDE', '', 'Policy resolves outside template directory.');
+        };
+        contained(path);
+        handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const before = await handle.stat();
+        if (!before.isFile())
+            fail('INPUT_TYPE', '', 'Input must be a regular file.');
+        if (before.size > MAX_BYTES)
+            fail('INPUT_LIMIT', '', 'Input exceeds 1 MiB.');
+        const verifyLocation = async () => {
+            if (allowedRoot && await realpath(allowedRoot) !== allowedRoot)
+                fail('INPUT_CHANGED', '', 'Template root changed during capture.');
+            const currentPath = await realpath(resolve(file));
+            contained(currentPath);
+            if (currentPath !== path)
+                fail('INPUT_CHANGED', '', 'Input location changed during capture.');
+            const current = await pathStat(currentPath);
+            if (current.dev !== before.dev || current.ino !== before.ino)
+                fail('INPUT_CHANGED', '', 'Input identity changed during capture.');
+        };
+        await verifyLocation(); // Validate the opened descriptor before reading bytes.
+        const bytes = Buffer.alloc(MAX_BYTES + 1);
+        let length = 0;
+        while (length < bytes.length) {
+            const part = await handle.read(bytes, length, bytes.length - length, null);
+            if (!part.bytesRead)
+                break;
+            length += part.bytesRead;
+        }
+        if (length > MAX_BYTES)
+            fail('INPUT_LIMIT', '', 'Input exceeds 1 MiB.');
+        await verifyLocation();
+        const after = await handle.stat();
+        if (before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs)
+            fail('INPUT_CHANGED', '', 'Input changed during capture.');
+        return { path, bytes: Buffer.from(bytes.subarray(0, length)) };
+    }
+    catch (e) {
+        if (e instanceof DataError)
+            throw e;
+        return fail('INPUT_READ', '', 'Unable to read input file.');
+    }
+    finally {
+        await handle?.close();
+    }
+}
+export function text(bytes) {
+    if (bytes.length > MAX_BYTES)
+        fail('INPUT_LIMIT', '', 'Input exceeds 1 MiB.');
+    try {
+        return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    }
+    catch {
+        fail('ENCODING', '', 'Input must be UTF-8.');
+    }
+}
+export function parseYaml(bytes) {
+    try {
+        const docs = parseAllDocuments(text(bytes), { uniqueKeys: true, prettyErrors: false, strict: true });
+        if (docs.length !== 1)
+            fail('YAML_DOCUMENT', '', 'Exactly one YAML document is required.');
+        const doc = docs[0];
+        if (doc.errors.length || doc.warnings.length)
+            fail('YAML_INVALID', '', 'Invalid YAML or duplicate keys.');
+        const stack = [{ node: doc.contents, depth: 0 }];
+        const tags = new Set(['tag:yaml.org,2002:str', 'tag:yaml.org,2002:int', 'tag:yaml.org,2002:float', 'tag:yaml.org,2002:bool', 'tag:yaml.org,2002:null', 'tag:yaml.org,2002:map', 'tag:yaml.org,2002:seq']);
+        while (stack.length) {
+            const { node, depth } = stack.pop();
+            if (depth > 32)
+                fail('INPUT_DEPTH', '', 'Input nesting exceeds 32.');
+            if (isAlias(node))
+                fail('YAML_ALIAS', '', 'YAML aliases are not supported.');
+            if (record(node) && typeof node.tag === 'string' && !tags.has(node.tag))
+                fail('YAML_TAG', '', 'Custom YAML tags are not supported.');
+            if (isMap(node))
+                for (const pair of node.items) {
+                    stack.push({ node: pair.key, depth: depth + 1 }, { node: pair.value, depth: depth + 1 });
+                }
+            else if (isSeq(node))
+                for (const item of node.items)
+                    stack.push({ node: item, depth: depth + 1 });
+        }
+        return doc.toJS({ maxAliasCount: 0 });
+    }
+    catch (e) {
+        if (e instanceof DataError)
+            throw e;
+        fail('YAML_INVALID', '', 'Invalid YAML.');
+    }
+}
+export function parseJson(bytes) {
+    try {
+        const raw = text(bytes);
+        const value = JSON.parse(raw);
+        parseYaml(bytes); // JSON syntax is a YAML subset; detect decoded duplicate keys.
+        return value;
+    }
+    catch (e) {
+        if (e instanceof DataError)
+            throw e;
+        fail('JSON_INVALID', '', 'Invalid JSON.');
+    }
+}

package/dist/src/core/draft.d.ts

@@ -0,0 +1,6 @@
+import type { CapturedInput, TemplateBundle, ValidatedIssue, ValidationProblem } from './types.js';
+export declare function loadDraft(path: string): Promise<CapturedInput>;
+export declare function validateDraft(input: CapturedInput, bundle: TemplateBundle): {
+    issue?: ValidatedIssue;
+    problems: ValidationProblem[];
+};

package/dist/src/core/draft.js

@@ -0,0 +1,92 @@
+import { capture, parseJson, record, keys, nonblank, fail, DataError } from './data.js';
+import { validateLabelNames } from './labels-input.js';
+export async function loadDraft(path) { return capture(path); }
+function string(value, f, path) {
+    if (!nonblank(value))
+        fail('FIELD_REQUIRED', path, 'Expected nonblank text.');
+    if (f.type === 'string' && /[\r\n]/.test(value))
+        fail('FIELD_SINGLE_LINE', path, 'Expected a single line.');
+    const n = Array.from(value).length;
+    if ((f.minLength !== undefined && n < f.minLength) || (f.maxLength !== undefined && n > f.maxLength))
+        fail('FIELD_LENGTH', path, 'Text length is outside allowed range.');
+    if (f.options && !f.options.includes(value))
+        fail('FIELD_OPTION', path, 'Value is not an allowed option.');
+}
+function field(value, f) {
+    if (['string', 'text'].includes(f.type)) {
+        string(value, f, 'fields.' + f.id);
+        return;
+    }
+    if (!Array.isArray(value) || (f.required && !value.length) || (f.minItems !== undefined && value.length < f.minItems) || (f.maxItems !== undefined && value.length > f.maxItems))
+        fail('FIELD_ITEMS', 'fields.' + f.id, 'Invalid list size or type.');
+    if (f.type === 'string-list') {
+        for (const v of value)
+            string(v, { ...f, type: 'text' }, 'fields.' + f.id);
+        return;
+    }
+    const seen = new Set();
+    for (const v of value) {
+        if (!record(v))
+            fail('CRITERION_INVALID', 'fields.' + f.id, 'Criterion must be an object.');
+        keys(v, ['id', 'requirement', 'verification', 'expectedResult'], 'fields.' + f.id);
+        for (const k of ['id', 'requirement', 'verification', 'expectedResult'])
+            if (!nonblank(v[k]))
+                fail('CRITERION_REQUIRED', 'fields.' + f.id, 'All criterion attributes are required.');
+        const id = v.id;
+        if (seen.has(id))
+            fail('CRITERION_DUPLICATE', 'fields.' + f.id, 'Duplicate criterion ID.');
+        seen.add(id);
+    }
+}
+export function validateDraft(input, bundle) {
+    try {
+        const value = parseJson(input.bytes);
+        const t = bundle.template;
+        if (!record(value))
+            fail('DRAFT_TYPE', '', 'Draft must be an object.');
+        keys(value, ['version', 'template', 'repo', 'title', 'parentIssue', 'labels', 'fields', 'agents'], 'draft');
+        if (value.version !== 1 || value.template !== t.id)
+            fail('DRAFT_TEMPLATE', 'template', 'Draft template does not match.');
+        if (typeof value.repo !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9-]{0,99}\/[a-zA-Z0-9_.][a-zA-Z0-9_.-]{0,99}$/.test(value.repo) || value.repo.endsWith('/.') || value.repo.endsWith('/..'))
+            fail('DRAFT_REPO', 'repo', 'Expected OWNER/REPO.');
+        if (!nonblank(value.title) || /[\r\n\u0000-\u001f\u007f]/.test(value.title) || Array.from(value.title).length > 256)
+            fail('DRAFT_TITLE', 'title', 'Expected a nonblank single-line title up to 256 characters.');
+        if (value.labels !== undefined)
+            validateLabelNames(value.labels);
+        if (t.kind === 'task' && (!Number.isSafeInteger(value.parentIssue) || value.parentIssue < 1))
+            fail('DRAFT_PARENT', 'parentIssue', 'A positive parent issue is required.');
+        if (t.kind === 'parent' && value.parentIssue !== undefined)
+            fail('DRAFT_PARENT', 'parentIssue', 'Parent issue must not specify a parent.');
+        if (!record(value.fields))
+            fail('DRAFT_FIELDS', 'fields', 'Fields must be an object.');
+        keys(value.fields, t.fields.map(f => f.id), 'fields');
+        for (const f of t.fields) {
+            const present = Object.hasOwn(value.fields, f.id);
+            if (!present && !f.required)
+                continue;
+            field(present ? value.fields[f.id] : undefined, f);
+        }
+        if (!record(value.agents))
+            fail('DRAFT_AGENTS', 'agents', 'Agents must be an object.');
+        keys(value.agents, t.agents, 'agents');
+        for (const agent of t.agents) {
+            const a = Object.hasOwn(value.agents, agent) ? value.agents[agent] : undefined;
+            if (!record(a))
+                fail('AGENT_REQUIRED', 'agents.' + agent, 'Agent assignment is required.');
+            keys(a, ['model', 'thinking', 'reason', 'upperTierApproval'], 'agents.' + agent);
+            if (!nonblank(a.model) || !nonblank(a.thinking) || !nonblank(a.reason))
+                fail('AGENT_REQUIRED', 'agents.' + agent, 'Model, thinking and reason are required.');
+            const profile = bundle.policy.agents[agent]?.find(p => p.model === a.model && p.thinking === a.thinking);
+            if (!profile)
+                fail('AGENT_PROFILE', 'agents.' + agent, 'Model/thinking combination is not allowed for this agent.');
+            if (profile.tier === 'upper' && !nonblank(a.upperTierApproval))
+                fail('AGENT_APPROVAL', 'agents.' + agent, 'Upper profile requires an approval record.');
+            if (a.upperTierApproval !== undefined && !nonblank(a.upperTierApproval))
+                fail('AGENT_APPROVAL', 'agents.' + agent, 'Approval record must be nonblank.');
+        }
+        return { issue: { draft: value, bundle, draftInput: input }, problems: [] };
+    }
+    catch (e) {
+        return { problems: [e instanceof DataError ? { code: e.code, path: e.field, message: e.message } : { code: 'INPUT_INVALID', path: '', message: 'Invalid input.' }] };
+    }
+}

package/dist/src/core/forms.d.ts

@@ -0,0 +1,3 @@
+import type { TemplateBundle } from './types.js';
+export declare function renderForm(bundle: TemplateBundle): string;
+export declare function writeForm(path: string, content: string, overwrite?: boolean): Promise<void>;

package/dist/src/core/forms.js

@@ -0,0 +1,54 @@
+import { stringify } from 'yaml';
+import { open } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { fail, DataError } from './data.js';
+export function renderForm(bundle) {
+    const { template: t, policy: p } = bundle, body = [{ type: 'markdown', attributes: { value: 'このフォームは共通YAMLから生成されています。CLIの全検査（担当別の条件・上位承認等）をGitHub上で強制するものではありません。モデル利用承認と投稿承認を別途確認してください。' } }];
+    const ids = new Set();
+    const add = (f) => {
+        if (f.id) {
+            if (ids.has(f.id))
+                fail('FORM_ID_COLLISION', '', 'Generated form IDs collide.');
+            ids.add(f.id);
+        }
+        body.push(f);
+    };
+    if (t.kind === 'task')
+        add({ type: 'input', id: 'parent-issue', attributes: { label: '親Issue', description: '同じrepositoryの親Issue番号' }, validations: { required: true } });
+    for (const f of t.fields) {
+        const id = 'field-' + f.id.toLowerCase();
+        let type = f.type === 'string' ? 'input' : 'textarea';
+        if (f.options)
+            type = 'dropdown';
+        add({ type, id, attributes: { label: f.label, ...(f.description ? { description: f.description } : {}), ...(f.options ? { options: f.options, ...(f.type === 'string-list' ? { multiple: true } : {}) } : {}),
+                ...(!f.options && ['string-list', 'criteria'].includes(f.type) ? { description: (f.description ?? '') + '\nJSON配列で入力してください。criteriaの各要素: id, requirement, verification, expectedResult。' } : {}) }, validations: { required: f.required } });
+    }
+    for (const agent of t.agents) {
+        const prefix = 'agent-' + agent.toLowerCase(), profiles = p.agents[agent];
+        add({ type: 'dropdown', id: prefix + '-profile', attributes: { label: agent + ' モデル / thinking', options: profiles.map(x => x.model + ' / ' + x.thinking + ' (' + x.tier + ')') }, validations: { required: true } });
+        add({ type: 'textarea', id: prefix + '-reason', attributes: { label: agent + ' 選定理由' }, validations: { required: true } });
+        if (profiles.some(x => x.tier === 'upper'))
+            add({ type: 'textarea', id: prefix + '-approval', attributes: { label: agent + ' 上位利用の承認記録', description: 'upperを選ぶ場合はユーザー承認の参照・説明が必要。basicの場合は不要。' }, validations: { required: false } });
+    }
+    return stringify({ name: t.name, description: t.description, body });
+}
+export async function writeForm(path, content, overwrite = false) {
+    let handle;
+    try {
+        handle = await open(path, overwrite ? constants.O_WRONLY | constants.O_CREAT | constants.O_NOFOLLOW : constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+        if (!(await handle.stat()).isFile())
+            fail('OUTPUT_TYPE', '', 'Output must be a regular file.');
+        if (overwrite)
+            await handle.truncate(0);
+        await handle.writeFile(content, 'utf8');
+        await handle.sync();
+    }
+    catch (e) {
+        if (e instanceof DataError)
+            throw e;
+        fail('OUTPUT_WRITE', '', 'Cannot write output; existing files need --overwrite and symlinks are refused.');
+    }
+    finally {
+        await handle?.close();
+    }
+}

package/dist/src/core/gh-process.d.ts

@@ -0,0 +1,14 @@
+export type GhOptions = {
+    ghExecutable?: string;
+    timeoutMs?: number;
+    maxOutputBytes?: number;
+    env?: NodeJS.ProcessEnv;
+    signal?: AbortSignal;
+    beforeStart?: () => boolean;
+    beforeStartAsync?: () => Promise<boolean>;
+};
+export type GhResult = {
+    status: 'ok' | 'not-started' | 'unknown';
+    stdout: string;
+};
+export declare function runGh(args: string[], body: string, options?: GhOptions): Promise<GhResult>;

package/dist/src/core/gh-process.js

@@ -0,0 +1,62 @@
+import { spawn } from 'node:child_process';
+export async function runGh(args, body, options = {}) {
+    const timeout = options.timeoutMs ?? 60000, max = options.maxOutputBytes ?? 1048576;
+    if (!Number.isSafeInteger(timeout) || timeout < 1 || timeout > 60000 || !Number.isSafeInteger(max) || max < 1 || max > 1048576 || Buffer.byteLength(body) > 1048576)
+        return Promise.resolve({ status: 'not-started', stdout: '' });
+    try {
+        if (options.beforeStartAsync && !await options.beforeStartAsync())
+            return { status: 'not-started', stdout: '' };
+    }
+    catch {
+        return { status: 'not-started', stdout: '' };
+    }
+    return new Promise(resolve => {
+        const group = process.platform !== 'win32';
+        let child;
+        try {
+            if (options.signal?.aborted || options.beforeStart?.() === false || options.signal?.aborted)
+                return resolve({ status: 'not-started', stdout: '' });
+            child = spawn(options.ghExecutable ?? 'gh', args, { shell: false, detached: group, env: { ...process.env, ...options.env, GH_HOST: 'github.com' }, stdio: ['pipe', 'pipe', 'pipe'] });
+        }
+        catch {
+            return resolve({ status: 'not-started', stdout: '' });
+        }
+        let started = false, failed = false, settled = false, stopping = false, stdoutBytes = 0, stderrBytes = 0;
+        const chunks = [];
+        let cleanup;
+        const signal = (kind) => { try {
+            if (group && child.pid)
+                process.kill(-child.pid, kind);
+            else
+                child.kill(kind);
+        }
+        catch { /* Owned process already gone. */ } };
+        const finish = (status) => { if (settled)
+            return; settled = true; clearTimeout(timer); if (cleanup)
+            clearTimeout(cleanup); options.signal?.removeEventListener('abort', abort); if (stopping && started)
+            signal('SIGKILL'); child.stdin.destroy(); child.stdout.destroy(); child.stderr.destroy(); resolve({ status, stdout: Buffer.concat(chunks).toString('utf8') }); };
+        const abort = () => { if (settled || stopping)
+            return; stopping = true; failed = true; if (started)
+            signal('SIGTERM'); cleanup = setTimeout(() => { if (started)
+            signal('SIGKILL'); finish(started ? 'unknown' : 'not-started'); }, 100); };
+        const timer = setTimeout(abort, timeout);
+        child.once('spawn', () => { started = true; if (stopping)
+            signal('SIGTERM'); });
+        child.once('error', () => { failed = true; if (!started)
+            finish('not-started');
+        else
+            abort(); });
+        child.stdout.on('data', (b) => { stdoutBytes += b.length; if (stdoutBytes > max)
+            return abort(); chunks.push(b); });
+        child.stderr.on('data', (b) => { stderrBytes += b.length; if (stderrBytes > max)
+            abort(); });
+        child.stdin.on('error', abort);
+        child.stdout.on('error', abort);
+        child.stderr.on('error', abort);
+        child.once('close', (code, signal) => finish(!started ? 'not-started' : !failed && code === 0 && !signal ? 'ok' : 'unknown'));
+        options.signal?.addEventListener('abort', abort, { once: true });
+        if (options.signal?.aborted)
+            abort();
+        child.stdin.end(body);
+    });
+}

package/dist/src/core/issue-labels.d.ts

@@ -0,0 +1,9 @@
+import { GhClient, type Repository, type Label } from './labels-github.js';
+import type { Preview, ValidatedIssue, SubmitOutcome } from './types.js';
+import type { GhOptions } from './gh-process.js';
+export type IssueLabelPreview = Preview & {
+    labelState?: Label[];
+    repository?: Repository;
+};
+export declare function createIssuePreview(issue: ValidatedIssue, options?: GhOptions, client?: GhClient): Promise<IssueLabelPreview>;
+export declare function submitLabelledIssue(issue: ValidatedIssue, digest: string, options?: GhOptions): Promise<SubmitOutcome>;