handovergap 0.1.0__tar.gz

handovergap-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -e ".[dev,demo]"
+      - run: ruff check .
+      - run: pytest
+      - run: handovergap demo
+      - run: handovergap evaluate --compare
+
+  package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install build twine
+      - run: python -m build
+      - run: twine check dist/*
+      - uses: actions/upload-artifact@v7
+        with:
+          name: distributions
+          path: dist/

handovergap-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,49 @@
+name: Publish to PyPI
+
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: python -m pip install build twine
+      - run: python -m build
+      - run: twine check dist/*
+      - uses: actions/upload-artifact@v7
+        with:
+          name: distributions
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/handovergap
+    permissions:
+      id-token: write
+    env:
+      PYPI_API_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: distributions
+          path: dist/
+      - name: Publish to PyPI with API token
+        if: ${{ env.PYPI_API_TOKEN != '' }}
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ env.PYPI_API_TOKEN }}
+      - name: Publish to PyPI with trusted publishing
+        if: ${{ env.PYPI_API_TOKEN == '' }}
+        uses: pypa/gh-action-pypi-publish@release/v1

handovergap-0.1.0/.github/workflows/test-publish.yml

@@ -0,0 +1,50 @@
+name: Publish to TestPyPI
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: python -m pip install build twine
+      - run: python -m build
+      - run: twine check dist/*
+      - uses: actions/upload-artifact@v7
+        with:
+          name: test-distributions
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/handovergap
+    permissions:
+      id-token: write
+    env:
+      TEST_PYPI_API_TOKEN: ${{ secrets.TEST_PYPI_API_TOKEN }}
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: test-distributions
+          path: dist/
+      - name: Publish to TestPyPI with API token
+        if: ${{ env.TEST_PYPI_API_TOKEN != '' }}
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          password: ${{ env.TEST_PYPI_API_TOKEN }}
+      - name: Publish to TestPyPI with trusted publishing
+        if: ${{ env.TEST_PYPI_API_TOKEN == '' }}
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

handovergap-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.DS_Store
+.env
+build/
+dist/
+*.egg-info/

handovergap-0.1.0/AGENTS.md

@@ -0,0 +1,42 @@
+# AGENTS.md
+
+All agents must optimize for contest-winning evidence, not feature volume.
+
+## Core Thesis
+
+Correct memories are not always transferable.
+
+## Required Work Loop
+
+Plan -> Act -> Observe -> Validate -> Reflect -> Update Context -> Handoff
+
+Work one loop at a time.
+
+## Winning Filter
+
+Before implementing any feature, answer:
+
+```text
+Which article claim, evaluation metric, TiDB-specific learning, PyPI first-run experience, or demo clarity does this improve?
+```
+
+If the answer is unclear, do not implement it.
+
+## Forbidden in P0
+
+- real company data
+- employee scoring
+- OpenAI-required runtime
+- TiDB-required runtime
+- full web app
+- Slack/GitHub integration
+- broad refactors without validation
+
+## MVP Commands
+
+```bash
+handovergap demo
+handovergap detect --scenario S001 --role CS
+handovergap evaluate --compare
+pytest
+```

handovergap-0.1.0/CLAUDE.md

@@ -0,0 +1,80 @@
+# CLAUDE.md
+
+## Mission
+
+Build HandoverGap RAG as a contest-grade, PyPI-installable toolkit and mini benchmark.
+
+## Core Thesis
+
+Correct memories are not always transferable.
+
+## Working Contract
+
+For every task:
+
+1. State objective.
+2. Inspect required files.
+3. Implement smallest useful change.
+4. Validate.
+5. Update docs/tasks if behavior changed.
+6. Produce loop report.
+7. Stop.
+
+## Winning Mode
+
+Optimize for:
+
+- article claim
+- evaluation metric
+- TiDB-specific learning
+- PyPI first-run experience
+- demo clarity
+
+Do not optimize for feature count.
+
+## Required Framing
+
+Do not describe this as a generic RAG app.
+
+Describe it as:
+
+> A TiDB-backed evaluation toolkit for detecting when a retrieved organizational memory is correct but not yet transferable to a successor.
+
+## MVP Focus
+
+P0:
+
+- CLI
+- sample dataset
+- rule-based detector
+- baseline comparison
+- evaluation metrics
+- tests
+
+P1:
+
+- TiDB schema and optional store
+- Streamlit demo
+- PyPI package
+- article assets
+
+## Loop Report Format
+
+```md
+## Loop Report
+
+### Objective
+...
+
+### Files Changed
+...
+
+### Validation
+...
+
+### What This Improves for the Article
+...
+
+### Next Recommended Loop
+...
+```

handovergap-0.1.0/CODEX.md

@@ -0,0 +1,39 @@
+# CODEX.md
+
+## Mission
+
+Implement `handovergap`, a Python package and CLI for detecting tacit context gaps in handover-oriented RAG.
+
+## Priority Order
+
+1. CLI first-run experience
+2. evaluation reproducibility
+3. baseline comparison
+4. TiDB-specific implementation
+5. article assets
+6. demo polish
+
+## Core Commands
+
+```bash
+handovergap demo
+handovergap detect --scenario S001 --role CS
+handovergap evaluate --compare
+handovergap schema --dialect tidb
+```
+
+## Constraints
+
+- Python >= 3.10
+- Typer CLI
+- Pydantic v2
+- Rich output
+- pytest
+- no required external LLM in P0
+- no required TiDB in local MVP
+- synthetic data only
+
+## Stop Rule
+
+Do not move to the next loop automatically.  
+End with a loop report.

handovergap-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Masa Mura
+
+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.

handovergap-0.1.0/LOOP_ENGINEERING.md

@@ -0,0 +1,254 @@
+# Loop Engineering Harness
+
+This document defines the operating loop for AI coding agents working on HandoverGap RAG.
+
+## What Loop Engineering Means Here
+
+Loop engineering is not a task list.
+
+It is the design of a closed development loop where an AI agent repeatedly:
+
+```text
+Plan
+→ Act
+→ Observe
+→ Validate
+→ Reflect
+→ Update Context
+→ Handoff
+```
+
+The goal is to prevent the agent from drifting into broad, unverified implementation.
+
+Every loop must have:
+
+- objective
+- input files
+- output files
+- forbidden changes
+- validation commands
+- failure handling
+- context update rule
+- handoff format
+- stop condition
+
+## Global Loop Contract
+
+For every task, the agent must:
+
+1. Read the task contract.
+2. Restate the loop objective in one sentence.
+3. Inspect only the necessary files first.
+4. Prefer tests before implementation when possible.
+5. Implement the smallest useful change.
+6. Run the validation commands.
+7. If validation fails, fix the smallest cause only.
+8. Update docs or task status if behavior changed.
+9. Write a loop report.
+10. Stop.
+
+## Forbidden Behavior
+
+The agent must not:
+
+- implement multiple loops in one pass
+- introduce external LLM dependency in P0
+- require TiDB for local MVP
+- use real company or customer data
+- create employee scoring or surveillance features
+- silently change public CLI behavior
+- skip validation commands
+- hide failing tests
+- broaden the architecture without updating docs
+
+## Loop Types
+
+### Research Loop
+
+Purpose: Verify positioning and novelty.
+
+```text
+Hypothesis
+→ Related work / competitor check
+→ Difference statement
+→ Article thesis update
+→ Risk note
+```
+
+Output:
+
+- `docs/13_competitor_analysis.md`
+- `article/key_phrases.md`
+- `article/zenn_outline.md`
+
+### Product Loop
+
+Purpose: Improve 5-minute package experience.
+
+```text
+CLI idea
+→ Implement
+→ Run quickstart
+→ Observe friction
+→ Simplify
+→ Update README
+```
+
+Output:
+
+- CLI command
+- README quickstart
+- smoke test
+
+### Evaluation Loop
+
+Purpose: Make the claim measurable.
+
+```text
+Scenario
+→ Gold gaps
+→ Run baseline
+→ Run proposed method
+→ Compare
+→ Inspect failure
+→ Improve schema
+```
+
+Output:
+
+- benchmark scenarios
+- metrics
+- result table
+
+### Engineering Loop
+
+Purpose: Keep code maintainable.
+
+```text
+Test
+→ Implement
+→ Lint
+→ Smoke test
+→ Docs update
+→ Handoff
+```
+
+Output:
+
+- passing tests
+- small diff
+- loop report
+
+### Article Loop
+
+Purpose: Turn implementation results into article content.
+
+```text
+Draft claim
+→ Link to implementation result
+→ Add table/screenshot
+→ Remove unsupported claim
+→ Update article
+```
+
+Output:
+
+- article section
+- result table
+- screenshot checklist
+
+## Validation Levels
+
+### L0: Local Smoke
+
+```bash
+handovergap --help
+handovergap demo
+handovergap detect --scenario S001 --role CS
+handovergap evaluate
+```
+
+### L1: Test
+
+```bash
+pytest
+```
+
+### L2: Quality
+
+```bash
+ruff check .
+mypy src
+```
+
+### L3: Package
+
+```bash
+python -m build
+twine check dist/*
+```
+
+## Failure Handling
+
+### If tests fail
+
+Do not add new features.
+
+1. Identify the failing test.
+2. Explain the likely cause.
+3. Fix the smallest cause.
+4. Rerun the exact failing test.
+5. Rerun full tests if fixed.
+
+### If CLI UX is confusing
+
+1. Simplify command.
+2. Update README.
+3. Add smoke test.
+4. Do not add a new command unless necessary.
+
+### If novelty claim is unsupported
+
+1. Downgrade the claim.
+2. Add limitation.
+3. Add evaluation or evidence.
+4. Update article wording.
+
+### If TiDB integration blocks progress
+
+1. Keep InMemoryStore working.
+2. Add a clear TODO.
+3. Isolate TiDB-specific code.
+4. Do not break local MVP.
+
+## Loop Report Format
+
+At the end of every loop, produce:
+
+```md
+## Loop Report
+
+### Objective
+...
+
+### Files Changed
+- ...
+
+### Validation
+- [ ] command: result
+
+### Observations
+...
+
+### Failures
+...
+
+### Next Recommended Loop
+...
+```
+
+## Stop Rule
+
+Stop after one loop.
+
+If tempted to continue, write the next loop contract instead.