steersync 0.2.0__tar.gz → 0.4.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. {steersync-0.2.0 → steersync-0.4.0}/CHANGELOG.md +96 -0
  2. {steersync-0.2.0 → steersync-0.4.0}/PKG-INFO +167 -65
  3. {steersync-0.2.0 → steersync-0.4.0}/README.md +159 -58
  4. {steersync-0.2.0 → steersync-0.4.0}/pyproject.toml +23 -16
  5. steersync-0.4.0/scripts/prepare_release.py +226 -0
  6. {steersync-0.2.0 → steersync-0.4.0}/src/steersync/__init__.py +1 -1
  7. {steersync-0.2.0 → steersync-0.4.0}/src/steersync/cli.py +277 -11
  8. {steersync-0.2.0 → steersync-0.4.0}/src/steersync/config.py +136 -9
  9. {steersync-0.2.0 → steersync-0.4.0}/src/steersync/errors.py +6 -0
  10. steersync-0.4.0/src/steersync/gitlab.py +209 -0
  11. {steersync-0.2.0 → steersync-0.4.0}/src/steersync/gitops.py +64 -9
  12. {steersync-0.2.0 → steersync-0.4.0}/src/steersync/hooks.py +111 -20
  13. steersync-0.4.0/src/steersync/kiro_rules.py +819 -0
  14. steersync-0.4.0/src/steersync/kiro_version.py +269 -0
  15. {steersync-0.2.0 → steersync-0.4.0}/src/steersync/lint.py +242 -118
  16. {steersync-0.2.0 → steersync-0.4.0}/src/steersync/locking.py +2 -4
  17. {steersync-0.2.0 → steersync-0.4.0}/src/steersync/logging_utils.py +0 -2
  18. steersync-0.4.0/src/steersync/mcp_server.py +394 -0
  19. steersync-0.4.0/src/steersync/migrate.py +175 -0
  20. {steersync-0.2.0 → steersync-0.4.0}/src/steersync/paths.py +0 -2
  21. steersync-0.4.0/src/steersync/practices.py +522 -0
  22. steersync-0.4.0/src/steersync/resources/default_config.yaml +262 -0
  23. {steersync-0.2.0 → steersync-0.4.0}/src/steersync/steering.py +32 -7
  24. {steersync-0.2.0 → steersync-0.4.0}/src/steersync/sync.py +205 -16
  25. {steersync-0.2.0 → steersync-0.4.0}/steersync.example.yaml +16 -2
  26. {steersync-0.2.0 → steersync-0.4.0}/tests/conftest.py +7 -2
  27. steersync-0.4.0/tests/test_automation.py +491 -0
  28. {steersync-0.2.0 → steersync-0.4.0}/tests/test_cli.py +17 -7
  29. {steersync-0.2.0 → steersync-0.4.0}/tests/test_collections.py +49 -11
  30. {steersync-0.2.0 → steersync-0.4.0}/tests/test_config.py +7 -2
  31. steersync-0.4.0/tests/test_gitlab.py +188 -0
  32. {steersync-0.2.0 → steersync-0.4.0}/tests/test_gitops.py +20 -8
  33. {steersync-0.2.0 → steersync-0.4.0}/tests/test_hardening.py +4 -6
  34. {steersync-0.2.0 → steersync-0.4.0}/tests/test_hooks.py +27 -4
  35. steersync-0.4.0/tests/test_kiro_collections.py +156 -0
  36. steersync-0.4.0/tests/test_kiro_rules.py +341 -0
  37. steersync-0.4.0/tests/test_kiro_version.py +187 -0
  38. {steersync-0.2.0 → steersync-0.4.0}/tests/test_lint.py +14 -6
  39. steersync-0.4.0/tests/test_mcp_server.py +89 -0
  40. steersync-0.4.0/tests/test_migrate.py +111 -0
  41. steersync-0.4.0/tests/test_practices.py +213 -0
  42. steersync-0.4.0/tests/test_prepare_release.py +158 -0
  43. {steersync-0.2.0 → steersync-0.4.0}/tests/test_steering.py +0 -2
  44. {steersync-0.2.0 → steersync-0.4.0}/tests/test_sync.py +21 -6
  45. steersync-0.2.0/src/steersync/mcp_server.py +0 -171
  46. steersync-0.2.0/src/steersync/resources/default_config.yaml +0 -154
  47. steersync-0.2.0/tests/test_mcp_server.py +0 -58
  48. {steersync-0.2.0 → steersync-0.4.0}/.gitignore +0 -0
  49. {steersync-0.2.0 → steersync-0.4.0}/LICENSE +0 -0
  50. {steersync-0.2.0 → steersync-0.4.0}/src/steersync/__main__.py +0 -0
  51. {steersync-0.2.0 → steersync-0.4.0}/tests/__init__.py +0 -0
@@ -5,6 +5,102 @@ Keep a Changelog and the project uses semantic versioning.
5
5
 
6
6
  ## [Unreleased]
7
7
 
