beyond-local-file 0.2.2__tar.gz

beyond_local_file-0.2.2/.gitignore

@@ -0,0 +1,21 @@
+.DS_Store
+.vscode/
+
+# Agentic
+/.qoder/specs/
+/.trae/documents/
+
+# Python
+__pycache__/
+.venv/
+.hypothesis/
+.pytest_cache/
+.ruff_cache/
+dist/
+
+# Demo workspace (temporary, regenerated by setup script)
+/demo-workspace/
+
+# Demo recordings (keep only the final optimized GIF)
+/demo/*.cast
+/demo/*-unoptimized.gif

beyond_local_file-0.2.2/.kiro/hooks/code-review.kiro.hook

@@ -0,0 +1,13 @@
+{
+  "enabled": true,
+  "name": "Code Review",
+  "description": "Runs a thorough code review of changed files in src/beyond_local_file/ using the project's review checklist covering architecture, code quality, docstrings, type annotations, Ruff compliance, correctness, tests, and language.",
+  "version": "1",
+  "when": {
+    "type": "userTriggered"
+  },
+  "then": {
+    "type": "askAgent",
+    "prompt": "You are a senior Python engineer performing a thorough code review for the `beyond-local-file` project — a CLI tool (Click + Rich) that manages symlinks and Git excludes for local development files across multiple projects.\n\n## Project Context\n\n**Stack:** Python 3.13+, Click 8, Rich 14, PyYAML 6, uv (exclusive package manager), Ruff (linter + formatter), pytest + Hypothesis (tests).\n\n**Architecture:** The project follows a divide-and-conquer strategy with protocol-based composition:\n- **Operations** (SyncOperation, CheckOperation) partition items by strategy and coordinate managers\n- **Managers** (SymlinkManager, CopyManager) implement LinkStrategyManager protocol\n- **Result Types** use composition for strategy-specific details (LinkCreateResult, LinkCheckResult)\n- Operations are responsible for partitioning; managers receive pre-filtered items\n- See `docs/architecture-design.md` for complete architecture documentation\n\n## Review Checklist\n\nReview ALL changed files in `src/beyond_local_file/` against each category below. Be precise: quote the problematic code, state the rule violated, and give a concrete fix.\n\n### 1. Architecture & Responsibility\n- Does each module respect its single responsibility?\n- Are new CLI commands implemented as `CmdOperation` subclasses in `project_processor.py`?\n- Are all fixed option values defined as `StrEnum` in `options.py`? No magic strings elsewhere.\n- Are raw Click strings coerced back to enums at the CLI boundary?\n- Is output formatting decoupled from operations via dedicated formatter classes?\n- Do operations partition items by strategy before delegating to managers?\n- Do managers receive pre-filtered items (not the entire project)?\n- Are result types using composition for strategy-specific details?\n\n### 2. Code Quality & Design\n- Does every function/class follow the single-responsibility principle?\n- Are there deep nesting levels (>3) that should be refactored?\n- Are there any magic values, hardcoded strings, or unexplained constants?\n- Are changes minimal, safe, and behavior-preserving (Martin Fowler refactoring principles)?\n- Is there any unnecessary complexity?\n\n### 3. Docstrings (Google Style)\n- Does every public class, method, function, and module have a complete Google-style docstring?\n- Do docstrings describe behavior from the caller's perspective?\n- Are `Args:`, `Returns:`, and `Raises:` sections present and accurate?\n- For Click commands: is the docstring clean — summary + optional description only, NO `Args:` section?\n- Are there any stale or misleading docstrings?\n\n### 4. Type Annotations\n- Are all function signatures fully annotated?\n- Are `noqa` suppressions present where Click injects args at runtime?\n- Are modern Python 3.13+ union types used?\n- Are `None`-returning procedures explicitly annotated `-> None`?\n\n### 5. Ruff Compliance\n- Would any changed code trigger violations under: `E`, `W`, `F`, `I`, `UP`, `B`, `SIM`, `ANN`, `PL`, `RUF`?\n- Are lines within the 120-character limit?\n- Are imports sorted?\n- Do all `noqa` suppressions include an explanatory comment?\n\n### 6. Correctness & Edge Cases\n- Are symlink path resolutions always absolute?\n- Are config paths resolved relative to the config file's directory?\n- Are target paths resolved relative to CWD?\n- Are missing files, broken symlinks, and non-existent target directories handled gracefully?\n- Is `.git/info/exclude` read/written safely?\n\n### 7. Tests\n- Is there a corresponding test for every new function or behavior change?\n- Do tests cover edge cases?\n- Is test coverage maintained above 80%?\n\n### 8. Language\n- Are all docstrings, inline comments, and docs written in English?\n- Do inline comments explain *why*, not *what*?\n\n### 9. Documentation Gap Analysis\n- Check if changes affect behavior, CLI options, or configuration that should be reflected in:\n  - `README.md` (project root)\n  - `docs/` directory\n  - `.kiro/steering/` files (project rules, steering docs)\n- **New-feature rule:** Determine whether the changes introduce a new feature (new CLI command, new option, new config key, new behavior). If yes, missing documentation for that feature in the appropriate docs and/or steering files is a 🔴 **Must Fix** — without it the feature is effectively invisible.\n- Flag any changed options or modified behavior that lack corresponding documentation updates.\n- Flag any steering files that should be updated to reflect new patterns or conventions introduced by the changes.\n- **Documentation gap detection criteria:**\n  1. **New patterns/conventions:** Changes introduce new coding patterns, architectural conventions, configuration approaches, or tool usage not covered in existing docs\n     - Example: New annotation usage, new middleware integration, new exception handling pattern\n  2. **Implicit rules made explicit:** Changes reflect existing but undocumented team conventions\n     - Example: Field naming conventions, configuration patterns, scenario-specific handling practices\n  3. **Lessons learned:** Changes fix a common mistake worth documenting to prevent others from repeating it\n     - Example: Non-intuitive API behavior, hidden configuration dependencies\n  4. **Steering rule gaps:** Changes involve scenarios not covered in `.kiro/steering/`, potentially causing AI-assisted coding to generate non-compliant code\n  5. **Integration guide gaps or staleness:** Changes affect APIs (add/modify/delete endpoints) but `docs/` lacks corresponding integration guides, or existing guides are inconsistent with implementation\n\nFor each documentation gap found, provide:\n- **Content summary:** One-sentence description of what needs to be added\n- **Target file:** Specific file path (docs/xx.md or .kiro/steering/xx.md)\n- **Rationale:** Why current docs are insufficient and what value the addition provides\n\nIf no documentation gaps are found, state \"No documentation gaps found\" — do not force findings.\n\n## Action Rules\n\n### 🔴 Must Fix — Auto-fix loop\nFor every Must Fix issue you find:\n1. Fix the code yourself immediately.\n2. After fixing, re-run the relevant checklist checks on the changed files.\n3. Repeat until zero Must Fix issues remain.\n4. Report what you fixed and the final state.\n\n### 🟡 Should Fix / 🔵 Consider — Log to simple_advices.md\nFor Should Fix and Consider issues that can be clearly stated in one sentence:\n1. Append each issue to `local-file/tasks/auto-review/simple_advices.md` as a checklist item.\n2. Use this format per entry:\n   ```\n   - [ ] **[🟡/🔵] <short title>** — `<file>:<line>` — <one-line description of the issue and suggested fix>\n   ```\n3. Group entries under a date heading (`## YYYY-MM-DD`) so the file serves as a running log.\n\nFor complex findings requiring detailed description, impact analysis, or multiple solutions:\n1. Create a detailed task file in `local-file/tasks/auto-review/` following the standard task format\n2. Add it to `local-file/tasks/auto-review/index.md`\n\n## Output Format\n\nUse this structure:\n```\n## Code Review Summary\n**Files reviewed:** <list>\n**Overall assessment:** ✅ Approved / ⚠️ Approved with comments / ❌ Changes required\n\n## 🔴 Must Fix (auto-fixed)\nList each issue you found and how you fixed it. If none, state \"No must-fix issues found.\"\n\n## 🟡 Should Fix / 🔵 Consider\nList issues appended to `simple_advices.md` or created as detailed tasks. If none, state \"No advisory issues found.\"\n\n## Documentation Gaps\nList any documentation that needs updating in README.md, docs/, or .kiro/steering/ to reflect the changes. If none, state \"No documentation gaps found.\"\n\n## What's Done Well\n```\n\n## Recommended Commit Message\n\nIf the overall assessment is ✅ Approved or ⚠️ Approved with comments, generate a recommended git commit message following Conventional Commits format:\n- Use appropriate type: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, etc.\n- Include a concise scope in parentheses when relevant (e.g., `feat(cli)`, `fix(symlink)`)\n- Write a clear, imperative subject line (max 72 chars)\n- Add a body with bullet points summarizing key changes if needed\n- Example:\n```\nfeat(cli): add dry-run mode for sync command\n\n- Add --dry-run flag to sync command\n- Display planned actions without executing\n- Update help text and docstrings\n```\n\nIf the assessment is ❌ Changes required (Must Fix issues could not be auto-resolved), skip the commit message and state \"Resolve remaining 🔴 Must Fix issues before committing.\"\n\nBe direct, precise, and constructive. Quote actual code. Focus on substance over style nits unless they violate a hard project rule."
+  }
+}

beyond_local_file-0.2.2/.kiro/hooks/prepare-release.kiro.hook

@@ -0,0 +1,13 @@
+{
+  "enabled": true,
+  "name": "Prepare Release",
+  "description": "Archives completed tasks, generates CHANGELOG entries, and cleans up task indices for the next release",
+  "version": "1",
+  "when": {
+    "type": "userTriggered"
+  },
+  "then": {
+    "type": "askAgent",
+    "prompt": "You are preparing a new release for the `beyond-local-file` project. Follow these steps:\n\n## Step 1: Determine Release Version\n\n1. Get the latest git tag: `git describe --tags --abbrev=0`\n2. Ask the user what the next version number should be (e.g., v0.2.0)\n3. Store this as `NEW_VERSION`\n4. Get the date of the last release tag: `git log -1 --format=%ai [last-tag]`\n5. Store this as `LAST_RELEASE_DATE`\n\n## Step 2: Validate All Tests Pass\n\n1. Run the full test suite: `uv run pytest`\n2. If any tests fail:\n   - Report the failures to the user\n   - STOP the release preparation process immediately\n   - Inform the user they must fix all test failures before proceeding with the release\n   - Do NOT continue to subsequent steps\n3. Only continue to Step 3 if all tests pass successfully\n\n## Step 3: Identify Completed Tasks\n\n1. Read `local-file/tasks/manual/index.md`\n2. Extract all lines marked with `[x]` (completed tasks)\n3. For each completed task:\n   - Extract the task file name from the markdown link\n   - Read the full task file from `local-file/tasks/manual/[task-name].md`\n   - Extract from the header: Category, Description\n   - Extract from sections: Motivation, Expected Behavior\n   - Use these to write clear, user-facing changelog entries\n\n## Step 4: Identify Agentic Worklog Files to Archive\n\n1. Find all timestamped files in `local-file/agentic/analysis/`, `local-file/agentic/drafts/`, and `local-file/agentic/summaries/`\n2. For each file with `YYYYMMDD-HH-` prefix:\n   - Parse the timestamp from the filename\n   - If the timestamp is >= `LAST_RELEASE_DATE` and < current date, mark for archival\n3. Store the list of files to archive\n\n## Step 5: Generate CHANGELOG\n\nCreate `local-file/tasks/releases/${NEW_VERSION}/CHANGELOG.md` with this structure:\n\n```markdown\n# Release ${NEW_VERSION}\n\nRelease Date: [YYYY-MM-DD]\n\n## Features\n- [Feature title] — Brief description from task\n\n## Bug Fixes\n- [Bug title] — Brief description from task\n\n## Usability\n- [Usability improvement] — Brief description from task\n\n## Documentation\n- [Doc update] — Brief description from task\n\n## Code Quality\n- [Refactoring] — Brief description from task\n```\n\nOnly include categories that have completed tasks. Use the task descriptions and motivation to write clear, user-facing changelog entries.\n\n## Step 6: Archive Completed Tasks\n\n1. Create directories:\n   - `local-file/tasks/releases/${NEW_VERSION}/tasks/manual/`\n   - `local-file/tasks/releases/${NEW_VERSION}/tasks/auto-review/` (if needed)\n2. For each completed manual task file:\n   - Copy the file from `local-file/tasks/manual/[task-name].md` to `local-file/tasks/releases/${NEW_VERSION}/tasks/manual/[task-name].md`\n   - Delete the original from `local-file/tasks/manual/`\n3. For each completed auto-review detailed task (if any):\n   - Copy the file from `local-file/tasks/auto-review/[task-name].md` to `local-file/tasks/releases/${NEW_VERSION}/tasks/auto-review/[task-name].md`\n   - Delete the original from `local-file/tasks/auto-review/`\n\n## Step 7: Archive Agentic Worklog Files\n\n1. Create directories:\n   - `local-file/tasks/releases/${NEW_VERSION}/worklog/analysis/`\n   - `local-file/tasks/releases/${NEW_VERSION}/worklog/drafts/`\n   - `local-file/tasks/releases/${NEW_VERSION}/worklog/summaries/`\n2. For each agentic file marked for archival:\n   - Move the file from its current location to the corresponding worklog directory\n   - Preserve the filename (including timestamp prefix)\n3. This keeps the working agentic directories clean for the next development cycle\n\n## Step 8: Update Task Indices\n\n1. Update `local-file/tasks/manual/index.md`:\n   - Remove all lines marked with `[x]` (completed tasks)\n   - Keep only uncompleted tasks `[ ]`\n   - Preserve category structure\n\n2. Update `local-file/tasks/index.md`:\n   - Add a link to the new release under \"Archived Releases\" section:\n     ```markdown\n     - [${NEW_VERSION}](./releases/${NEW_VERSION}/CHANGELOG.md) — Released YYYY-MM-DD\n     ```\n\n## Step 9: Update Project CHANGELOG.md\n\n1. Read the generated `local-file/tasks/releases/${NEW_VERSION}/CHANGELOG.md`\n2. Prepend its content to the root `CHANGELOG.md` file\n3. Ensure proper formatting and separation between releases\n\n## Step 10: Summary\n\nProvide a summary:\n- Number of tasks archived\n- Number of agentic worklog files archived (by type: analysis, drafts, summaries)\n- Categories affected\n- Location of generated CHANGELOG\n- Suggested next steps (review CHANGELOG, commit changes, create git tag)\n\n## Important Notes\n\n- Do NOT create a git tag — the user will do this manually after review\n- Do NOT commit changes — let the user review first\n- Preserve the structure and formatting of all markdown files\n- If no completed tasks exist, inform the user and exit gracefully\n- Auto-review findings in `local-file/tasks/auto-review/simple_advices.md` are NOT archived — they remain as a running log\n- Detailed auto-review tasks (if any exist and are completed) CAN be archived like manual tasks\n- Agentic worklog files are MOVED (not copied) to keep working directories clean\n- Only archive agentic files between the last release date and current date"
+  }
+}

beyond_local_file-0.2.2/.kiro/steering/architecture.md

@@ -0,0 +1,116 @@
+---
+inclusion: fileMatch
+fileMatchPattern: "src/beyond_local_file/**"
+---
+
+# Architecture
+
+## Package Layout
+
+```
+src/beyond_local_file/
+├── __init__.py                  # Package metadata (__version__)
+├── cli.py                       # Click CLI entry point — command groups and options
+├── config.py                    # YAML config loading and path resolution (Config class)
+├── options.py                   # StrEnum definitions for CLI option values
+├── link_strategy_protocol.py   # Protocol definitions and unified result types
+├── formatters.py                # Output formatters: LinkSyncFormatter, LinkCheckFormatter
+├── git_manager.py               # GitExcludeManager — reads/writes .git/info/exclude
+├── project_processor.py         # ProjectProcessor + CmdOperation subclasses (SyncOperation, CheckOperation)
+├── symlink_manager.py           # SymlinkManager — implements LinkStrategyManager protocol
+├── copy_manager.py              # CopyManager — implements LinkStrategyManager protocol
+├── sync_state.py                # Copy strategy state tracking
+└── model/
+    ├── config.py                # Config models (YAML structure)
+    ├── processing.py            # Processing models (execution structure)
+    └── translator.py            # Config → Processing translation
+```
+
+## Data Flow
+
+1. `cli.py` parses CLI args, calls `load_config()` from `project_processor.py`.
+2. `load_config()` uses `Config` (from `config.py`) to parse YAML and return `dict[str, ProjectConfiguration]`.
+3. `ProjectProcessor.process_all(operation)` iterates projects/targets, creates `Project.from_directory()`, and calls `operation.execute(project, target_path)`.
+4. `SyncOperation` / `CheckOperation` delegate to `SymlinkManager` for the actual symlink and git-exclude work.
+5. Formatters in `formatters.py` handle all output rendering (Rich tables for table mode, click.echo for verbose mode).
+
+## Key Design Decisions
+
+- Tool and data separation: the CLI is installed once; managed project directories live separately.
+- Config paths resolve relative to the config file's directory; target paths resolve relative to CWD.
+- `CmdOperation` is an abstract base with `execute()` and `verbose_progress` — new commands extend this.
+- `SymlinkManager` owns both symlink logic and `GitExcludeManager` composition.
+- Output formatting is decoupled from operations via dedicated formatter classes.
+
+## Result Type Architecture
+
+All result types are defined in `link_strategy_protocol.py` as the single source of truth:
+
+**Base Result Types:**
+- `LinkCreateResult` — Results from link creation operations
+- `LinkCheckResult` — Results from link check operations
+- `GitExcludeAddResult` — Results from git exclude add operations
+- `GitExcludeCheckResult` — Results from git exclude check operations
+- `OperationProgress` — Progress tracking embedded in operation results
+
+**Strategy-Specific Details:**
+- `CopyCreateDetails` — Additional information for copy strategy create operations (e.g., reverse_copied items)
+- `CopyCheckDetails` — Additional information for copy strategy check operations (e.g., sync status details)
+
+**Composition Pattern:**
+Base results use composition for strategy-specific details:
+```python
+@dataclass
+class LinkCreateResult:
+    created: set[str]
+    already_correct: set[str]
+    skipped: set[str]
+    failed: set[str]
+    details: LinkCreateDetails | None = None  # Strategy-specific details
+    progress: OperationProgress = field(default_factory=...)
+```
+
+Managers create unified result types directly.
+
+## Git Exclude Responsibility Pattern
+
+Operations are responsible for checking git repository status before calling manager git exclude methods:
+
+```python
+# In operations (project_processor.py)
+if symlink_items:
+    manager = SymlinkManager(symlink_items, unit.target_project_path)
+    link_result = manager.create_links(self.ask_callback)
+    
+    # Operation checks git repo status
+    git_result = None
+    if manager.git_manager.is_git_repo():
+        git_result = manager.add_git_excludes()
+```
+
+Managers document this as a PRECONDITION in their docstrings:
+
+```python
+def add_git_excludes(self) -> GitExcludeAddResult:
+    """Add git exclude entries for all managed items (protocol method).
+    
+    PRECONDITION: This method is guaranteed to be called only when the target
+    directory is inside a git repository. Callers must check git repo status
+    before invoking this method.
+    """
+```
+
+This design:
+- Keeps managers focused on their core responsibility (managing links)
+- Avoids redundant git repo checks across multiple managers
+- Makes the precondition explicit in the contract
+
+## Adding a New CLI Command
+
+1. Create a new `CmdOperation` subclass in `project_processor.py`.
+2. Add a new Click command in `cli.py` under the `link` group (or a new group).
+3. If the command has fixed option values, define a `StrEnum` in `options.py`.
+4. Use protocol methods (`create_links()`, `check_links()`, `add_git_excludes()`, `check_git_excludes()`).
+5. Operations must check git repo status before calling git exclude methods.
+6. Use `LinkSyncFormatter` and `LinkCheckFormatter` for output.
+7. All result types come from `link_strategy_protocol.py`.

beyond_local_file-0.2.2/.kiro/steering/docstrings.md

@@ -0,0 +1,55 @@
+---
+inclusion: fileMatch
+fileMatchPattern: "src/beyond_local_file/**"
+---
+
+# Docstring Conventions
+
+## General Rules
+
+Every public class, function, method, and module must have a complete docstring using Google style.
+
+Docstrings should:
+- Describe purpose from the caller's perspective.
+- Document parameters (type, meaning, default).
+- Specify return value (type and semantics).
+- List possible exceptions or important edge cases.
+- Avoid leaking implementation details.
+
+Example:
+```python
+def process_data(path: str | Path, /, *, timeout: int = 30) -> dict[str, Any]:
+    """Load and process configuration from the given path.
+
+    Args:
+        path: Path to the configuration file (str or Path object).
+        timeout: Maximum time in seconds to wait for I/O operations.
+
+    Returns:
+        Dictionary containing the parsed and normalized configuration.
+
+    Raises:
+        FileNotFoundError: If the file does not exist.
+        ValueError: If the file contains invalid YAML.
+    """
+```
+
+## Click CLI Commands
+
+Click uses the function docstring as `--help` text. Keep it clean:
+
+- Do NOT include an `Args:` section — Click documents arguments/options via decorators and `help=` parameters.
+- Use only a short summary line and optionally a longer description paragraph.
+
+Example:
+```python
+@cli.command()
+@click.argument("project_name", required=False)
+@click.option("--verbose", is_flag=True, help="Enable verbose output.")
+def deploy(project_name, verbose):  # noqa: ANN001 -- click injects args at runtime
+    """Deploy the project to the target environment.
+
+    Reads configuration from the default config file and deploys all
+    configured targets unless a specific project name is provided.
+    """
+```

beyond_local_file-0.2.2/.kiro/steering/local_file_structure.md

@@ -0,0 +1,324 @@
+---
+inclusion: always
+---
+
+# local-file Directory Convention
+
+This file defines the storage and organization conventions for the `local-file/` directory.
+
+## Directory Structure
+
+```
+local-file/
+├── agentic/              # Kiro-generated content
+│   ├── analysis/        # Technical analysis reports (timestamped, flat)
+│   ├── drafts/          # Informal plans, drafts, proposals (timestamped, flat)
+│   ├── specs/           # Formal specification files (no timestamps, flat)
+│   └── summaries/       # Task completion summaries (timestamped, flat)
+├── initiatives/          # Strategic work items (not in changelog/release cycle)
+│   ├── README.md        # Documentation
+│   └── *.md             # Initiative files (e.g., share-and-impact.md)
+└── tasks/               # Task tracking system
+    ├── index.md         # Main hub linking to all task groups
+    ├── manual/          # User-created tasks
+    ├── auto-review/     # Auto-generated review findings
+    └── releases/        # Archived completed tasks by release
+        └── v0.x.x/      # Example release
+            ├── CHANGELOG.md
+            ├── tasks/   # Archived tasks
+            │   ├── manual/
+            │   └── auto-review/
+            └── worklog/ # Archived agentic files
+                ├── analysis/
+                ├── drafts/
+                └── summaries/
+```
+
+---
+
+## Agentic Directory (`local-file/agentic/`)
+
+Kiro-generated content organized by purpose. All files in `analysis/`, `drafts/`, and `summaries/` use `YYYYMMDD-HH-` prefix for chronological ordering (GMT+8 timezone).
+
+### analysis/
+
+**Purpose:** Technical analysis reports generated at the start of or during a chat conversation.
+
+**When to write:** When analyzing codebase structure, investigating issues, or exploring technical approaches before implementation.
+
+**Examples:**
+- Codebase structure analysis
+- Performance bottleneck investigation
+- Dependency analysis
+- Architecture exploration
+
+**Naming:** `YYYYMMDD-HH-descriptive-title.md` using GMT+8 timezone (e.g., `20260326-18-codebase-structure-for-copy-feature.md`)
+
+**Structure:** Flat directory - no subdirectories
+
+### drafts/
+
+**Purpose:** Informal implementation plans, design proposals, or when explicitly asked to draft something.
+
+**When to write:**
+- Creating informal design proposals
+- Drafting API specifications
+- Sketching implementation approaches
+- When user explicitly asks to "draft" something
+
+**Examples:**
+- Design proposals
+- OpenAPI spec drafts
+- Implementation approach sketches
+- Architecture alternatives
+
+**Naming:** `YYYYMMDD-HH-descriptive-title.md` using GMT+8 timezone (e.g., `20260326-18-single-file-copy-proposal.md`)
+
+**Structure:** Flat directory - no subdirectories
+
+### specs/
+
+**Purpose:** Formal specification files that define formats, conventions, and standards.
+
+**When to write:** When creating formal specifications for:
+- File formats
+- API specifications
+- Configuration formats
+- Task definitions
+- Coding conventions
+
+**Examples:**
+- `task-definition-spec.md`
+- `config-format-spec.md`
+- `api-specification.md`
+
+**Naming:** Use `-spec.md` suffix for specification files (no timestamp prefix - specs are timeless)
+
+**Structure:** Flat directory - no subdirectories
+
+### summaries/
+
+**Purpose:** Task completion summaries documenting changes made during a task or conversation.
+
+**When to write:** When a task has been completed and you want to summarize the changes made.
+
+**Examples:**
+- `20260403-14-task-system-improvements.md`
+- `20260327-09-copy-feature-implementation.md`
+- `20260320-16-subpath-support-added.md`
+
+**Naming:** `YYYYMMDD-HH-descriptive-title.md` using GMT+8 timezone
+
+**Structure:** Flat directory - no subdirectories
+
+---
+
+## Initiatives Directory (`local-file/initiatives/`)
+
+Strategic work items and coordinated efforts that don't directly belong in the changelog or release cycle.
+
+**For complete initiative format specification, see:** `local-file/agentic/specs/initiative-definition-spec.md`
+
+This section provides a quick reference. The formal spec contains detailed guidelines on initiative structure, action item tracking, naming conventions, workflow, and best practices.
+
+**Purpose:** Track promotional activities, infrastructure setup, meta-project work, and multi-step initiatives.
+
+**What goes here:**
+- Promotional activities (PyPI publishing, community sharing)
+- Infrastructure setup (CI/CD, GitHub Actions)
+- Meta-project work (documentation overhauls, branding)
+- Multi-step initiatives spanning multiple actions
+
+**What doesn't go here:**
+- Feature development → `local-file/tasks/manual/`
+- Bug fixes → `local-file/tasks/manual/`
+- Code quality improvements → `local-file/tasks/manual/`
+- Auto-review findings → `local-file/tasks/auto-review/`
+
+### Initiative File Format
+
+Each initiative file follows this structure:
+
+**Header (Required):**
+```markdown
+# Initiative Title
+
+**Goal:** One-sentence description of what this initiative aims to achieve.
+**Status:** Planning | In Progress | Completed | On Hold
+**Created:** YYYY-MM-DD
+**Completed:** YYYY-MM-DD (only if status is Completed)
+```
+
+**Overview Section (Required):**
+Brief description of the initiative, its purpose, and expected impact.
+
+**Action Items Table (Required):**
+```markdown
+| # | Action | Status | Related Task/Resource | Notes |
+|---|--------|--------|----------------------|-------|
+| 1 | [Action description] | Not Started | [Link to task](../tasks/manual/task.md) | Optional context |
+| 2 | [Action description] | In Progress | [External link](https://...) | Optional context |
+| 3 | [Action description] | Completed | — | Completed YYYY-MM-DD |
+```
+
+The Action Items table is the centerpiece - it provides at-a-glance status tracking with:
+- Sequential numbering for easy reference
+- Clear action descriptions
+- Status tracking (Not Started, In Progress, Completed, Blocked, Skipped)
+- Links to related tasks or external resources
+- Optional notes for context, completion dates, or blockers
+
+**Detailed Sections (Optional):**
+For complex actions requiring more explanation, add detailed sections after the Action Items table with prerequisites, steps, resources, and notes.
+
+**Success Criteria (Recommended):**
+Define measurable outcomes and specific deliverables that indicate initiative completion.
+
+### Linking Between Initiatives and Tasks
+
+**From Initiative to Task:**
+```markdown
+| 2 | Add --version option | Not Started | [Task](../tasks/manual/add-version-option.md) | Required before PyPI |
+```
+
+**From Task to Initiative:**
+```markdown
+**Part of Initiative:** [Share & Prove Impact](../../initiatives/share-and-impact.md)
+```
+
+This creates bidirectional links showing how strategic goals connect to concrete work.
+
+### Naming Conventions
+
+- Use descriptive, goal-oriented names in kebab-case
+- Avoid dates in filenames (initiatives are timeless)
+- Examples: `share-and-impact.md`, `ci-cd-automation.md`, `documentation-overhaul.md`
+
+**Structure:** Flat directory with markdown files describing goals, action items with status tracking, and context.
+
+**Examples:**
+- `share-and-impact.md` — Promoting the project through PyPI, README improvements, community engagement
+
+---
+
+## Task Tracking System (`local-file/tasks/`)
+
+All project tasks are tracked under `local-file/tasks/` with task groups, indices, and individual task files.
+
+**For complete task format specification, see:** `local-file/agentic/specs/task-definition-spec.md`
+
+This section provides a quick reference. The formal spec contains detailed guidelines on task structure, naming conventions, workflow, and best practices.
+
+### Structure
+
+```
+local-file/tasks/
+├── index.md              # Main hub linking to all task groups
+├── manual/               # User-created tasks
+│   ├── index.md         # Manual tasks index
+│   ├── README.md        # Documentation
+│   └── *.md             # Individual task files
+├── auto-review/          # Auto-generated review findings
+│   ├── index.md         # Auto-review tasks index
+│   ├── simple_advices.md # One-sentence findings (running log)
+│   ├── README.md        # Documentation
+│   └── *.md             # Detailed auto-review task files
+└── releases/             # Archived completed tasks by release
+    ├── README.md        # Documentation
+    └── v0.x.x/          # Example: tasks completed in v0.2.0
+        ├── CHANGELOG.md # Formal changelog for this release
+        ├── tasks/       # Archived completed tasks
+        │   ├── manual/  # Archived manual tasks
+        │   └── auto-review/ # Archived auto-review tasks
+        └── worklog/     # Archived agentic worklog files
+            ├── analysis/   # Archived analysis files
+            ├── drafts/     # Archived draft files
+            └── summaries/  # Archived summary files
+```
+
+### Task Groups
+
+#### Manual Tasks (`local-file/tasks/manual/`)
+User-created tasks for features, bugs, usability improvements, and documentation.
+
+#### Auto-Review Tasks (`local-file/tasks/auto-review/`)
+Automatically generated code review findings:
+- `simple_advices.md` — One-sentence findings (🟡 Should Fix / 🔵 Consider), grouped by date
+- Detailed task files — Complex findings requiring more context, impact analysis, or multiple solutions
+
+### Task Lifecycle
+
+#### 1. Creating a Manual Task
+- Create a markdown file in `local-file/tasks/manual/{verb}-{slug}.md`
+- Start with header: Title, Category, Status, Description
+- Add core sections: Motivation, Current Behavior, Expected Behavior, Proposed Solution
+- Add optional sections as needed (keep implementation details minimal)
+- Add a checkbox entry in `local-file/tasks/manual/index.md` under the appropriate category
+
+#### 2. Creating an Auto-Review Finding
+For simple one-sentence findings:
+- Append to `local-file/tasks/auto-review/simple_advices.md`
+- Group by date, use 🟡 or 🔵 prefix
+
+For complex findings:
+- Create a detailed task file in `local-file/tasks/auto-review/`
+- Add to `auto-review/index.md`
+
+#### 3. Working on a Task
+- Update the Status field in the task file header as work progresses
+- Commit changes with descriptive messages
+
+#### 4. Completing a Task
+- Update Status to "Completed" in the task file header
+- Mark checkbox with `[x]` in the appropriate index
+- Add completion date: `— Completed: YYYY-MM-DD` (infer from git commit date if possible)
+- Commit the completion
+
+#### 5. Preparing a Release (Use Hook)
+When ready to release, trigger the "Prepare Release" hook which will:
+- Gather all completed manual tasks since last git tag
+- Generate formal CHANGELOG.md entries
+- Archive completed tasks to `local-file/tasks/releases/[version]/tasks/manual/` and `tasks/auto-review/`
+- Archive agentic worklog files to `local-file/tasks/releases/[version]/worklog/analysis/`, `worklog/drafts/`, and `worklog/summaries/`
+- Update manual task index to remove completed tasks
+- Create a clean slate for the next development cycle
+- Note: Simple advices are NOT archived — they remain as a running log
+
+### Categories
+
+- Features — New functionality
+- Bugs — Known issues to fix
+- Usability — CLI UX and output improvements
+- Documentation — Docs and README updates
+- Code Quality — Refactoring and technical debt
+
+### Conventions
+
+#### Task File Format
+- Header first: Title, Category, Status, Description at the top
+- Core sections: Motivation, Current Behavior, Expected Behavior, Proposed Solution
+- Keep implementation details minimal — they become stale quickly
+- Focus on "why" and "what", not detailed "how"
+
+#### Naming
+- Use format: `{verb}-{slug}.md` (e.g., `add-dry-run-mode.md`, `fix-path-resolution.md`)
+- Link tasks from the appropriate group index
+
+#### Auto-Review
+- Simple one-sentence findings go in `simple_advices.md`
+- Complex findings requiring detailed analysis get their own task files
+- Simple advices are NOT archived — they remain as a continuous running log
+
+#### Completion
+- Infer completion dates from git commit history when possible
+- Completed manual tasks remain in their group until the next release preparation
+- Completed auto-review detailed tasks CAN be archived
+
+---
+
+## Notes
+
+- All Kiro-generated content must be placed in the appropriate subdirectories
+- Do not scatter files in the `local-file/` root directory
+- Use descriptive filenames that clearly indicate content
+- Follow naming conventions for consistency

beyond_local_file-0.2.2/.kiro/steering/project_rules.md

@@ -0,0 +1,40 @@
+---
+inclusion: always
+---
+
+# Project Rules
+
+## 1. Environment & Tooling
+
+All Python development must use `uv` exclusively. No `pip`, `venv`, `poetry`, `conda`, or manual `python -m` calls.
+
+Common commands:
+- `uv add <package>` / `uv add --dev <package>`
+- `uv run ruff check --fix .` / `uv run ruff format .`
+- `uv run pytest`
+- `uv run python script.py`
+
+## 2. Code Quality
+
+- Follow Martin Fowler's refactoring principles — small, safe, behavior-preserving changes.
+- Keep code simple, readable, and self-documenting.
+- Single responsibility for functions and classes.
+- Avoid deep nesting, magic values, and unnecessary complexity.
+
+## 3. Linting & Formatting
+
+All code must pass Ruff with zero violations. Configuration lives in `pyproject.toml` under `[tool.ruff]`.
+
+- Auto-fix: `uv run ruff check --fix .` then `uv run ruff format .`
+- When suppressing a rule, add a comment explaining why (e.g. `# noqa: ANN001 -- click injects args at runtime`).
+
+## 4. Language
+
+All files — code, documentation, configuration, scripts, and any generated content — must be written in English unless the user explicitly requests Chinese.
+
+## 5. Fixed Option Values
+
+All fixed sets of option values (output formats, modes, strategies) must be defined as `StrEnum` members in `src/beyond_local_file/options.py`. No magic strings elsewhere.
+
+- Use `[f.value for f in MyEnum]` for `click.Choice` lists.
+- Coerce raw Click strings back to the enum at the CLI boundary: `MyEnum(raw_value)`.