giton 0.1.2__tar.gz → 0.1.5__tar.gz

{giton-0.1.2 → giton-0.1.5}/.gitignore

@@ -1,4 +1,5 @@
 # Byte-compiled / optimized / DLL files
+.idea/misc.xml
 .idea/.name
 .idea/giton.iml
 .env.example

{giton-0.1.2 → giton-0.1.5}/.idea/workspace.xml

@@ -5,27 +5,37 @@
   </component>
   <component name="ChangeListManager">
     <list default="true" id="9532a670-1f01-4d5e-9501-f3491f105c64" name="Changes" comment="">
-      <change afterPath="$PROJECT_DIR$/.koru/event-store.jsonl" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/.koru/events/observability.jsonl" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/.koru/history.jsonl" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/.koru/onboarding.json" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/.koru/project.json" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/.planfile/.koru/autonomous-state.json" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/.planfile/.koru/autonomy-telemetry.json" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/.planfile/.koru/event-store.jsonl" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/.planfile/.koru/nfo-events.jsonl" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/.planfile/.koru/operator-steps/mcp_koru.ticket" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/.planfile/.koru/operator-steps/self_control.ticket" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/.planfile/.koru/queue-runner.lock" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/.planfile/.koru/serve-endpoint.json" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/.planfile/config.yaml" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/.planfile/sprints/current.yaml" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/.planfile/sprints/current.yaml.lock" afterDir="false" />
-      <change afterPath="$PROJECT_DIR$/koru.yaml" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/README.md" beforeDir="false" afterPath="$PROJECT_DIR$/README.md" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/examples/advanced/Dockerfile" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/examples/advanced/README.md" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/examples/advanced/logs/log.txt" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/examples/advanced/main.py" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/examples/basic/Dockerfile" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/examples/basic/README.md" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/examples/basic/logs/log.txt" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/examples/basic/main.py" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/examples/testing/Dockerfile" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/examples/testing/README.md" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/examples/testing/docker-compose.yml" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/examples/testing/logs/log.txt" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/examples/testing/sample_project/pyproject.toml" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/examples/testing/sample_project/src/example.py" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/examples/testing/sample_project/tests/test_example.py" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/examples/testing/test_giton_integration.py" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/src/giton/history.py" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/src/giton/interactive.py" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/src/giton/policies.py" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/src/giton/repo_config.py" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/tests/test_history.py" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/tests/test_policies.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/VERSION" beforeDir="false" afterPath="$PROJECT_DIR$/VERSION" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/goal.yaml" beforeDir="false" afterPath="$PROJECT_DIR$/goal.yaml" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/pyproject.toml" beforeDir="false" afterPath="$PROJECT_DIR$/pyproject.toml" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/src/gix/cli.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/gix/cli.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/src/giton/__init__.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/giton/__init__.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/src/giton/cli.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/giton/cli.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/src/giton/hooks.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/giton/hooks.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/src/giton/runner.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/giton/runner.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/src/giton/shell.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/giton/shell.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/uv.lock" beforeDir="false" afterPath="$PROJECT_DIR$/uv.lock" afterDir="false" />
     </list>
     <option name="SHOW_DIALOG" value="false" />
     <option name="HIGHLIGHT_CONFLICTS" value="true" />
@@ -45,61 +55,61 @@
   </component>
   <component name="NextEditCompletionFeaturesState">
     <decayedCancelled>
