jp_address_complement 0.1.0

data/.cursor/commands/speckit.tasks.md

@@ -0,0 +1,137 @@
+---
+description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts.
+handoffs: 
+  - label: Analyze For Consistency
+    agent: speckit.analyze
+    prompt: Run a project analysis for consistency
+    send: true
+  - label: Implement Project
+    agent: speckit.implement
+    prompt: Start the implementation in phases
+    send: true
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+1. **Setup**: Run `.specify/scripts/bash/check-prerequisites.sh --json` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. **Load design documents**: Read from FEATURE_DIR:
+   - **Required**: plan.md (tech stack, libraries, structure), spec.md (user stories with priorities)
+   - **Optional**: data-model.md (entities), contracts/ (interface contracts), research.md (decisions), quickstart.md (test scenarios)
+   - Note: Not all projects have all documents. Generate tasks based on what's available.
+
+3. **Execute task generation workflow**:
+   - Load plan.md and extract tech stack, libraries, project structure
+   - Load spec.md and extract user stories with their priorities (P1, P2, P3, etc.)
+   - If data-model.md exists: Extract entities and map to user stories
+   - If contracts/ exists: Map interface contracts to user stories
+   - If research.md exists: Extract decisions for setup tasks
+   - Generate tasks organized by user story (see Task Generation Rules below)
+   - Generate dependency graph showing user story completion order
+   - Create parallel execution examples per user story
+   - Validate task completeness (each user story has all needed tasks, independently testable)
+
+4. **Generate tasks.md**: Use `.specify/templates/tasks-template.md` as structure, fill with:
+   - Correct feature name from plan.md
+   - Phase 1: Setup tasks (project initialization)
+   - Phase 2: Foundational tasks (blocking prerequisites for all user stories)
+   - Phase 3+: One phase per user story (in priority order from spec.md)
+   - Each phase includes: story goal, independent test criteria, tests (if requested), implementation tasks
+   - Final Phase: Polish & cross-cutting concerns
+   - All tasks must follow the strict checklist format (see Task Generation Rules below)
+   - Clear file paths for each task
+   - Dependencies section showing story completion order
+   - Parallel execution examples per story
+   - Implementation strategy section (MVP first, incremental delivery)
+
+5. **Report**: Output path to generated tasks.md and summary:
+   - Total task count
+   - Task count per user story
+   - Parallel opportunities identified
+   - Independent test criteria for each story
+   - Suggested MVP scope (typically just User Story 1)
+   - Format validation: Confirm ALL tasks follow the checklist format (checkbox, ID, labels, file paths)
+
+Context for task generation: $ARGUMENTS
+
+The tasks.md should be immediately executable - each task must be specific enough that an LLM can complete it without additional context.
+
+## Task Generation Rules
+
+**CRITICAL**: Tasks MUST be organized by user story to enable independent implementation and testing.
+
+**Tests are OPTIONAL**: Only generate test tasks if explicitly requested in the feature specification or if user requests TDD approach.
+
+### Checklist Format (REQUIRED)
+
+Every task MUST strictly follow this format:
+
+```text
+- [ ] [TaskID] [P?] [Story?] Description with file path
+```
+
+**Format Components**:
+
+1. **Checkbox**: ALWAYS start with `- [ ]` (markdown checkbox)
+2. **Task ID**: Sequential number (T001, T002, T003...) in execution order
+3. **[P] marker**: Include ONLY if task is parallelizable (different files, no dependencies on incomplete tasks)
+4. **[Story] label**: REQUIRED for user story phase tasks only
+   - Format: [US1], [US2], [US3], etc. (maps to user stories from spec.md)
+   - Setup phase: NO story label
+   - Foundational phase: NO story label  
+   - User Story phases: MUST have story label
+   - Polish phase: NO story label
+5. **Description**: Clear action with exact file path
+
+**Examples**:
+
+- ✅ CORRECT: `- [ ] T001 Create project structure per implementation plan`
+- ✅ CORRECT: `- [ ] T005 [P] Implement authentication middleware in src/middleware/auth.py`
+- ✅ CORRECT: `- [ ] T012 [P] [US1] Create User model in src/models/user.py`
+- ✅ CORRECT: `- [ ] T014 [US1] Implement UserService in src/services/user_service.py`
+- ❌ WRONG: `- [ ] Create User model` (missing ID and Story label)
+- ❌ WRONG: `T001 [US1] Create model` (missing checkbox)
+- ❌ WRONG: `- [ ] [US1] Create User model` (missing Task ID)
+- ❌ WRONG: `- [ ] T001 [US1] Create model` (missing file path)
+
+### Task Organization
+
+1. **From User Stories (spec.md)** - PRIMARY ORGANIZATION:
+   - Each user story (P1, P2, P3...) gets its own phase
+   - Map all related components to their story:
+     - Models needed for that story
+     - Services needed for that story
+     - Interfaces/UI needed for that story
+     - If tests requested: Tests specific to that story
+   - Mark story dependencies (most stories should be independent)
+
+2. **From Contracts**:
+   - Map each interface contract → to the user story it serves
+   - If tests requested: Each interface contract → contract test task [P] before implementation in that story's phase
+
+3. **From Data Model**:
+   - Map each entity to the user story(ies) that need it
+   - If entity serves multiple stories: Put in earliest story or Setup phase
+   - Relationships → service layer tasks in appropriate story phase
+
+4. **From Setup/Infrastructure**:
+   - Shared infrastructure → Setup phase (Phase 1)
+   - Foundational/blocking tasks → Foundational phase (Phase 2)
+   - Story-specific setup → within that story's phase
+
+### Phase Structure
+
+- **Phase 1**: Setup (project initialization)
+- **Phase 2**: Foundational (blocking prerequisites - MUST complete before user stories)
+- **Phase 3+**: User Stories in priority order (P1, P2, P3...)
+  - Within each story: Tests (if requested) → Models → Services → Endpoints → Integration
+  - Each phase should be a complete, independently testable increment
+- **Final Phase**: Polish & Cross-Cutting Concerns