8
+ ## [0.4.0] - 2026-11-22
9
+
10
+ ### Added
11
+
12
+ - Collections for the rest of the committable Kiro configuration (Kiro IDE 1.5, Kiro CLI 3.5):
13
+ `workflows` (`.kiro/workflows/*.workflow.{json,yaml,yml}` and `~/.kiro/workflows`),
14
+ `sandbox` (`.kiro/settings/sandbox.json`), `kiroignore` (`.kiroignore` at any depth and
15
+ `~/.kiro/settings/kiroignore`) and the opt in `cli-settings` (`.kiro/settings/cli.json`).
16
+ `agents-md` now syncs nested `AGENTS.md` files, and `specs` syncs every file in a spec
17
+ directory (`bugfix.md`, metadata), not only markdown.
18
+ - Schema rules (`steersync.kiro_rules`): hooks need `version: "v1"` and a matching
19
+ `action.command` or `action.prompt`; integer timeouts; `confirm` only on `Stop` command
20
+ hooks; the `SessionEnd`, `PermissionRequest`, `PreCompact` and `PostCompact` triggers, with
21
+ CLI 2.x camelCase names flagged. Agents: V2 format (`toolsSettings` or `allowedTools`
22
+ without `permissions`) is an error because Kiro rewrites such files on load, plus checks
23
+ for `permissions.rules`, 2.x tool names, `use_aws`, `toolAliases`, `keyboardShortcut`,
24
+ resource schemes, home directory paths and inline V3 hooks, for JSON and Markdown agents.
25
+ `mcp.json`: literal secrets in `env`, `headers` and `oauth.clientSecret`, `oauth.mode`,
26
+ `clientMetadataUrl`, timeouts. `sandbox.json`, workspace `cli.json`, workflow recipes
27
+ (node types, unique ids, `repeat` limits, join policies, depth and size) and
28
+ `.kiroignore` syntax.
29
+ - Kiro CLI V3 harness detection: `steersync v3-status`, a harness section in `doctor`, the
30
+ `kiro_v3_status` MCP tool and a once a day reminder from the session hook. Uses only
31
+ `kiro-cli --version` and `kiro-cli settings`, never a chat session.
32
+ - `steersync migrate-hooks` converts `*.kiro.hook` files and CLI 2.x inline agent hooks into
33
+ standalone `.kiro/hooks/*.json` files (dry run by default).
34
+ - The `steersync-mcp` entry point, MCP tool titles and read only, destructive and idempotent
35
+ annotations, server version and title, `confirm` for a forced pull, and logs on stderr.
36
+
37
+ ### Changed
38
+
39
+ - The rendered `mcp.json` entry runs `uvx --from "steersync[mcp]==<version>" steersync mcp`
40
+ (the previous `uvx steersync mcp` lacked the `mcp` extra) and auto approves the read only
41
+ tools.
42
+ - Collections may share a directory when each selects its files by literal name and the
43
+ names do not overlap. Hidden files are synced when a pattern names them literally, and
44
+ excluded trees such as `node_modules` are no longer walked.
45
+ - Dependency floors: click 8.5.1, pydantic 2.14.4, PyYAML 6.0.4, pymarkdownlnt 0.9.42,
46
+ hatchling 1.33, pytest 9.2, ruff 0.17.6, bandit 1.9, pip-audit 2.10. pytest uses its
47
+ native TOML configuration, coverage must stay at 90 per cent, CI also tests Python 3.15
48
+ and runs ty as an advisory check, and `from __future__ import annotations` is gone
49
+ (Python 3.14 defers annotations).
50
+
51
+ ### Fixed
52
+
53
+ - The Kiro session hook command `steersync pull --quiet --best-effort` failed with "No such
54
+ option: --quiet"; `pull` now accepts `-q/--quiet`.
55
+ - `steersync lint FILE` crashed for a file outside the repository, and
56
+ `steersync lint --profile P DIR` used the steering file patterns for every profile.
57
+
58
+ ## [0.3.0] - 2026-10-13
59
+
60
+ ### Added
61
+
62
+ - Two more collections from the Kiro configuration scopes: `prompts` (`.kiro/prompts` and
63
+ `~/.kiro/prompts`, the saved prompts that become slash commands) and `agents-md` (the
64
+ `AGENTS.md` at the repository root). Legacy `.kiro.hook` files are picked up by the hooks
65
+ collection and flagged.
66
+ - Best practice validation. Every collection profile now reports warnings taken from the Kiro
67
+ documentation (steering file naming and `auto` descriptions, the `globs` key, always on
68
+ context budget, missing foundation files, agent tool wildcards and startup globs, inline
69
+ agent hooks on CLI 3.0, hook timeouts and legacy schemas, skill name and description
70
+ limits, machine specific paths in `mcp.json`, prompt name length) plus the `settings` and
71
+ `prompt` profiles. Warnings never block; thresholds live under `lint.practice_limits` and
72
+ `lint.practices: false` turns them off. The rules are listed in `docs/validation.md`.
73
+ - `steersync init` writes the Kiro `SessionStart` hook and registers the steersync MCP server
74
+ in `.kiro/settings/mcp.json` (other servers kept, an existing entry left alone), so a Kiro
75
+ session in any repository refreshes and loads the configuration without being asked.
76
+ `steersync lint` warns when either piece is missing.
77
+ - GitLab merge requests through the REST API: `steersync mr` and the `raise_merge_request`
78
+ MCP tool open or find the merge request for the proposal branch, `push` confirms or creates
79
+ it and prints the URL when the token is present. The token comes from `GITLAB_TOKEN` (name
80
+ configurable with `gitlab.token_env`); `gitlab.api_url`, `gitlab.project` and
81
+ `gitlab.target_branch` are derived from `remote.url` and `remote.default_branch` unless set.
82
+ - `push` and `status` list other proposal branches of the same project still on the central
83
+ remote and warn about them (`branch.warn_existing`).
84
+ - Offline fallback: when the central repository is unreachable and a cache clone exists,
85
+ `pull` and `status` apply the cached default branch and say so (`sync.offline_fallback`).
86
+ `pull --best-effort` runs with the hook time budget.
87
+ - Automatic releases: merging a pull request to `main` computes the version from a
88
+ `release:*` label, a Conventional Commits title prefix or the Unreleased changelog section,
89
+ commits the changelog and version bump, publishes to PyPI and creates the tag and GitHub
90
+ release in the same run (`scripts/prepare_release.py`).
91
+
92
+ ### Changed
93
+
94
+ - Proposal branches are named `kiro-config/{project}/{user}-{hash}`; `{user}` now prefers the
95
+ operating system user name (letters, digits and dashes), then the git email, then the git
96
+ name (`branch.user_from`). The template must keep `{project}` and `{hash}`.
97
+ - MCP tools are named by intent and described for the agent: `pull_kiro_config`,
98
+ `push_kiro_config`, `raise_merge_request`, `diff_kiro_config`, `validate_kiro_config` and
99
+ `list_kiro_collections` replace `pull_steering`, `push_steering`, `diff_steering` and
100
+ `lint_steering`. The rendered `mcp.json` entry forwards the GitLab token variable.
101
+ - `pull` logs the central content's lint errors and a one line count of warnings instead of
102
+ every warning.
103
+
8
104
  ## [0.2.0] - 2026-10-12
