Count and prune instruction artifacts in status / build (#48)

#48 の PR-4a (観測まで)。status / doctor / prune を instruction 対応にする。

- status.generated_state: instruction (generated/<tool>/instructions/*) も total /
  stale に数える。鮮度は InstructionMarker の build_id を source content から再計算して
  比較する (mtime 非依存)。doctor は status 統合なので自動的に instruction を含む。
- build --prune: 対応する instruction asset が無い generated instruction を削除する
  (agent-tools marker を持つもののみ)。あわせて skill -> instruction 転換で残った
  stale skill directory もここで prune される (PR-1 で先送りした課題の解消)。
- status / build の self-test に instruction の generated カウント・stale・prune を追加。
- docs/instruction-artifact-kind.md の実装状況を更新。

injection の instruction strict と実 asset 投入は PR-4b。

Refs #48

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: kosako

docs/instruction-artifact-kind.md

@@ -90,6 +90,7 @@ connect / sync (所有判定) が同じ format を共有する。
   instruction 生成、ファイル内コメント marker (`scripts/lib/instruction_marker.rb`)、
   check-manifests の 1-per-target 検証、catalog の target-artifact 化と register の
   ビルド可能性証明、connect (`scripts/connect.sh`)、sync の instruction 配置
-  (catalog を source of truth として列挙)。
-- 後続: status / doctor / prune の instruction 対応、injection の instruction strict、
-  検証用の実 instruction asset 投入。
+  (catalog を source of truth として列挙)、status / doctor の instruction generated
+  カウントと鮮度判定、build --prune の instruction 対応。
+- 後続: injection の instruction strict (external URL を high に)、検証用の実
+  instruction asset 投入。

scripts/lib/build.rb

@@ -143,13 +143,22 @@ def rel(path)
     # marker のない directory は warning として返し、残す。
     def prune
       expected = Hash.new { |h, k| h[k] = [] }
+      instruction_expected = Hash.new(false)
       Assets.load_all(@root).each do |asset|
-        asset[:targets].each { |tool| expected[tool] << asset[:name] }
+        (asset[:targets] || []).each do |tool|
+          if ArtifactTargets.resolve(asset, tool) == "instruction"
+            instruction_expected[tool] = true
+          else
+            expected[tool] << asset[:name]
+          end
+        end
       end
 
       pruned = []
       kept = []
       TOOLS.each do |tool|
+        # skill: manifest に対応しない generated directory を削除する。
+        # (skill -> instruction 転換で残った stale skill もここで消える)
         Dir.glob(File.join(@root, "generated", tool, "skills", "*")).sort.each do |dir|
           next unless File.directory?(dir)
           next if expected[tool].include?(File.basename(dir))
@@ -161,6 +170,20 @@ def prune
             kept << rel(dir)
           end
         end
+
+        # instruction: その tool 向け instruction asset が無ければ generated を削除する。
+        next if instruction_expected[tool]
+
+        Dir.glob(File.join(@root, "generated", tool, "instructions", "*")).sort.each do |file|
+          next unless File.file?(file)
+
+          if InstructionMarker.parse(File.read(file))
+            FileUtils.rm_f(file)
+            pruned << rel(file)
+          else
+            kept << rel(file)
+          end
+        end
       end
       [pruned, kept]
     end

scripts/lib/status.rb

@@ -17,6 +17,7 @@
 require_relative "build"
 require_relative "sync"
 require_relative "artifact_targets"
+require_relative "instruction_marker"
 
 module Status
   CONTRACT_VERSION = 2
@@ -72,6 +73,7 @@ def injection_outcome(findings)
     end
 
     # generated artifacts の数と、source より古い (build_id 不一致) artifact の数。
+    # skill (directory) と instruction (単一ファイル) の両方を数える。
     def generated_state
       sources = Assets.sources_by_name(@root)
       total = 0
@@ -83,6 +85,12 @@ def generated_state
           total += 1
           stale += 1 unless fresh?(artifact, sources)
         end
+        Dir.glob(File.join(@root, "generated", tool, "instructions", "*")).sort.each do |artifact|
+          next unless File.file?(artifact)
+
+          total += 1
+          stale += 1 unless fresh_instruction?(artifact, sources)
+        end
       end
       [total, stale]
     end
@@ -102,6 +110,17 @@ def fresh?(artifact, sources)
       false
     end
 
+    # instruction (ファイル内コメント marker) の鮮度判定。
+    def fresh_instruction?(path, sources)
+      marker = InstructionMarker.parse(File.read(path))
+      return false unless marker
+
+      source = sources[marker["name"]]
+      return false unless source
+
+      marker["build_id"] == Build.build_id_for(@root, source["path"], source["format"])
+    end
+
     # catalog (docs/register-catalog.md) の register summary。
     def register_summary
       catalog_path = File.join(@root, "generated", "catalog.json")

scripts/tests/build-test.sh

@@ -238,6 +238,13 @@ grep -q "ドキュメントは日本語" "$claude_instr" \
 [ ! -d "$tmp/instr/generated/claude-code/skills" ] \
   || fail "instruction must not be generated as a skill"
 
+# --- case 4d: --prune は instruction asset が消えた generated も削除する ---
+rm "$tmp/instr/shared/instructions/personal-ops.md" "$tmp/instr/shared/instructions/personal-ops.asset.yml"
+"$build" --root "$tmp/instr" --prune > "$tmp/out-iprune" 2>&1 || fail "instruction prune should pass: $(cat "$tmp/out-iprune")"
+grep -q "pruned: generated/codex/instructions/AGENTS.md" "$tmp/out-iprune" || fail "instruction not pruned: $(cat "$tmp/out-iprune")"
+[ ! -e "$tmp/instr/generated/codex/instructions/AGENTS.md" ] || fail "orphan instruction should be removed"
+[ ! -e "$tmp/instr/generated/claude-code/instructions/CLAUDE.md" ] || fail "orphan claude instruction should be removed"
+
 # --- case 5: repository 本体が build できる ---
 repo_root=$(CDPATH= cd -- "$script_dir/../.." && pwd)
 "$build" --root "$repo_root" --quiet > "$tmp/out-repo" 2>&1 \

scripts/tests/status-test.sh

@@ -129,4 +129,33 @@ repo_root=$(CDPATH= cd -- "$script_dir/../.." && pwd)
 "$status_sh" --root "$repo_root" --json > "$tmp/s9" 2>&1 || fail "repo status should succeed"
 [ "$(jget "$tmp/s9" repo present)" = "true" ] || fail "repo.present should be true"
 
+# --- case 10: instruction の generated も generated.total に数える ---
+mkdir -p "$tmp/irepo/shared/instructions" "$tmp/icodex" "$tmp/iclaude"
+cat > "$tmp/irepo/shared/instructions/personal-ops.md" <<'EOF'
+# ops
+EOF
+cat > "$tmp/irepo/shared/instructions/personal-ops.asset.yml" <<'EOF'
+schema_version: 1
+name: personal-ops
+kind: instruction
+visibility: public
+targets:
+  - codex
+  - claude-code
+risk:
+  prompt_injection: low
+  privacy: low
+source:
+  path: shared/instructions/personal-ops.md
+  format: markdown
+EOF
+"$build" --root "$tmp/irepo" --quiet > /dev/null
+"$status_sh" --root "$tmp/irepo" --codex-home "$tmp/icodex" --claude-home "$tmp/iclaude" --json > "$tmp/is10" 2>&1
+[ "$(jget "$tmp/is10" generated total)" = "2" ] || fail "instruction generated should count (2 targets): $(cat "$tmp/is10")"
+[ "$(jget "$tmp/is10" generated stale)" = "0" ] || fail "fresh instruction should not be stale"
+# source 変更で instruction も stale になる
+echo "changed" >> "$tmp/irepo/shared/instructions/personal-ops.md"
+"$status_sh" --root "$tmp/irepo" --codex-home "$tmp/icodex" --claude-home "$tmp/iclaude" --json > "$tmp/is10b" 2>&1
+[ "$(jget "$tmp/is10b" generated stale)" = "2" ] || fail "changed instruction source should be stale: $(cat "$tmp/is10b")"
+
 echo "ok: status self-test passed"