-      <entry key="MS100" value="1.3718424857785465" />
-      <entry key="MS500" value="3.3112573847521194" />
-      <entry key="S2" value="5.757179828705393" />
-      <entry key="S5" value="7.6841756824539456" />
-      <entry key="S10" value="8.699229618740706" />
-      <entry key="S30" value="9.717210745606021" />
-      <entry key="S60" value="11.113347666363076" />
-      <entry key="M2" value="13.75095879930024" />
-      <entry key="M5" value="17.495199423296118" />
-      <entry key="M10" value="19.469986695045137" />
-      <entry key="M15" value="20.244063435580596" />
-      <entry key="M30" value="21.085273253896926" />
-      <entry key="H1" value="21.53302338793371" />
-      <entry key="H2" value="21.76405315334236" />
-      <entry key="H4" value="21.881404889788154" />
-      <entry key="D1" value="21.98014719736049" />
-      <entry key="W1" value="21.997161747982677" />
+      <entry key="MS100" value="1.1840429966024764" />
+      <entry key="MS500" value="3.008906012331558" />
+      <entry key="S2" value="4.354063637612695" />
+      <entry key="S5" value="4.726721936322459" />
+      <entry key="S10" value="4.867729736902627" />
+      <entry key="S30" value="6.007189586843474" />
+      <entry key="S60" value="8.687315057904945" />
+      <entry key="M2" value="12.390366740242463" />
+      <entry key="M5" value="20.028499727277765" />
+      <entry key="M10" value="28.647532831651066" />
+      <entry key="M15" value="34.56395301166038" />
+      <entry key="M30" value="44.528965358361326" />
+      <entry key="H1" value="52.2573782114977" />
+      <entry key="H2" value="57.174224782901376" />
+      <entry key="H4" value="59.96191489846307" />
+      <entry key="D1" value="62.475178727914766" />
+      <entry key="W1" value="62.92455821571766" />
     </decayedCancelled>
     <decayedSelected>
       <entry key="MS100" value="0.0" />
       <entry key="MS500" value="0.0" />
-      <entry key="S2" value="0.0" />
-      <entry key="S5" value="0.0" />
-      <entry key="S10" value="0.0" />
-      <entry key="S30" value="0.0" />
-      <entry key="S60" value="0.0" />
-      <entry key="M2" value="0.0" />
-      <entry key="M5" value="0.0" />
-      <entry key="M10" value="0.0" />
-      <entry key="M15" value="0.0" />
-      <entry key="M30" value="0.0" />
-      <entry key="H1" value="0.0" />
-      <entry key="H2" value="0.0" />
-      <entry key="H4" value="0.0" />
-      <entry key="D1" value="0.0" />
-      <entry key="W1" value="0.0" />
+      <entry key="S2" value="1.750725986257552E-98" />
+      <entry key="S5" value="7.893820947435761E-40" />
+      <entry key="S10" value="2.8095944453667604E-20" />
+      <entry key="S30" value="3.0400533972351147E-7" />
+      <entry key="S60" value="5.513667923655825E-4" />
+      <entry key="M2" value="0.023481200828866962" />
+      <entry key="M5" value="0.22299140361394168" />
+      <entry key="M10" value="0.4722196561071362" />
+      <entry key="M15" value="0.6064049071866291" />
+      <entry key="M30" value="0.7787200441664701" />
+      <entry key="H1" value="0.8824511568163249" />
+      <entry key="H2" value="0.9393887144395157" />
+      <entry key="H4" value="0.9692206737577957" />
+      <entry key="D1" value="0.9948030578200769" />
+      <entry key="W1" value="0.9992559207852288" />
     </decayedSelected>
     <decayedShown>