9
105
 
10
106
  ### Added
@@ -1,7 +1,7 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: steersync
3
- Version: 0.2.0
4
- Summary: Sync Kiro steering documents between developer machines and a central git repository.
3
+ Version: 0.4.0
4
+ Summary: Sync Kiro configuration (steering, specs, skills, agents, hooks, workflows, settings) with a central git repository.
5
5
  Project-URL: Homepage, https://github.com/SCGIS-Wales/steersync
6
6
  Project-URL: Repository, https://github.com/SCGIS-Wales/steersync
7
7
  Project-URL: Issues, https://github.com/SCGIS-Wales/steersync/issues
@@ -9,7 +9,7 @@ Project-URL: Changelog, https://github.com/SCGIS-Wales/steersync/blob/main/CHANG
9
9
  Author-email: Dejan Gregor <dejan.gregor@gmail.com>
10
10
  License-Expression: Apache-2.0
11
11
  License-File: LICENSE
12
- Keywords: developer-experience,git,kiro,mcp,pre-push,steering
12
+ Keywords: agents,developer-experience,git,hooks,kiro,kiro-cli,mcp,pre-push,steering,workflows
13
13
  Classifier: Development Status :: 4 - Beta
14
14
  Classifier: Environment :: Console
15
15
  Classifier: Intended Audience :: Developers
@@ -17,22 +17,26 @@ Classifier: Operating System :: OS Independent
17
17
  Classifier: Programming Language :: Python :: 3
18
18
  Classifier: Programming Language :: Python :: 3 :: Only
19
19
  Classifier: Programming Language :: Python :: 3.14
20
+ Classifier: Programming Language :: Python :: 3.15
20
21
  Classifier: Topic :: Software Development :: Version Control :: Git
21
22
  Classifier: Typing :: Typed
22
23
  Requires-Python: >=3.14
23
- Requires-Dist: click<9,>=8.5
24
- Requires-Dist: pydantic<3,>=2.14
25
- Requires-Dist: pymarkdownlnt<1,>=0.9.40
24
+ Requires-Dist: click<9,>=8.5.1
25
+ Requires-Dist: pydantic<3,>=2.14.4
26
+ Requires-Dist: pymarkdownlnt<1,>=0.9.42
26
27
  Requires-Dist: python-frontmatter<2,>=1.3
27
- Requires-Dist: pyyaml<7,>=6.0.3
28
+ Requires-Dist: pyyaml<7,>=6.0.4
28
29
  Provides-Extra: mcp
29
30
  Requires-Dist: mcp<3,>=2.3; extra == 'mcp'
30
31
  Description-Content-Type: text/markdown
31
32
 
32
33
  # steersync
33
34
 