data/.cursor/commands/speckit.taskstoissues.md

@@ -0,0 +1,30 @@
+---
+description: Convert existing tasks into actionable, dependency-ordered GitHub issues for the feature based on available design artifacts.
+tools: ['github/github-mcp-server/issue_write']
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+1. Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+1. From the executed script, extract the path to **tasks**.
+1. Get the Git remote by running:
+
+```bash
+git config --get remote.origin.url
+```
+
+> [!CAUTION]
+> ONLY PROCEED TO NEXT STEPS IF THE REMOTE IS A GITHUB URL
+
+1. For each task in the list, use the GitHub MCP server to create a new issue in the repository that is representative of the Git remote.
+
+> [!CAUTION]
+> UNDER NO CIRCUMSTANCES EVER CREATE ISSUES IN REPOSITORIES THAT DO NOT MATCH THE REMOTE URL

data/.cursor/rules/specify-rules.mdc

@@ -0,0 +1,32 @@
+# jp_address_complement_rb Development Guidelines
+
+Auto-generated from all feature plans. Last updated: 2026-02-23
+
+## Active Technologies
+- Ruby 3.0+（3.2 以上推奨） + Rails 7.x 以上（オプション）、RSpec、SimpleCov、RuboCop (004-prefecture-code-reverse-lookup)
+- 都道府県コード⇔名称はメモリ内の定数マッピング。逆引きは既存の `jp_address_complement_postal_codes` テーブルを利用。 (004-prefecture-code-reverse-lookup)
+
+- Ruby 3.x（3.2 以上推奨） + Rails 7.x、ActiveRecord、標準庫 CSV (003-csv-remove-obsolete)
+
+## Project Structure
+
+```text
+src/
+tests/
+```
+
+## Commands
+
+# Add commands for Ruby 3.x（3.2 以上推奨）
+
+## Code Style
+
+Ruby 3.x（3.2 以上推奨）: Follow standard conventions
+
+## Recent Changes
+- 004-prefecture-code-reverse-lookup: Added Ruby 3.0+（3.2 以上推奨） + Rails 7.x 以上（オプション）、RSpec、SimpleCov、RuboCop
+
+- 003-csv-remove-obsolete: Added Ruby 3.x（3.2 以上推奨） + Rails 7.x、ActiveRecord、標準庫 CSV
+
+<!-- MANUAL ADDITIONS START -->
+<!-- MANUAL ADDITIONS END -->

data/.rubocop.yml