-      <entry key="MS100" value="1.3130341694304903" />
-      <entry key="MS500" value="3.279711290013356" />
-      <entry key="S2" value="5.74254019350286" />
-      <entry key="S5" value="7.676080681885882" />
-      <entry key="S10" value="8.694587478942692" />
-      <entry key="S30" value="9.715431623419397" />
-      <entry key="S60" value="11.112211704324547" />
-      <entry key="M2" value="13.750130059214802" />
-      <entry key="M5" value="17.494711142555076" />
-      <entry key="M10" value="19.469700036990325" />
-      <entry key="M15" value="20.2438611107584" />
-      <entry key="M30" value="21.085165964837984" />
-      <entry key="H1" value="21.532968106864043" />
-      <entry key="H2" value="21.76402508981725" />
-      <entry key="H4" value="21.881390750497314" />
-      <entry key="D1" value="21.98014482572406" />
-      <entry key="W1" value="21.997161408805948" />
+      <entry key="MS100" value="1.1676890724774422" />
+      <entry key="MS500" value="3.0000523431376207" />
+      <entry key="S2" value="4.350775089905487" />
+      <entry key="S5" value="4.725285817140984" />
+      <entry key="S10" value="4.866969299487099" />
+      <entry key="S30" value="6.006050466143283" />
+      <entry key="S60" value="8.686237365128678" />
+      <entry key="M2" value="12.412310145277253" />
+      <entry key="M5" value="20.250271675744575" />
+      <entry key="M10" value="29.118834037658004" />
+      <entry key="M15" value="35.16962424632721" />
+      <entry key="M30" value="45.307228651231846" />
+      <entry key="H1" value="53.13956938106742" />
+      <entry key="H2" value="58.113473925261886" />
+      <entry key="H4" value="60.93106313433165" />
+      <entry key="D1" value="63.46996931990426" />
+      <entry key="W1" value="63.92381234570905" />
     </decayedShown>
   </component>
   <component name="ProjectColorInfo"><![CDATA[{

giton-0.1.5/CHANGELOG.md

@@ -0,0 +1,141 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.5] - 2026-05-27
+
+### Docs
+- Update README.md
+
+### Other
+- Update .idea/misc.xml
+
+## [0.1.4] - 2026-05-27
+
+### Docs
+- Update CHANGELOG.md
+- Update README.md
+- Update examples/advanced/README.md
+- Update examples/basic/README.md
+- Update examples/testing/README.md
+
+### Test
+- Update tests/test_history.py
+- Update tests/test_policies.py
+
+### Other
+- Update VERSION
+- Update examples/advanced/Dockerfile
+- Update examples/advanced/logs/log.txt
+- Update examples/advanced/main.py
+- Update examples/basic/Dockerfile
+- Update examples/basic/logs/log.txt
+- Update examples/basic/main.py
+- Update examples/testing/Dockerfile
+- Update examples/testing/docker-compose.yml
+- Update examples/testing/logs/log.txt
+- ... and 5 more files
+
+## [0.1.4] - 2026-05-27
+
+### Added
+- New `commit-msg` git hook: validates the message file before the
+  commit is finalized. Aborts with a tip when policies fail; user's
+  message is preserved so they can re-run `git commit`.
+  Installed automatically by `giton init`.
+- `giton fixup [--target SHA] [--yes]` — creates a `fixup!` commit
+  from the staged index, recording a backup ref under
+  `refs/giton/backup/fixup-<timestamp>` first.
+- New `giton history` sub-app:
+  - `history log [-n N] [-r RANGE]` — show commits eligible for push,
+    highlighting `fixup!` entries.
+  - `history clean [--base REF] [--yes] [-i]` — safe
+    `git rebase -i --autosquash` with backup ref
+    `refs/giton/backup/clean-<timestamp>` and headless edit by default
+    (`GIT_SEQUENCE_EDITOR=true GIT_EDITOR=true`).
+- New module `giton/history.py` with reusable primitives:
+  `head_sha`, `make_backup_ref`, `list_log`, `upstream_range`,
+  `create_fixup`, `has_staged_changes`, `autosquash`.
+- Tests: `tests/test_history.py` (8 cases) covering hook installation,
+  backup refs, fixup creation, autosquash, CLI fixup flow, and the
+  `commit-msg` hook on both invalid and valid subjects.
+
+### Changed
+- `policies.conventional_commits` and `policies.no_wip_commits` now
+  also fire on the `commit-msg` trigger.
+- `repo_config` defaults gained a `commit-msg` entry with
+  `fail_on_policy: true`.
+- Fixed `examples/testing/test_giton_integration.py`: positional
+  `policy check pre-commit` form replaced with `--trigger pre-commit`
+  and the result is now asserted.
+
+## [0.1.3] - 2026-05-27
+
+### Added
+- Built-in policy engine (`giton/policies.py`) with four checks:
+  `conventional_commits`, `no_wip_commits`, `no_secrets`,
+  `max_file_size`. Runs on every hook trigger, no plugins required.
+- Per-repo configuration file `.giton/config.yaml` with per-policy
+  options and per-trigger `fail_on_policy` switch (`giton/repo_config.py`).
+- New CLI sub-app `giton policy` with `check`, `init`, `list` commands.
+- Interactive helper `giton/interactive.py` (`confirm`, `choose`)
+  honouring `GITON_NON_INTERACTIVE` and TTY detection.
+- `runner.run_trigger` now returns a `TriggerOutcome` carrying both
+  policy findings and plugin results; hooks fail when
+  `fail_on_policy` and any error is present.
+- Tests: `tests/test_policies.py` covers all checks, repo-config
+  override semantics, and an end-to-end `run_trigger` flow.
+
+### Changed
+- `giton hook pre-commit` / `pre-push` now also evaluate built-in
+  policies; `post-commit` runs them advisory by default.
+- Shell REPL gained `policy list|check|init` commands.
+
+## [0.1.2] - 2026-05-27
+
+### Docs
+- Update CHANGELOG.md
+- Update README.md
+- Update TODO.md
+
+### Test
+- Update tests/test_basic.py
+
+### Other
+- Update .gitignore
+- Update .koru/event-store.jsonl
+- Update .koru/events/observability.jsonl
+- Update .koru/history.jsonl
+- Update .koru/onboarding.json
+- Update .koru/project.json
+- Update .planfile/.koru/autonomous-state.json
+- Update .planfile/.koru/autonomy-telemetry.json
+- Update .planfile/.koru/event-store.jsonl
+- Update .planfile/.koru/nfo-events.jsonl
+- ... and 9 more files
+
+## [0.1.1] - 2026-05-27
+
+### Docs
+- Update README.md
+
+### Test
+- Update tests/__init__.py
+- Update tests/test_basic.py
+
+### Other
+- Update .env.example
+- Update .idea/.gitignore
+- Update .idea/giton.iml
+- Update .idea/inspectionProfiles/Project_Default.xml
+- Update .idea/inspectionProfiles/profiles_settings.xml
+- Update .idea/modules.xml
+- Update .idea/pyProjectModel.xml
+- Update .idea/vcs.xml
+- Update uv.lock
+

{giton-0.1.2 → giton-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: giton
-Version: 0.1.2
+Version: 0.1.5
 Summary: Local AI layer for git: orchestrates policies & plugins between commit and push.
 Author: semcod
 Author-email: Tom Sapletta <tom@sapletta.com>
@@ -22,11 +22,11 @@ Description-Content-Type: text/markdown
 
 ## AI Cost Tracking
 
-![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.1.2-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
-![AI Cost](https://img.shields.io/badge/AI%20Cost-$0.41-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-3.0h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
+![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.1.5-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
+![AI Cost](https://img.shields.io/badge/AI%20Cost-$0.61-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-3.2h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
 
-- 🤖 **LLM usage:** $0.4093 (6 commits)
-- 👤 **Human dev:** ~$300 (3.0h @ $100/h, 30min dedup)
+- 🤖 **LLM usage:** $0.6123 (8 commits)
+- 👤 **Human dev:** ~$318 (3.2h @ $100/h, 30min dedup)
 
 Generated on 2026-05-27 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/qwen/qwen3-coder-next)
 
@@ -45,7 +45,7 @@ What is still missing is one local operator that:
 - cleans up history before `push`,
 - integrates plugins via MCP/REST/CLI/gRPC.
 
-## Proposed direction for `gix`
+## Proposed direction for `giton`
 
 1. **Local-first with safe defaults**
    - AI proposes changes, user approves them.
@@ -111,7 +111,7 @@ giton plugin install-category lang:python   # install everything for a language
 
 ### Default plugins
 
-The 3 plugins activated by `gix init` cover the most common
+The 3 plugins activated by `giton init` cover the most common
 day-to-day needs in a `commit → push` loop:
 
 | name      | category        | trigger      | role                                       |
@@ -145,6 +145,40 @@ giton> catalog
 giton> install prefact
 ```
 
+### Built-in policies
+
+`giton` ships with a small zero-dependency policy engine that runs on
+every hook trigger — even before any plugin is installed:
+
+- **`conventional_commits`** — subject must match
+  `type(scope)?: subject` and stay within `max_subject_length`.
+- **`no_wip_commits`** — blocks subjects matching `wip`, `tmp`, `xxx`, `fixme`.
+- **`no_secrets`** — scans staged additions for AWS keys, private-key
+  headers and `api_key=`/`secret=` patterns.
+- **`max_file_size`** — rejects staged files larger than `kb` (default 512 KB).
+
+Inspect or customize them per repo:
+
+```bash
+giton policy list                    # show active policies
+giton policy check -t pre-commit     # evaluate without running plugins
+giton policy init                    # write .giton/config.yaml
+```
+
+`.giton/config.yaml` is a deep-merge over the defaults — disable a
+single check or tweak `max_subject_length` without restating everything:
+
+```yaml
+policies:
+  no_wip_commits:
+    enabled: false
+  conventional_commits:
+    max_subject_length: 100
+hooks:
+  post-commit:
+    fail_on_policy: true   # turn advisory checks into blocking
+```
+
 ### Plugin contract
 
 A plugin is any executable command (CLI). The catalog entry declares its
@@ -156,6 +190,36 @@ Future exec types (`mcp`, `rest`) will share the same JSON in/out
 contract: input = git context + policy findings, output = list of
 proposed actions (patches, fixup commits, warnings).
 
+## Examples
+
+The `examples/` directory contains working demonstrations of giton:
+
+- **[examples/basic](examples/basic/)** - Basic usage example showing how to use giton as a Python library to collect git context, run triggers, and handle policy findings and plugin results. Can be run directly or with pytest.
+
+- **[examples/advanced](examples/advanced/)** - Advanced usage example demonstrating plugin management (add, remove, list), custom policy configuration, hook installation/uninstallation, and running multiple triggers in sequence.
+
+- **[examples/testing](examples/testing/)** - Testing example with pytest integration and Docker support. Shows how to integrate giton into CI/CD pipelines with containerized testing environments. Includes Dockerfile and docker-compose.yml for easy setup.
+
+### Running examples with Docker
+
+All examples include Dockerfiles for containerized execution:
+
+```bash
+# Basic example
+docker build -f examples/basic/Dockerfile -t giton-example-basic .
+docker run --rm -v $(pwd)/examples/basic/logs:/app/logs giton-example-basic
+
+# Advanced example
+docker build -f examples/advanced/Dockerfile -t giton-example-advanced .
+docker run --rm -v $(pwd)/examples/advanced/logs:/app/logs giton-example-advanced
+
+# Testing example
+docker build -f examples/testing/Dockerfile -t giton-test .
+docker run --rm -v $(pwd)/examples/testing/logs:/app/logs giton-test
+```
+
+See each example's README.md for detailed usage instructions.
+
 
 ## License
 

{giton-0.1.2 → giton-0.1.5}/README.md

@@ -3,11 +3,11 @@
 
 ## AI Cost Tracking
 
-![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.1.2-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
-![AI Cost](https://img.shields.io/badge/AI%20Cost-$0.41-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-3.0h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
+![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.1.5-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
+![AI Cost](https://img.shields.io/badge/AI%20Cost-$0.61-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-3.2h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
 
-- 🤖 **LLM usage:** $0.4093 (6 commits)
-- 👤 **Human dev:** ~$300 (3.0h @ $100/h, 30min dedup)
+- 🤖 **LLM usage:** $0.6123 (8 commits)
+- 👤 **Human dev:** ~$318 (3.2h @ $100/h, 30min dedup)
 
 Generated on 2026-05-27 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/qwen/qwen3-coder-next)
 
@@ -26,7 +26,7 @@ What is still missing is one local operator that:
 - cleans up history before `push`,
 - integrates plugins via MCP/REST/CLI/gRPC.
 
-## Proposed direction for `gix`
+## Proposed direction for `giton`
 
 1. **Local-first with safe defaults**
    - AI proposes changes, user approves them.
@@ -92,7 +92,7 @@ giton plugin install-category lang:python   # install everything for a language
 
 ### Default plugins
 
-The 3 plugins activated by `gix init` cover the most common
+The 3 plugins activated by `giton init` cover the most common
 day-to-day needs in a `commit → push` loop:
 
 | name      | category        | trigger      | role                                       |
@@ -126,6 +126,40 @@ giton> catalog
 giton> install prefact
 ```
 
+### Built-in policies
+
+`giton` ships with a small zero-dependency policy engine that runs on
+every hook trigger — even before any plugin is installed:
+
+- **`conventional_commits`** — subject must match
+  `type(scope)?: subject` and stay within `max_subject_length`.
+- **`no_wip_commits`** — blocks subjects matching `wip`, `tmp`, `xxx`, `fixme`.
+- **`no_secrets`** — scans staged additions for AWS keys, private-key
+  headers and `api_key=`/`secret=` patterns.
+- **`max_file_size`** — rejects staged files larger than `kb` (default 512 KB).
+
+Inspect or customize them per repo:
+
+```bash
+giton policy list                    # show active policies
+giton policy check -t pre-commit     # evaluate without running plugins
+giton policy init                    # write .giton/config.yaml
+```
+
+`.giton/config.yaml` is a deep-merge over the defaults — disable a
+single check or tweak `max_subject_length` without restating everything:
+
+```yaml
+policies:
+  no_wip_commits:
+    enabled: false
+  conventional_commits:
+    max_subject_length: 100
+hooks:
+  post-commit:
+    fail_on_policy: true   # turn advisory checks into blocking
+```
+
 ### Plugin contract
 
 A plugin is any executable command (CLI). The catalog entry declares its
@@ -137,6 +171,36 @@ Future exec types (`mcp`, `rest`) will share the same JSON in/out
 contract: input = git context + policy findings, output = list of
 proposed actions (patches, fixup commits, warnings).
 
+## Examples
+
+The `examples/` directory contains working demonstrations of giton:
+
+- **[examples/basic](examples/basic/)** - Basic usage example showing how to use giton as a Python library to collect git context, run triggers, and handle policy findings and plugin results. Can be run directly or with pytest.
+
+- **[examples/advanced](examples/advanced/)** - Advanced usage example demonstrating plugin management (add, remove, list), custom policy configuration, hook installation/uninstallation, and running multiple triggers in sequence.
+
+- **[examples/testing](examples/testing/)** - Testing example with pytest integration and Docker support. Shows how to integrate giton into CI/CD pipelines with containerized testing environments. Includes Dockerfile and docker-compose.yml for easy setup.
+
+### Running examples with Docker
+
+All examples include Dockerfiles for containerized execution:
+
+```bash
+# Basic example
+docker build -f examples/basic/Dockerfile -t giton-example-basic .
+docker run --rm -v $(pwd)/examples/basic/logs:/app/logs giton-example-basic
+
+# Advanced example
+docker build -f examples/advanced/Dockerfile -t giton-example-advanced .
+docker run --rm -v $(pwd)/examples/advanced/logs:/app/logs giton-example-advanced
+
+# Testing example
+docker build -f examples/testing/Dockerfile -t giton-test .
+docker run --rm -v $(pwd)/examples/testing/logs:/app/logs giton-test
+```
+
+See each example's README.md for detailed usage instructions.
+
 
 ## License
 

giton-0.1.5/VERSION

@@ -0,0 +1 @@
+0.1.5

giton-0.1.5/examples/advanced/Dockerfile

@@ -0,0 +1,33 @@
+FROM python:3.13-slim
+
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy giton source from parent directory (build context is project root)
+COPY ../../src/giton /app/src/giton
+COPY ../../pyproject.toml /app/pyproject.toml
+COPY ../../README.md /app/README.md
+
+# Install giton and dependencies
+RUN pip install --no-cache-dir -e .
+
+# Install pytest and testing dependencies
+RUN pip install --no-cache-dir pytest pytest-cov
+
+# Copy example files
+COPY examples/advanced/main.py /app/main.py
+
+# Create log directory
+RUN mkdir -p /app/logs
+
+# Set up git repository
+RUN git init && \
+    git config user.email "test@example.com" && \
+    git config user.name "Test User"
+
+# Default command - run example and save logs
+CMD bash -c "python main.py 2>&1 | tee /app/logs/log.txt"

giton-0.1.5/examples/advanced/README.md

@@ -0,0 +1,55 @@
+# Advanced Giton Example
+
+This example demonstrates advanced giton usage including:
+- Custom policy configuration
+- Plugin management
+- Programmatic hook installation
+- Interactive usage patterns
+
+## Setup
+
+```bash
+# Install giton with dev dependencies
+pip install giton[dev]
+
+# Initialize giton
+giton init
+```
+
+## Features Demonstrated
+
+The `main.py` script shows:
+- Loading and managing plugins
+- Custom policy evaluation
+- Installing/uninstalling git hooks
+- Running multiple triggers in sequence
+- Handling errors and edge cases
+
+## Running the example
+
+```bash
+cd examples/advanced
+python main.py
+```
+
+## Advanced Concepts
+
+### Policy Configuration
+Giton uses YAML-based policy files to define rules for:
+- Commit message conventions
+- Code quality standards
+- Security checks
+- Test coverage requirements
+
+### Plugin System
+Plugins can be:
+- CLI tools (exec type)
+- MCP servers
+- REST APIs
+- gRPC services
+
+### Hook Integration
+Giton installs git hooks that delegate to `giton hook <name>`:
+- `pre-commit`: Run checks before committing
+- `post-commit`: Analyze after commit
+- `pre-push`: Final validation before pushing