34
- Sync the whole [Kiro](https://kiro.dev) `.kiro/` configuration, steering, specs, skills,
35
- agents, hooks and settings, between developer machines and a central git repository. A plain
35
+ Sync the whole [Kiro](https://kiro.dev) `.kiro/` configuration (steering, specs, skills,
36
+ agents, hooks, settings, the sandbox policy, workflow recipes, prompts, `AGENTS.md` and
37
+ `.kiroignore` files) between developer machines and a central git repository. It targets Kiro
38
+ IDE 1.5 and Kiro CLI 3.5 with the V3 agent harness, and reminds you when a machine is still
39
+ on V2. A plain
36
40
  Python CLI runs from a git pre-push hook and shells out to the `git` binary, so your existing
37
41
  SSH agent or credential helper does the authentication. An MCP server and Kiro session hooks
38
42
  are optional layers on top of the same core.
@@ -55,18 +59,35 @@ layout; each one is configurable and new ones are added with a single YAML block
55
59
  | Collection | Workspace | Global (`~/.kiro`) | Central directory | Files | Lint profile |
56
60
  |---|---|---|---|---|---|
57
61
  | `steering` | `.kiro/steering` | `steering` | `steering/` | `**/*.md` | `steering`: Kiro front matter, references, secrets, markdown |
58
- | `specs` | `.kiro/specs` | none | `specs/` | `**/*.md` | `markdown`: secrets and markdown style |
62
+ | `specs` | `.kiro/specs` | none | `specs/` | every file in each spec (`requirements.md` or `bugfix.md`, `design.md`, `tasks.md`, metadata) | `markdown`: secrets and markdown style |
59
63
  | `skills` | `.kiro/skills` | `skills` | `skills/` | everything (`SKILL.md`, `scripts/`, `references/`, `assets/`) | `skill`: `SKILL.md` needs `name` and `description`, secrets in scripts |
60
- | `agents` | `.kiro/agents` | `agents` | `agents/` | `**/*.json`, `**/*.md` | `agent`: valid JSON with a `name`, flags deprecated `toolsSettings` |
61
- | `hooks` | `.kiro/hooks` | `hooks` | `hooks/` | `**/*.json` | `hooks`: `version`, `hooks[]` with `name`, `trigger`, `action` |
62
- | `settings` | `.kiro/settings` | none | `settings/` | `lsp.json`, `mcp.json` | `json`: valid JSON and secrets |
63
-
64
- Execute bits on skill scripts survive the round trip, hidden files are never synced, and
65
- files a collection's patterns do not select are never touched on either side. Limit any
64
+ | `agents` | `.kiro/agents` | `agents` | `agents/` | `**/*.json`, `**/*.md` (not the `*.json.bak` upgrade backups) | `agent`: V3 universal format, `permissions.rules`, tool names, resources, inline hooks |
65
+ | `hooks` | `.kiro/hooks` | `hooks` | `hooks/` | `**/*.json`, legacy `**/*.kiro.hook` | `hooks`: `version: v1`, triggers, actions, timeouts, `confirm` |
66
+ | `settings` | `.kiro/settings` | none | `settings/` | `lsp.json`, `mcp.json` | `settings`: shapes, literal secrets, OAuth, machine paths |
67
+ | `sandbox` | `.kiro/settings` | none | `sandbox/` | `sandbox.json` | `settings`: `enabled`, `networkAccess` |
68
+ | `cli-settings` (off by default) | `.kiro/settings` | none | `cli-settings/` | `cli.json` | `settings`: rejects global only keys such as `chat.agentEngine` |
69
+ | `workflows` | `.kiro/workflows` | `workflows` | `workflows/` | `**/*.workflow.json`, `.yaml`, `.yml` | `workflow`: the recipe schema of Kiro CLI 3.5 |
70
+ | `prompts` | `.kiro/prompts` | `prompts` | `prompts/` | `**/*.md` | `prompt`: markdown plus the 50 character name limit |
71
+ | `agents-md` | the repository | none | `agents-md/` | `**/AGENTS.md` (root and nested) | `markdown` (kept in the project repository too) |
72
+ | `kiroignore` | the repository | `settings` (`kiroignore`) | `kiroignore/` | `**/.kiroignore` | `kiroignore`: gitignore syntax, advice on `.env*` and `*.pem` |
73
+
74
+ Execute bits on skill scripts survive the round trip. Hidden directories are never synced,
75
+ and a hidden file only when a pattern names it (`**/.kiroignore`). Files a collection's
76
+ patterns do not select are never touched on either side, which is why `settings`, `sandbox`
77
+ and `cli-settings` can share `.kiro/settings`. The repository wide collections skip
78
+ `node_modules`, virtual environments, `dist`, `build` and `target` without walking them. Limit any
66
79
  command to some collections with `--collection NAME` (repeatable), list them with
67
80
  `steersync config collections`, and see [docs/central-layout.md](docs/central-layout.md) for
68
81
  a worked example of a full `.kiro/` tree in the central repository.
69
82
 
83
+ Never synced, by design: workspace permissions (`~/.kiro/workspace-roots/<hash>/permissions.yaml`,
84
+ kept per user so that a cloned repository cannot inject permission rules) and
85
+ `~/.kiro/settings/permissions.yaml`, `~/.kiro/powers/` (installed from a registry),
86
+ `~/.kiro/memories/`, `~/.kiro/sessions/`, `~/.kiro/crew/`, `~/.kiro/settings/cli.json`,
87
+ `managed-settings.json` and knowledge base indexes (the declarations in agent `resources`
88
+ are synced with the agent). Every path above comes from
89
+ the Kiro configuration scopes documentation; a new kind of content is one YAML block.
90
+
70
91
  ## Install
71
92
 
72
93
  Requires Python 3.14 or newer and git 2.18 or newer. Every
@@ -74,8 +95,11 @@ Requires Python 3.14 or newer and git 2.18 or newer. Every
74
95
  sdist and a `SHA256SUMS` file, with signed build provenance.
75
96
 
76
97
  ```bash
77
- VERSION=0.2.0
98
+ VERSION=0.4.0
78
99
  uv tool install "https://github.com/SCGIS-Wales/steersync/releases/download/v${VERSION}/steersync-${VERSION}-py3-none-any.whl"
100
+ # or run it without installing
101
+ uvx steersync --help
102
+ uvx --from "steersync[mcp]" steersync-mcp
79
103
  # with the MCP server
80
104
  uv tool install "steersync[mcp] @ https://github.com/SCGIS-Wales/steersync/releases/download/v${VERSION}/steersync-${VERSION}-py3-none-any.whl"
81
105
  # verify where the wheel came from
@@ -103,7 +127,9 @@ files that the GitHub release carries.
103
127
  2. Prepare a project. This adds every synced directory (`.kiro/steering/`, `.kiro/specs/`,
104
128
  `.kiro/skills/`, ...) and the lock file to `.git/info/exclude` (so centrally managed
105
129
  content is never committed to the project by accident; set `git_exclude: false` on a
106
- collection to keep committing it) and installs a chaining pre-push hook:
130
+ collection to keep committing it), installs a chaining pre-push hook, writes the Kiro
131
+ `SessionStart` hook that pulls at every session start and registers the steersync MCP
132
+ server in `.kiro/settings/mcp.json`:
107
133
 
108
134
  ```bash
109
135
  cd ~/code/my-service
@@ -113,9 +139,28 @@ files that the GitHub release carries.
113
139
 
114
140
  3. Edit anything under `.kiro/`. On your next `git push`, or on demand with
115
141
  `steersync push`, every collection is proposed to the central repository as one merge
116
- request.
142
+ request. With `GITLAB_TOKEN` exported, the merge request URL is printed and
143
+ `steersync mr` opens or finds it at any time.
144
+
145
+ Run `steersync doctor` at any time to see what steersync has resolved, and `steersync lint`
146
+ to validate the configuration against Kiro's rules and best practices.
147
+
148
+ ## Starting Kiro in any repository
149
+
150
+ The goal is that anyone who clones a project and starts Kiro gets the whole configuration
151
+ without asking for it. `steersync init` makes that true for a repository:
152
+
153
+ | Piece | What it does | Written by |
154
+ |---|---|---|
155
+ | `.kiro/hooks/steersync.json` | A V3 `SessionStart` hook running `steersync pull --quiet --best-effort`, so the session starts from the latest merged configuration. Bounded git time; never fails the session. | `steersync init` (or `steersync kiro-hook --write`) |
156
+ | `.kiro/settings/mcp.json` | The steersync MCP server, so "pull the kiro config", "push my steering", "raise an MR for the kiro config" or "validate the agents" work in chat. | `steersync init` (merged into an existing file, other servers kept) |
157
+ | `.git/hooks/pre-push` | Proposes `.kiro/` on every push of the project. | `steersync init --hook` |
117
158
 
118
- Run `steersync doctor` at any time to see what steersync has resolved.
159
+ Kiro then loads what it finds: always on steering in every session, `fileMatch`, `manual`
160
+ and `auto` steering on CLI V3, skills on demand, prompts as slash commands, hooks and
161
+ settings. `steersync lint` warns (`autoload-hook-missing`, `autoload-mcp-missing`) when a
162
+ repository lacks either piece. On CLI 2.x, where standalone hooks do not exist, paste
163
+ `steersync kiro-hook --engine v2` into the custom agent's `hooks` block.
119
164
 
120
165
  ## Central repository layout
121
166
 
@@ -150,13 +195,16 @@ subdirectory; `pull` and `status` print a warning pointing at them until that is
150
195
  | `steersync push [--dry-run] [--scope global] [--no-lint] [-m MSG] [-c NAME] [--json]` | Propose local collections centrally in one branch. `--from-hook` is used by git hooks and never blocks the push unless strict. |
151
196
  | `steersync status [-c NAME] [--json]` | Show adds, updates, deletes and local edits per collection in both directions. |
152
197
  | `steersync lint [PATHS] [-c NAME] [--profile P] [--json]` | Validate every collection with its profile, or explicit paths. Exit code 4 on errors. |
153
- | `steersync init [--write-config] [--hook] [--no-exclude]` | Prepare a repository. |
198
+ | `steersync mr [--branch NAME] [--title T] [-c NAME] [--json]` | Open, or find, the GitLab merge request for the pushed proposal branch. Needs the token in `GITLAB_TOKEN` (configurable). |
199
+ | `steersync init [--write-config] [--hook] [--no-exclude] [--no-kiro] [--mcp-command PATH]` | Prepare a repository: excludes, git hook, Kiro session hook and MCP server entry. |
154
200
  | `steersync install-hook [--force]` | Install or update the chaining pre-push hook. |
155
201
  | `steersync kiro-hook [--engine v2\|v3] [--write]` | Render a Kiro hook that runs `steersync pull --quiet` at session start. |
156
- | `steersync mcp-config [--remote URL]` | Render an `mcp.json` fragment. |
157
- | `steersync mcp` | Run the MCP stdio server. |
202
+ | `steersync migrate-hooks [--write]` | Convert `*.kiro.hook` files and CLI 2.x inline agent hooks into `.kiro/hooks/*.json`. Dry run by default; never overwrites or deletes. |
203
+ | `steersync v3-status [--json] [--strict]` | Report the kiro-cli version, `chat.agentEngine` and agents still in the V2 format. `--strict` exits 10 when a reminder applies. |
204
+ | `steersync mcp-config [--command uvx] [--remote URL]` | Render an `mcp.json` fragment. |
205
+ | `steersync mcp` (or `steersync-mcp`) | Run the MCP stdio server. |
158
206
  | `steersync config show\|validate\|default\|collections` | Inspect configuration and the resolved collection directories. |
159
- | `steersync doctor` | Report git version, resolved paths, remote and project slug. |
207
+ | `steersync doctor` | Report git version, resolved paths, remote, project slug and the Kiro CLI harness. |
160
208
 
161
209
  Global options: `--config PATH`, `--log-level`, `--log-format text|json`, `--quiet`.
162
210
 
@@ -176,6 +224,8 @@ for the packaged defaults.
176
224
  | `STEERSYNC_GIT_BINARY` | `git.binary` |
177
225
  | `STEERSYNC_LOG_LEVEL`, `STEERSYNC_LOG_FORMAT` | `logging.*` |
178
226
  | `STEERSYNC_STRICT` | `hook.strict` |
227
+ | `STEERSYNC_GITLAB_API_URL`, `STEERSYNC_GITLAB_PROJECT` | `gitlab.api_url`, `gitlab.project` |
228
+ | `GITLAB_TOKEN` (name set by `gitlab.token_env`) | Token with the `api` scope used only for merge requests |
179
229
  | `KIRO_HOME` | Location of `~/.kiro`, as honoured by kiro-cli |
180
230
 
181
231
  Unknown keys, invalid patterns, unsafe paths and malformed push options are rejected at load
@@ -221,6 +271,8 @@ share a directory on either side.
221
271
  | A failed push always resets the cache clone to a clean default branch. | automatic |
222
272
  | From a pre-push hook each git call is capped and retried at most once, and no failure, including an unexpected bug, blocks the push unless strict mode is on. | `hook.timeout_seconds`, `hook.strict` |
223
273
  | Central and local content larger than the limits is refused. | `sync.max_files`, `sync.max_total_bytes` |
274
+ | When the central repository cannot be reached and a cache clone exists, `pull` and `status` apply the cached copy of the default branch and say so (`offline` in JSON output). Permanent errors such as authentication failures still fail, and `push` never uses the cache. | `sync.offline_fallback` |
275
+ | `pull --best-effort` (the Kiro session hook) runs with the hook time budget, so a slow server never stalls a session start. | `hook.timeout_seconds` |
224
276
 
225
277
  ## How pull decides what to write
226
278
 
@@ -257,7 +309,7 @@ Teams that already use [pre-commit](https://pre-commit.com) can use the publishe
257
309
  default_install_hook_types: [pre-commit, pre-push]
258
310
  repos:
259
311
  - repo: https://github.com/SCGIS-Wales/steersync
260
- rev: v0.2.0
312
+ rev: v0.4.0
261
313
  hooks:
262
314
  - id: steersync-push
263
315
  - id: steersync-lint
@@ -266,52 +318,102 @@ repos:
266
318
  The lint hook receives the changed files under `.kiro/` and lints each with the profile of
267
319
  the collection it belongs to.
268
320
 
269
- ## GitLab merge requests
270
-
271
- The default push options create a merge request against the default branch, remove the source
272
- branch on merge and set a title. Branch names follow `steering/{project}/{user}-{hash}`, where
273
- the hash covers every file, so two people proposing identical content share one branch and a
274
- second identical push is reported as `already-proposed`. Servers that do not advertise push
275
- options (GitHub, plain bare repositories) make git fail, so steersync retries once without them
276
- and says so. Push options may use `{default_branch}`, `{project}`, `{user}` and `{hash}`.
321
+ ## Proposal branches and GitLab merge requests
277
322
 
278
- ## Lint rules
323
+ Pulls always come from the central repository's default branch (`remote.default_branch`,
324
+ `main` unless configured). Pushes go to a proposal branch named after the project repository
325
+ you are working in:
279
326
 
280
- Each collection runs one lint profile. The `steering` profile applies every rule below.
281
- `markdown` (specs, prompts, references) applies the encoding, size, secret and markdown rules
282
- without Kiro front matter checks. `skill` adds `skill-front-matter-required`,
283
- `skill-requires-metadata` and `skill-name-mismatch` for `SKILL.md`. `json` adds `json-syntax`,
284
- `hooks` adds `hook-schema`, `hook-trigger` and `hook-action`, `agent` adds `agent-schema`,
285
- `agent-name` and `agent-deprecated-key`, and `generic` only enforces the size limit and secret
286
- scanning, allowing binary assets. New profiles are one function in `steersync.lint.PROFILES`.
327
+ ```text
328
+ kiro-config/{project}/{user}-{hash}
329
+ kiro-config/acme/platform/entra-app-registration/dgregor-3f9a1c2e
330
+ ```
287
331
 
288
- | Rule | Severity | Check |
289
- |---|---|---|
290
- | `front-matter-position` | error | Front matter must start on line 1; Kiro ignores it after a blank line. |
291
- | `front-matter-yaml` | error | Front matter must be valid YAML. |
292
- | `inclusion-value` | error | `inclusion` is `always`, `fileMatch`, `manual` or `auto`. |
293
- | `filematch-pattern-required`, `filematch-pattern-type` | error | `fileMatch` needs a string or list of strings. |
294
- | `auto-requires-metadata` | error | `auto` needs `name` and `description`. |
295
- | `unknown-key` | warning | Keys Kiro does not know are ignored; `x-steersync` is allowed. |
296
- | `encoding-utf8`, `max-size` | error | UTF-8 only; default limit 64 KiB because always included bytes cost context. |
297
- | `require-h1` | warning | A level one heading is expected. |
298
- | `file-reference-missing`, `file-reference-escape` | warning, error | `#[[file:path]]`, `#[[file:path:line]]`, `#[[file:path:start-end]]` and `#[[folder:path]]` targets must exist inside the workspace. |
299
- | `forbidden-*` | error | AWS keys, private keys, GitHub, GitLab and Slack tokens, generic credentials. Patterns are configurable. |
300
- | `markdown-MD*` | configurable | pymarkdown rules with the front matter extension enabled. |
332
+ `{project}` is the slug of the project's origin URL, `{user}` comes from the sources listed
333
+ in `branch.user_from` (the operating system user name first, reduced to letters, digits and
334
+ dashes, then the local part of the git `user.email`, then the git `user.name`) and `{hash}`
335
+ covers every synced file, so two people proposing identical content share one branch and a
336
+ second identical push is reported as `already-proposed`. The template is configurable; it
337
+ must keep `{project}` and `{hash}`.
338
+
339
+ Before pushing, steersync lists the other proposal branches of the same project still on
340
+ the remote and warns about them, so unmerged work is reviewed before more is added
341
+ (`branch.warn_existing`). `steersync status` prints the same list.
342
+
343
+ The merge request is opened in two ways:
344
+
345
+ 1. **Push options.** The default `remote.push_options` ask GitLab to create a merge request
346
+ against the default branch, remove the source branch on merge and set a title. Servers
347
+ that do not advertise push options (GitHub, plain bare repositories) make git fail, so
348
+ steersync retries once without them and says so.
349
+ 2. **GitLab API.** When the token variable is set (`GITLAB_TOKEN`, name configurable with
350
+ `gitlab.token_env`), `push` confirms or creates the merge request through the REST API and
351
+ prints its URL, and `steersync mr` (or the `raise_merge_request` MCP tool) does the same on
352
+ demand. The API base URL and project path are derived from `remote.url` and can be set
353
+ with `gitlab.api_url` and `gitlab.project`; `gitlab.target_branch` defaults to
354
+ `remote.default_branch`. The token is read from the environment only, never from a file,
355
+ and never logged.
356
+
357
+ ## Validation
358
+
359
+ Each collection runs one lint profile: `steering`, `agent`, `hooks`, `skill`, `settings`,
360
+ `prompt`, `workflow`, `kiroignore`, `markdown`, `json` or `generic`. **Errors** are things
361
+ Kiro cannot read or would rewrite (front matter after a blank line, an unknown inclusion
362
+ mode, invalid JSON, a `SKILL.md` without `name` and `description`, a hook without
363
+ `version: "v1"`, a workflow `repeat` without `maxIterations`, an unknown sandbox
364
+ `networkAccess`, a V2 format agent) or secrets, including literal tokens in `mcp.json`
365
+ `env`, `headers` and `oauth.clientSecret`; they stop a push. **Warnings** are best practices from
366
+ the Kiro documentation, reported objectively and never blocking: a steering file with a
367
+ numeric prefix, an `auto` description that is not written as a trigger, a `globs` key where
368
+ Kiro reads `fileMatchPattern`, an agent with `tools: ["*"]` or a `file://.kiro/steering/**`
369
+ resource that loads everything at startup, inline agent hooks on CLI 3.0, a hook with a
370
+ 15 minute timeout, a skill name that is not kebab case, an `mcp.json` with a home directory
371
+ path, more than 48 KiB of always on steering, missing `product.md`, `tech.md` and
372
+ `structure.md`. Every rule, its severity and the documentation page it comes from are listed
373
+ in [docs/validation.md](docs/validation.md); thresholds live under `lint.practice_limits`
374
+ and `lint.practices: false` turns the warnings off.
301
375
 
302
376
  ## Kiro integration
303
377
 
304
- **Session hook (V3).** `steersync kiro-hook --write` creates `.kiro/hooks/steersync.json` with a
305
- `SessionStart` trigger that runs `steersync pull --quiet --best-effort`. For CLI 2.x agents paste the output of
306
- `steersync kiro-hook --engine v2` into the agent's `hooks` block. Field reports say Kiro hooks fire
307
- only in headless runs or with a custom agent active, so treat them as a convenience and keep the
308
- git hook as the dependable trigger.
309
-
310
- **MCP server.** Add the fragment from `steersync mcp-config` to `.kiro/settings/mcp.json`. The
311
- server exposes `pull_steering`, `push_steering`, `diff_steering` and `lint_steering`. Kiro does
312
- not pass the shell's `PATH`, `SSH_AUTH_SOCK` or proxy variables to MCP servers, so the rendered
313
- fragment forwards them explicitly through `env`; use an absolute `--command` if `uvx` is not on
314
- Kiro's path.
378
+ **Session hook (V3).** `steersync init` (or `steersync kiro-hook --write`) creates
379
+ `.kiro/hooks/steersync.json` with a `SessionStart` trigger that runs
380
+ `steersync pull --quiet --best-effort`. For CLI 2.x agents paste the output of
381
+ `steersync kiro-hook --engine v2` into the agent's `hooks` block. Field reports say Kiro hooks
382
+ fire only in headless runs or with a custom agent active, so treat them as a convenience and
383
+ keep the git hook as the dependable trigger.
384
+
385
+ **Kiro CLI V3.** Kiro CLI 3.0.0 made V3 the default agent harness; V2 still runs but gets no
386
+ new features. `steersync doctor`, `steersync v3-status`, the `kiro_v3_status` MCP tool and
387
+ the session hook (at most once a day) check `kiro-cli --version`, `chat.agentEngine` and your
388
+ agent files. When a reminder applies, run `kiro-cli settings chat.agentEngine v3`, start
389
+ `kiro-cli` and run `/upgrade-agent`; for a shared agent directory run
390
+ `kiro-cli agent upgrade <dir>`. See <https://kiro.dev/docs/cli/v3/>. The probes never start a
391
+ chat, so they use no Kiro credits, and a reminder never fails a sync. Set
392
+ `STEERSYNC_NO_V3_REMINDER=1` to silence the session hook reminder.
393
+
394
+ **MCP server.** `steersync init` registers the server in `.kiro/settings/mcp.json`
395
+ (`steersync mcp-config` prints the fragment). It runs through
396
+ `uvx --from "steersync[mcp]==<version>" steersync mcp`, so nothing needs installing, and it
397
+ auto approves only the read only tools. The server is built on the MCP Python SDK v2
398
+ (`MCPServer`, specification 2026-07-28): tools return structured JSON and carry titles and
399
+ read only, destructive and idempotent hints. A forced pull needs `confirm: true` because it
400
+ overwrites local edits. The server tells the agent which tool answers
401
+ which request, so plain sentences work:
402
+
403
+ | Say | Tool |
404
+ |---|---|
405
+ | "pull / sync / refresh the kiro config", "update the steering and skills" | `pull_kiro_config` |
406
+ | "push / propose / share my kiro config", "sync my steering up" | `push_kiro_config` |
407
+ | "raise / open an MR for the kiro config", "merge request link" | `raise_merge_request` |
408
+ | "what changed", "status", "any open proposals for this repo" | `diff_kiro_config` |
409
+ | "validate / lint / check the kiro config, agents, hooks, skills" | `validate_kiro_config` |
410
+ | "what is synced and where" | `list_kiro_collections` |
411
+ | "am I on Kiro V3", "do my agents need upgrading" | `kiro_v3_status` |
412
+
413
+ Every tool accepts a `collections` list. Kiro does not pass the shell's `PATH`,
414
+ `SSH_AUTH_SOCK`, proxy variables or `GITLAB_TOKEN` to MCP servers, so the rendered entry
415
+ forwards them explicitly through `env`; use `steersync init --mcp-command /abs/path/uvx`
416
+ if `uvx` is not on Kiro's path.
315
417
 
316
418
  **Custom agents.** On Kiro CLI V3 custom agents inherit steering, skills and `AGENTS.md` by
317
419
  default, so list only the always on steering files in `resources` and reference skills with