@@ -0,0 +1,118 @@
+plugins:
+  - rubocop-rspec
+
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.2
+  SuggestExtensions: false
+  Exclude:
+    - "bin/**/*"
+    - "sig/**/*"
+    - "vendor/**/*"
+    - "specs/**/*"
+    - "examples/**/*"
+    - "Gemfile"
+
+# Gemspec の development dependency は gemspec 内で管理
+Gemspec/DevelopmentDependencies:
+  Enabled: false
+
+# 日本語コメントを許容
+Style/AsciiComments:
+  Enabled: false
+
+# frozen_string_literal は全ファイルで必須
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always
+
+# プロジェクトの特性上、メソッドの行数制限を緩める
+Metrics/MethodLength:
+  Max: 20
+
+# CsvImporter のブロック長は許容
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"
+    - "jp_address_complement.gemspec"
+
+# モジュール・クラス長の上限を緩める（Repository 実装用）
+Metrics/ClassLength:
+  Max: 150
+
+# RSpec の describe/context は DSL の性質上緩める
+RSpec/ExampleLength:
+  Max: 20
+
+RSpec/MultipleExpectations:
+  Max: 5
+
+RSpec/NestedGroups:
+  Max: 5
+
+# Generator・タスク・パフォーマンステストはクラス記述不要
+RSpec/DescribeClass:
+  Exclude:
+    - "spec/generators/**/*"
+    - "spec/tasks/**/*"
+    - "spec/performance_spec.rb"
+
+# RSpec spec パスのディレクトリ構成を許容（spec/ 直下に rb ファイルを置きたい場合）
+RSpec/SpecFilePathFormat:
+  Enabled: false
+
+RSpec/SpecFilePathSuffix:
+  Enabled: false
+
+# context の日本語記述の等を許容
+RSpec/ContextWording:
+  Prefixes:
+    - when
+    - with
+    - without
+    - 正常な
+    - 不正な
+    - "nil"
+    - 先頭
+    - 7桁
+    - 4桁
+    - 8桁
+    - 同じ
+    - 異なる
+
+# AddressRecord は Data.define の返り値で定数名規則を強制できない
+Naming/ConstantName:
+  Exclude:
+    - "lib/jp_address_complement/address_record.rb"
+
+# Gem エントリーポイントはトップレベルドキュメントを必須としない
+Style/Documentation:
+  Exclude:
+    - "lib/jp_address_complement.rb"
+    - "spec/**/*"
+
+# rbs-inline の #: Type 注釈は # の直後に : が来るため LeadingCommentSpace と競合（FR-010, T008）
+Layout/LeadingCommentSpace:
+  Exclude:
+    - "lib/jp_address_complement/configuration.rb"
+    - "lib/jp_address_complement/importers/csv_importer.rb"
+    - "lib/jp_address_complement/normalizer.rb"
+    - "lib/jp_address_complement/version.rb"
+
+# マジックコメント直後の空行: rbs_inline: disabled は 1 行で理由まで書くため空行を入れない（T008）
+Layout/EmptyLineAfterMagicComment:
+  Exclude:
+    - "lib/jp_address_complement/address_record.rb"
+
+# CsvImporter の parse_row は列数が多い CSV のパースのためやむを得ず複雑になる
+Metrics/AbcSize:
+  Exclude:
+    - "lib/jp_address_complement/importers/csv_importer.rb"
+
+Metrics/CyclomaticComplexity:
+  Exclude:
+    - "lib/jp_address_complement/importers/csv_importer.rb"
+
+Metrics/PerceivedComplexity:
+  Exclude:
+    - "lib/jp_address_complement/importers/csv_importer.rb"

data/.specify/memory/constitution.md

@@ -0,0 +1,130 @@
+<!--
+Sync Impact Report
+==================
+Version change: 1.0.1 → 1.0.2
+Bump type: PATCH（gem名 typo 修正・原則 IV にインポート戦略を追記）
+Modified principles:
+  - I. Gem-First: gem名 typo修正 jp_address_Complement → jp_address_complement
+  - IV. データ整合性と定期更新: 差分インポート戦略・DB負荷最適化方针を追記
+Added sections: none
+Removed sections: none
+Templates updated:
+  - .specify/templates/plan-template.md ✅ updated
+  - .specify/templates/spec-template.md ✅ (変更なし)
+  - .specify/templates/tasks-template.md ✅ (変更なし)
+Deferred TODOs: none
+-->
+
+# JpAddressComplement Constitution
+
+## Core Principles
+
+### I. Gem-First (単一責務 gem 設計)
+
+本プロジェクトは Rails アプリケーションに組み込む単一目的の gem として設計する。
+gem は自己完結し、独立してテスト・ドキュメント化できなければならない。
+機能追加の際は必ず「この gem の責務か」を問い、責務外の機能は含まない。
+
+- gem 名は `jp_address_complement`、名前空間は `JpAddressComplement` に閉じ、外部名前空間を汚染しない。
+- 外部依存は最小限とし、追加する場合は明確な理由を文書化する。
+- Rails への結合は Railtie/Engine 経由のみとし、本体ロジックは Rails 非依存に保つ。
+
+### II. TDD 必須 (NON-NEGOTIABLE)
+
+テストを先に書き、失敗を確認してから実装する。Red-Green-Refactor サイクルを厳守する。
+
+- 実装コードより先にテストを書く。テストが失敗することを確認してから実装を始める。
+- テストカバレッジは **90% 以上** を維持する（SimpleCov で計測）。
+- ユニットテスト・統合テストを両方用意する。
+- テストは意図を明確に示す記述でなければならない（`describe` / `context` / `it` の適切な使用）。
+
+### III. Rubocop 完全準拠 (NON-NEGOTIABLE)
+
+すべてのコードは `rubocop` を 100% パスしなければならない。
+
+- `# rubocop:disable` コメントの使用は **禁止**。
+- Rubocop の設定変更（`.rubocop.yml`）で対処する場合は、その理由をコメントで明記する。
+- CI/CD パイプラインで Rubocop チェックを必須ゲートとして設定する。
+- PR マージ前に必ず Rubocop をパスすること。
+
+### IV. データ整合性と定期更新
+
+日本郵便が公開する郵便番号 CSV データを正確に取り込み・管理する。
+
+- データソース URL（ZIP）: https://www.post.japanpost.jp/zipcode/dl/oogaki/zip/ken_all.zip
+- データの取り込みは冪等（同一データを重複投入してもデータが重複しない）でなければならない。
+- 定期更新の仕組み（Rake タスク等）を提供し、最新データへの追従を可能とする。
+- 文字コード（Shift-JIS → UTF-8 変換）や改行コードの差異を適切に処理する。
+
+#### インポート戦略（DB 負荷最適化）
+
+**基本方针: 差分インポートを強く推奨するが、負荷・運用コストを考慮して最適な手段を選択する。**
+
+1. **差分インポート（標準）**
+   - CSV 全件を読み込み、既存データとの差分（追加・変更・削除）のみ DB へ反映する。
+   - `INSERT ... ON CONFLICT DO UPDATE`（upsert）を活用し、変更がない行はスキップする。
+   - 削除検出は：削除フラグ列（`deleted_at`）もしくは「現在の全郵便番号セットに含まれない行を削除」で対応する。
+   - 大量 upsert はバッチ分割（例: 1,000件/バッチ）で実行し、ロック持続時間を最小化する。
+
+2. **全更新（フォールバック）**
+   - 初回セットアップ時、または差分検知機構が利用不可な場合に限り使用する。
+   - 全更新時は「一時テーブルへ載せ替え、アトミックに本テーブルと入れ替える」方式を検討する（ダウンタイムなし）。
+
+3. **差分検知の仕組み**
+   - 日本郵便が提供する差分データが利用可能な場合はそちらを優先する。
+   - 差分判定にはデータのチェックサム（MD5/SHA256）もしくはバージョン情報で変更の有無を判定する。
+   - 差分がない場合は DB への書き込みを全スキップする。
+
+### V. 機能要件の厳守
+
+提供する機能は以下の3つに限定し、各機能は明確なインターフェースを持つ。
+
+1. **郵便番号から住所取得**: 7桁の郵便番号（ハイフンあり・なし両対応）から住所を返す。
+2. **前方一致住所候補取得**: 郵便番号の先頭 4桁以上の入力で、対象となる住所候補一覧を返す。
+3. **郵便番号と住所の不一致検出**: 郵便番号と住所の組み合わせが正しいかを検証し、不一致の場合はその理由を返す。
+
+- 各機能は引数バリデーションを行い、不正入力には明確な例外またはエラーオブジェクトを返す。
+- 戻り値の型は一貫性を持たせる（nil ではなく空配列・Result オブジェクト等）。
+
+### VI. シンプルさ優先
+
+複雑さは価値によって正当化されなければならない。
+
+- YAGNI（You Aren't Gonna Need It）原則を適用する。
+- 抽象化は2つ以上のユースケースが存在してから導入する。
+- 設計判断には必ず理由を文書化する。
+
+## Technology Standards
+
+- **言語**: Ruby 3.x（3.2 以上を推奨）
+- **対応フレームワーク**: Rails 7.x 以上
+- **テストフレームワーク**: RSpec
+- **カバレッジ計測**: SimpleCov（目標 90% 以上）
+- **Lint**: RuboCop（100% 必須、disable 禁止）
+- **gem 管理**: Bundler
+- **データ形式**: 日本郵便oogaki CSV（Shift-JIS エンコード）
+- **プロジェクト種別**: Ruby gem（Rails Engine）
+
+## Quality Gates
+
+各 PR・マージ前に以下をすべて満たすこと：
+
+- [ ] `bundle exec rspec` が全テスト PASS
+- [ ] `bundle exec rubocop` が PASS（警告・エラーゼロ、disable コメントなし）
+- [ ] `SimpleCov` のカバレッジレポートで 90% 以上を確認
+- [ ] 新機能・変更にはテストが付随している（TDD サイクルを経ていること）
+- [ ] 公開 API の変更には CHANGELOG を更新
+
+## Governance
+
+- この Constitution はプロジェクトのすべての開発慣行より優先される。
+- 修正には以下が必要：変更内容の文書化・理由の明記・影響するテンプレート/タスクへの反映。
+- 原則 II（TDD）・原則 III（Rubocop）は **絶対要件** であり、例外なく遵守する。
+- すべての PR レビューでこの Constitution への準拠を確認する。
+- 複雑さの追加は必ず正当化し、Complexity Tracking セクションに記録する。
+- バージョニングポリシー：
+  - MAJOR: 後方互換性のない原則削除・再定義
+  - MINOR: 新原則追加・セクション追加
+  - PATCH: 表現の明確化・誤字修正・非意味的な改訂
+
+**Version**: 1.0.2 | **Ratified**: 2026-02-22 | **Last Amended**: 2026-02-22

data/.specify/scripts/bash/check-prerequisites.sh

@@ -0,0 +1,166 @@
+#!/usr/bin/env bash
+
+# Consolidated prerequisite checking script
+#
+# This script provides unified prerequisite checking for Spec-Driven Development workflow.
+# It replaces the functionality previously spread across multiple scripts.
+#
+# Usage: ./check-prerequisites.sh [OPTIONS]
+#
+# OPTIONS:
+#   --json              Output in JSON format
+#   --require-tasks     Require tasks.md to exist (for implementation phase)
+#   --include-tasks     Include tasks.md in AVAILABLE_DOCS list
+#   --paths-only        Only output path variables (no validation)
+#   --help, -h          Show help message
+#
+# OUTPUTS:
+#   JSON mode: {"FEATURE_DIR":"...", "AVAILABLE_DOCS":["..."]}
+#   Text mode: FEATURE_DIR:... \n AVAILABLE_DOCS: \n ✓/✗ file.md
+#   Paths only: REPO_ROOT: ... \n BRANCH: ... \n FEATURE_DIR: ... etc.
+
+set -e
+
+# Parse command line arguments
+JSON_MODE=false
+REQUIRE_TASKS=false
+INCLUDE_TASKS=false
+PATHS_ONLY=false
+
+for arg in "$@"; do
+    case "$arg" in
+        --json)
+            JSON_MODE=true
+            ;;
+        --require-tasks)
+            REQUIRE_TASKS=true
+            ;;
+        --include-tasks)
+            INCLUDE_TASKS=true
+            ;;
+        --paths-only)
+            PATHS_ONLY=true
+            ;;
+        --help|-h)
+            cat << 'EOF'
+Usage: check-prerequisites.sh [OPTIONS]
+
+Consolidated prerequisite checking for Spec-Driven Development workflow.
+
+OPTIONS:
+  --json              Output in JSON format
+  --require-tasks     Require tasks.md to exist (for implementation phase)
+  --include-tasks     Include tasks.md in AVAILABLE_DOCS list
+  --paths-only        Only output path variables (no prerequisite validation)
+  --help, -h          Show this help message
+
+EXAMPLES:
+  # Check task prerequisites (plan.md required)
+  ./check-prerequisites.sh --json
+  
+  # Check implementation prerequisites (plan.md + tasks.md required)
+  ./check-prerequisites.sh --json --require-tasks --include-tasks
+  
+  # Get feature paths only (no validation)
+  ./check-prerequisites.sh --paths-only
+  
+EOF
+            exit 0
+            ;;
+        *)
+            echo "ERROR: Unknown option '$arg'. Use --help for usage information." >&2
+            exit 1
+            ;;
+    esac
+done
+
+# Source common functions
+SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# Get feature paths and validate branch
+eval $(get_feature_paths)
+check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
+
+# If paths-only mode, output paths and exit (support JSON + paths-only combined)
+if $PATHS_ONLY; then
+    if $JSON_MODE; then
+        # Minimal JSON paths payload (no validation performed)
+        printf '{"REPO_ROOT":"%s","BRANCH":"%s","FEATURE_DIR":"%s","FEATURE_SPEC":"%s","IMPL_PLAN":"%s","TASKS":"%s"}\n' \
+            "$REPO_ROOT" "$CURRENT_BRANCH" "$FEATURE_DIR" "$FEATURE_SPEC" "$IMPL_PLAN" "$TASKS"
+    else
+        echo "REPO_ROOT: $REPO_ROOT"
+        echo "BRANCH: $CURRENT_BRANCH"
+        echo "FEATURE_DIR: $FEATURE_DIR"
+        echo "FEATURE_SPEC: $FEATURE_SPEC"
+        echo "IMPL_PLAN: $IMPL_PLAN"
+        echo "TASKS: $TASKS"
+    fi
+    exit 0
+fi
+
+# Validate required directories and files
+if [[ ! -d "$FEATURE_DIR" ]]; then
+    echo "ERROR: Feature directory not found: $FEATURE_DIR" >&2
+    echo "Run /speckit.specify first to create the feature structure." >&2
+    exit 1
+fi
+
+if [[ ! -f "$IMPL_PLAN" ]]; then
+    echo "ERROR: plan.md not found in $FEATURE_DIR" >&2
+    echo "Run /speckit.plan first to create the implementation plan." >&2
+    exit 1
+fi
+
+# Check for tasks.md if required
+if $REQUIRE_TASKS && [[ ! -f "$TASKS" ]]; then
+    echo "ERROR: tasks.md not found in $FEATURE_DIR" >&2
+    echo "Run /speckit.tasks first to create the task list." >&2
+    exit 1
+fi
+
+# Build list of available documents
+docs=()
+
+# Always check these optional docs
+[[ -f "$RESEARCH" ]] && docs+=("research.md")
+[[ -f "$DATA_MODEL" ]] && docs+=("data-model.md")
+
+# Check contracts directory (only if it exists and has files)
+if [[ -d "$CONTRACTS_DIR" ]] && [[ -n "$(ls -A "$CONTRACTS_DIR" 2>/dev/null)" ]]; then
+    docs+=("contracts/")
+fi
+
+[[ -f "$QUICKSTART" ]] && docs+=("quickstart.md")
+
+# Include tasks.md if requested and it exists
+if $INCLUDE_TASKS && [[ -f "$TASKS" ]]; then
+    docs+=("tasks.md")
+fi
+
+# Output results
+if $JSON_MODE; then
+    # Build JSON array of documents
+    if [[ ${#docs[@]} -eq 0 ]]; then
+        json_docs="[]"
+    else
+        json_docs=$(printf '"%s",' "${docs[@]}")
+        json_docs="[${json_docs%,}]"
+    fi
+    
+    printf '{"FEATURE_DIR":"%s","AVAILABLE_DOCS":%s}\n' "$FEATURE_DIR" "$json_docs"
+else
+    # Text output
+    echo "FEATURE_DIR:$FEATURE_DIR"
+    echo "AVAILABLE_DOCS:"
+    
+    # Show status of each potential document
+    check_file "$RESEARCH" "research.md"
+    check_file "$DATA_MODEL" "data-model.md"
+    check_dir "$CONTRACTS_DIR" "contracts/"
+    check_file "$QUICKSTART" "quickstart.md"
+    
+    if $INCLUDE_TASKS; then
+        check_file "$TASKS" "tasks.md"
+    fi
+fi