synorch 0.2.0 → 0.3.0

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 (82) hide show
  1. package/CHANGELOG.md +32 -1
  2. package/README.md +314 -28
  3. package/dist/application/doctor-service.d.ts +16 -0
  4. package/dist/application/doctor-service.d.ts.map +1 -1
  5. package/dist/application/doctor-service.js +230 -32
  6. package/dist/application/doctor-service.js.map +1 -1
  7. package/dist/application/generated-skill-doctor.d.ts +9 -0
  8. package/dist/application/generated-skill-doctor.d.ts.map +1 -0
  9. package/dist/application/generated-skill-doctor.js +433 -0
  10. package/dist/application/generated-skill-doctor.js.map +1 -0
  11. package/dist/application/project-discovery.d.ts +12 -0
  12. package/dist/application/project-discovery.d.ts.map +1 -1
  13. package/dist/application/project-discovery.js +65 -2
  14. package/dist/application/project-discovery.js.map +1 -1
  15. package/dist/application/safe-path.d.ts +19 -0
  16. package/dist/application/safe-path.d.ts.map +1 -0
  17. package/dist/application/safe-path.js +35 -0
  18. package/dist/application/safe-path.js.map +1 -0
  19. package/dist/application/size-ceiling.d.ts +15 -0
  20. package/dist/application/size-ceiling.d.ts.map +1 -0
  21. package/dist/application/size-ceiling.js +32 -0
  22. package/dist/application/size-ceiling.js.map +1 -0
  23. package/dist/application/structure-service.d.ts.map +1 -1
  24. package/dist/application/structure-service.js +10 -1
  25. package/dist/application/structure-service.js.map +1 -1
  26. package/dist/cli.js +10 -1
  27. package/dist/cli.js.map +1 -1
  28. package/dist/domain/canonical-contracts.d.ts +69 -0
  29. package/dist/domain/canonical-contracts.d.ts.map +1 -0
  30. package/dist/domain/canonical-contracts.js +92 -0
  31. package/dist/domain/canonical-contracts.js.map +1 -0
  32. package/dist/domain/generated-skill.d.ts +55 -0
  33. package/dist/domain/generated-skill.d.ts.map +1 -0
  34. package/dist/domain/generated-skill.js +90 -0
  35. package/dist/domain/generated-skill.js.map +1 -0
  36. package/dist/domain/generation.d.ts +15 -2
  37. package/dist/domain/generation.d.ts.map +1 -1
  38. package/dist/domain/observation-ledger.d.ts +118 -0
  39. package/dist/domain/observation-ledger.d.ts.map +1 -0
  40. package/dist/domain/observation-ledger.js +183 -0
  41. package/dist/domain/observation-ledger.js.map +1 -0
  42. package/dist/domain/product.d.ts +1 -1
  43. package/dist/domain/product.js +1 -1
  44. package/dist/domain/relative-path.d.ts +21 -0
  45. package/dist/domain/relative-path.d.ts.map +1 -0
  46. package/dist/domain/relative-path.js +43 -0
  47. package/dist/domain/relative-path.js.map +1 -0
  48. package/dist/domain/skill-packs.d.ts.map +1 -1
  49. package/dist/domain/skill-packs.js +1 -0
  50. package/dist/domain/skill-packs.js.map +1 -1
  51. package/dist/domain/zod-issues.d.ts +21 -0
  52. package/dist/domain/zod-issues.d.ts.map +1 -0
  53. package/dist/domain/zod-issues.js +27 -0
  54. package/dist/domain/zod-issues.js.map +1 -0
  55. package/dist/infrastructure/frontmatter.d.ts +25 -0
  56. package/dist/infrastructure/frontmatter.d.ts.map +1 -0
  57. package/dist/infrastructure/frontmatter.js +75 -0
  58. package/dist/infrastructure/frontmatter.js.map +1 -0
  59. package/dist/templates/agent-manifests.d.ts +19 -0
  60. package/dist/templates/agent-manifests.d.ts.map +1 -0
  61. package/dist/templates/agent-manifests.js +302 -0
  62. package/dist/templates/agent-manifests.js.map +1 -0
  63. package/dist/templates/base-skills.d.ts +23 -0
  64. package/dist/templates/base-skills.d.ts.map +1 -0
  65. package/dist/templates/base-skills.js +477 -0
  66. package/dist/templates/base-skills.js.map +1 -0
  67. package/dist/templates/skill-creator-skill.d.ts +23 -0
  68. package/dist/templates/skill-creator-skill.d.ts.map +1 -0
  69. package/dist/templates/skill-creator-skill.js +235 -0
  70. package/dist/templates/skill-creator-skill.js.map +1 -0
  71. package/dist/templates/skill-references.d.ts +13 -0
  72. package/dist/templates/skill-references.d.ts.map +1 -0
  73. package/dist/templates/skill-references.js +280 -0
  74. package/dist/templates/skill-references.js.map +1 -0
  75. package/dist/templates/structure-templates.d.ts.map +1 -1
  76. package/dist/templates/structure-templates.js +15 -139
  77. package/dist/templates/structure-templates.js.map +1 -1
  78. package/dist/templates/task-conductor-skill.d.ts +1 -1
  79. package/dist/templates/task-conductor-skill.d.ts.map +1 -1
  80. package/dist/templates/task-conductor-skill.js +50 -22
  81. package/dist/templates/task-conductor-skill.js.map +1 -1
  82. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [0.3.0] - 2026-09-22
11
+
12
+ ### Added
13
+
14
+ - Canonical Agent Manifest v1 and Canonical Skill Contract v1: machine-checkable frontmatter for every generated agent and skill, validated by `doctor` alongside the required body sections and a numbered `Procedure`.
15
+ - Per-layer byte ceilings enforced by `doctor` — entrypoint 2 500, constitution 1 500, core protocol 2 000, agent manifest 3 000, base skill 6 000, reference file 15 000 — with depth moved into `references/` files that load only when a procedure step needs them.
16
+ - `skill-creator`, the ninth canonical base skill: it distills repeatedly confirmed project knowledge into a generated project skill after three confirmations from distinct tasks, or immediately on a user correction.
17
+ - A Git-tracked observation ledger at `.ai/tasks/observations.yaml`, seeded by `init`, plus a `.ai/tasks/.gitignore` that keeps per-task working records local.
18
+ - A generated-skill contract for `.ai/skills/project/**` enforced by `doctor`: evidence with existing in-root sources and matching digests, a `priority: skill` ceiling, a 15KB size limit, a twelve active-skill budget, confirming task ids that must exist in the ledger, and shape warnings for incident-log narration, missing triggers and unsourced claims.
19
+ - `sync` prunes expired observations and reports how many it removed.
20
+
21
+ ### Changed
22
+
23
+ - Retirement guidance now matches the implemented first slice: `doctor` detects stale evidence, while unused-skill and supersession decisions remain review-driven until usage telemetry exists.
24
+ - Agent manifests and base skills were rewritten to contract depth, with `not_for`, `inputs`, `tools`, `outputs`, `allowed_skills` and `reports` promoted from prose into frontmatter.
25
+ - `sync` never creates, overwrites or deletes anything under `.ai/skills/project/**`, with or without `--force`.
26
+ - Existing 0.2.x structures must be regenerated with `syn init --force` followed by `syn sync --force` to pick up the canonical contracts, the ninth base skill and the observation ledger.
27
+ - Hand-written agent directories under `.ai/agents/` are now held to the Canonical Agent Manifest contract: `doctor` reports a missing `AGENT.md`, invalid frontmatter, a name that does not match its directory, an unknown skill reference or a missing required section as an error.
28
+ - `init` never overwrites `.ai/tasks/observations.yaml`. The ledger is seeded when absent and preserved from then on, with or without `--force`, and `inspect` and `init` report it as `preserved` rather than `update` or `conflict`. `.ai/tasks/.gitignore` remains canonical and is still refreshed by `--force`.
29
+ - Activating a generated project skill is expressed by `status: active` in the skill's own frontmatter and by the observation moving to `status: promoted` with the new optional `promoted_to` link. There is no registry entry: `.ai/projects/<id>.skills.yaml` has no project-skill slot and is regenerated by every `sync`.
30
+ - Agent manifests no longer restate the procedure, required inputs, stop conditions or output contract of their primary skills; each points at the skill that owns them, so a rule lives in exactly one layer.
31
+ - `sync` fails explicitly with exit code 2 on a schema-invalid observation ledger instead of pruning or rewriting it.
32
+ - `doctor` reports `generated.broken-promotion-link` when a `promoted` observation's `promoted_to` names no skill under `.ai/skills/project/`.
33
+ - Recorded digest prefixes must now be at least 32 hex characters, in both the observation ledger and generated-skill evidence; a shorter prefix no longer counts as a digest match.
34
+ - Diagnostics that reported a schema failure now render it as `path: message` on one line instead of a raw zod JSON dump, and a defect that has a dedicated code is no longer also reported as a generic contract violation.
35
+
36
+ ### Fixed
37
+
38
+ - A generated skill could declare a `references` entry with a UNC root, a drive letter or a `..` segment and receive no diagnostic, and declared references were never resolved at all. The lexical rule is now shared with the canonical checks and applied before the absolute-path test, and `diagnoseGeneratedSkills` validates containment, existence and the 15000-byte ceiling under `generated.unsafe-reference-path`, `generated.missing-reference-file` and `generated.reference-size` (a warning, like every other layer ceiling).
39
+
10
40
  ## [0.2.0] - 2026-09-21
11
41
  ### Added
12
42
 
@@ -36,6 +66,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
36
66
  - A bundled, provenance-tracked Ingenium skill catalog with on-demand loading rules.
37
67
  - Model profiles, orchestration protocols, minimal context packets, verification contracts, and provider adapters.
38
68
 
39
- [Unreleased]: https://github.com/TunahanTuna/synorch/compare/v0.2.0...HEAD
69
+ [Unreleased]: https://github.com/TunahanTuna/synorch/compare/v0.3.0...HEAD
70
+ [0.3.0]: https://github.com/TunahanTuna/synorch/compare/v0.2.0...v0.3.0
40
71
  [0.2.0]: https://github.com/TunahanTuna/synorch/compare/v0.1.0...v0.2.0
41
72
  [0.1.0]: https://github.com/TunahanTuna/synorch/releases/tag/v0.1.0
package/README.md CHANGED
@@ -1,60 +1,346 @@
1
+ <div align="center">
2
+
1
3
  # Synorch
2
4
 
3
- `synorch`, Codex ve Claude Code için provider-bağımsız, orchestrator merkezli agent/skill/protokol yapısı kuran Node.js tabanlı bir CLI'dır. Paket adı `synorch`, kurulumdan sonraki kısa terminal komutu `syn`'dir.
5
+ **Turn any repository into an orchestrator-led AI development organization — in one command.**
6
+
7
+ [![npm version](https://img.shields.io/npm/v/synorch.svg?color=0b7285&label=npm)](https://www.npmjs.com/package/synorch)
8
+ [![license](https://img.shields.io/badge/license-MIT-0b7285.svg)](./LICENSE)
9
+ [![node](https://img.shields.io/badge/node-%3E%3D24-0b7285.svg)](https://nodejs.org)
10
+
11
+ `npx synorch init` · works with **Codex** and **Claude Code** · zero runtime, zero lock-in
12
+
13
+ </div>
14
+
15
+ ---
16
+
17
+ ## Why Synorch exists
18
+
19
+ Coding agents are already good at writing code. What they are bad at is *running a project*.
20
+
21
+ Left alone, a single agent session drifts in predictable ways. It starts implementing before anyone agreed on a plan. It re-reads the same repository from scratch in every subagent, burning tokens on facts it already knew. It grades its own homework, so the review is never independent. It guesses your stack instead of proving it. And every new session starts from zero, because nothing it learned was written down anywhere durable.
22
+
23
+ Synorch fixes the *organization* around the model, not the model itself.
24
+
25
+ It is a CLI that installs a provider-neutral **orchestration system** into a folder, a repository, or a multi-repo workspace: one decision-making orchestrator, a set of specialized worker roles, constitutional protocols they cannot override, evidence-backed project facts, and a skill library that loads only when it is actually needed. After `syn init` and `syn sync`, you keep working exactly as before — inside Codex or Claude Code — except the agent now operates inside a structure with rules, memory, and receipts.
26
+
27
+ ### What it is not
28
+
29
+ Synorch is deliberately small in scope, and honest about it:
4
30
 
5
- ## Kullanım
31
+ - It is **not** a model runtime. It never calls an API, never holds your keys, never runs a conversation loop.
32
+ - It is **not** a background daemon. Nothing watches your files. Every action is a command you type.
33
+ - It is **not** another coding assistant. It makes the one you already pay for behave like a team.
34
+ - It **never invents** your architecture. Empty folder in, generic core out — no hallucinated project facts.
35
+ - It **never fakes** provider capabilities. If Codex or Claude Code can't do something, `syn doctor` tells you instead of pretending a markdown file solved it.
6
36
 
7
- Kurulum yapmadan çalıştırma:
37
+ ---
38
+
39
+ ## Quick start
40
+
41
+ ```bash
42
+ # Inside an existing repository — no install needed
43
+ npx synorch init # install the orchestration core
44
+ npx synorch sync # discover the real stack from evidence
45
+ npx synorch doctor # verify every reference end to end
46
+ ```
47
+
48
+ Prefer a global install and the short command:
49
+
50
+ ```bash
51
+ npm install --global synorch
52
+ syn init && syn sync && syn doctor
53
+ ```
54
+
55
+ Other package managers work the same way:
8
56
 
9
57
  ```bash
10
- npx synorch init
11
58
  pnpm dlx synorch init
12
59
  yarn dlx synorch init
13
60
  ```
14
61
 
15
- Global kurulumdan sonra kısa komut:
62
+ Then just open Codex or Claude Code in that folder. The generated `AGENTS.md` and `CLAUDE.md` become the entry point, and the orchestrator takes it from there.
63
+
64
+ > **Requires Node.js 24+.** Synorch ships as strict-TypeScript ESM and relies on Node's built-in type stripping — no transpiler in your dependency tree.
65
+
66
+ ---
67
+
68
+ ## The 60-second tour
16
69
 
17
70
  ```bash
18
- npm install --global synorch
19
- syn init
71
+ $ syn inspect # dry run: exactly what would be written, and what would conflict
72
+ Target: /home/dev/acme-api
73
+ Scope: repository
74
+ + create AGENTS.md
75
+ + create CLAUDE.md
76
+ + create .ai/constitution.md
77
+ + create .ai/protocols/core/orchestration.md
78
+ ...
79
+ ! conflict .ai/skills/planning/SKILL.md
80
+
81
+ 1 conflict(s) found. Existing files will not be overwritten without --force.
20
82
  ```
21
83
 
22
- ## Geliştirme
84
+ ```bash
85
+ $ syn sync # evidence-driven discovery, then registry refresh
86
+ Discovered 3 project(s).
87
+ acme-api: services/api
88
+ acme-web: apps/web
89
+ acme-jobs: services/jobs
90
+ ```
23
91
 
24
92
  ```bash
25
- pnpm install
26
- pnpm check
27
- pnpm dev -- inspect
93
+ $ syn doctor # integrity check from workspace entry down to skill file
94
+ ERROR skill.registry.missing_file: Registered skill has no file on disk (.ai/skills/technology/react-patterns/SKILL.md)
95
+ ```
96
+
97
+ `doctor` exits non-zero on any error, so it drops straight into CI.
98
+
99
+ ---
100
+
101
+ ## How the system works
102
+
103
+ ### One decision center
104
+
105
+ You talk to the orchestrator. Only the orchestrator talks back to you. Everything else happens below the waterline.
106
+
107
+ ```text
108
+ You
109
+ │
110
+ ▼
111
+ ┌─────────────┐
112
+ │ Orchestrator│ plans · decides · delegates · verifies
113
+ └──────┬──────┘
114
+ ┌───────────┬───┴───────┬────────────┐
115
+ ▼ ▼ ▼ ▼
116
+ Explorer Implementer Debugger Reviewer
117
+ (read-only) (scoped (root (independent
118
+ writes) cause) of the author)
119
+ ```
120
+
121
+ The orchestrator is a control plane, not a contributor. It is forbidden from writing production, test, config, or documentation code — even when the change is one line. It may only write orchestration artifacts under `.ai/tasks/**`. The agent that implemented something can never be the final judge of it.
122
+
123
+ ### Every task gets planned, approved, and proven
124
+
125
+ ```text
126
+ SESSION_BOOTSTRAP → MODEL_PROFILE_CONFIRMATION → INTAKE → DISCOVERY
127
+ → CLARIFICATION → PLAN → USER_APPROVAL → DECOMPOSITION → DISPATCH
128
+ → MONITORING → VERIFICATION → REVIEW → FINAL_REPORT
129
+ ```
130
+
131
+ Two gates are non-negotiable. Before the first task of a session, the orchestrator shows you the active provider and the model assigned to every role and waits for confirmation. Before any execution, it shows you a plan and waits for approval. Nothing starts silently.
132
+
133
+ ### Effort scales with risk
134
+
135
+ Full ceremony on a typo fix is just expensive theater. Synorch classifies every task before execution:
136
+
137
+ | Tier | Workers | Verification | Independent review |
138
+ | --- | --- | --- | --- |
139
+ | **trivial** | one fast worker | claim-specific evidence only | not by default |
140
+ | **standard** | matched to scope | targeted checks | on material or boundary-crossing changes |
141
+ | **high-risk** | complex worker | comprehensive evidence | mandatory |
142
+
143
+ Tiers can only be escalated — if a finding widens the scope mid-flight, the task moves up, never down. Headed-browser verification is opt-in: it needs either your explicit request or a named criterion that cheaper evidence genuinely cannot settle.
144
+
145
+ ### Context packets instead of re-reading the repo
146
+
147
+ The expensive failure mode of multi-agent setups is that every worker rediscovers the same codebase. Synorch's answer is a schema'd handoff: the orchestrator does broad discovery **once**, then compiles a minimal, sourced packet per task.
148
+
149
+ ```yaml
150
+ task_id: auth-refresh-fix-implementation
151
+ assigned_role: implementer
152
+ model_tier: complex_worker
153
+
154
+ objective: Fix the session loss that occurs during refresh token rotation.
155
+
156
+ scope:
157
+ owned_paths: [src/auth/**, tests/auth/**]
158
+ read_paths: [src/session/**]
159
+ forbidden_paths: [src/billing/**]
160
+
161
+ known_facts:
162
+ - statement: Token rotation is active on refresh
163
+ source: src/auth/refresh-service.ts
164
+ confidence: verified
165
+
166
+ acceptance_criteria:
167
+ - Replaying an old refresh token revokes the whole token family
168
+ - A normal refresh does not terminate the active session
169
+
170
+ verification:
171
+ commands: [pnpm test auth, pnpm typecheck]
172
+ ```
173
+
174
+ Workers report back in the same structured shape — changed files, commands run, decisions made, unresolved risks. Follow-up work uses **delta handoff** (`extends:` plus only what changed) rather than resending the whole packet. If a worker notices that the files its context was built on have shifted, it stops and escalates instead of acting on stale truth.
175
+
176
+ ### Facts, not guesses
177
+
178
+ `syn sync` walks your repository or workspace deterministically and records what it can *prove*, with a source path attached to every claim:
179
+
180
+ ```yaml
181
+ test:
182
+ value: pnpm test
183
+ cwd: frontend
184
+ source: package.json
185
+ confidence: verified
186
+ ```
187
+
188
+ It parses JavaScript/TypeScript manifests plus Maven and Gradle definitions, and it is careful about false positives: commented-out coordinates and entries sitting only under dependency/plugin *management* do not count as evidence of an active framework. Nested module trees are discovered recursively, with a separate depth budget so a deep Java source tree isn't silently truncated. When a safety limit is genuinely reached, sync fails loudly rather than handing you an incomplete snapshot.
189
+
190
+ ### Skills load just in time
191
+
192
+ Every project registry gets the same nine canonical base skills:
193
+
194
+ `planning` · `project-discovery` · `codebase-exploration` · `implementation` · `verification` · `debugging` · `code-review` · `task-conductor` · `skill-creator`
195
+
196
+ Technology skills are added **only** when matching verified evidence exists:
197
+
198
+ | Detected | Activated skills |
199
+ | --- | --- |
200
+ | TypeScript | `typescript-patterns` |
201
+ | React | `react-patterns`, `react-modern`, `frontend-craft` |
202
+ | Vue / Nuxt | `vue-modern`, `frontend-craft` |
203
+ | Java | `java-patterns`, `java-backend` |
204
+ | Spring Boot | `spring-boot-patterns` |
205
+ | JPA / Hibernate | `jpa-patterns`, `db-schema-craft`, `query-tuning` |
206
+ | Express / Fastify / NestJS | `node-backend` |
207
+ | Maven · Gradle | `maven-build` · `gradle-build` |
208
+ | Tailwind CSS | `tailwind-v4-tokens` |
209
+
210
+ Beyond that, `sync` materializes a bundled 32-skill Ingenium library under `.ai/skills/library/ingenium/`, with source, license, and provenance recorded in `.ai/skills/catalog.yaml`. Those entries stay `available`, not loaded — the orchestrator pulls one into context only when a task description actually matches its description. Loading the whole pool at once is explicitly forbidden, which is the difference between a useful library and a context bill.
211
+
212
+ Three states, kept distinct: **available** (in the catalog) → **active** (in a project registry) → **loaded** (in a task context). Session bootstrap never scans the catalog.
213
+
214
+ Anthropic Agent Skills, Superpowers, and Microsoft Agent Skills are catalogued `reference-only` with pinned commit IDs. Third-party content is never auto-imported or executed without a separate security and license review.
215
+
216
+ ### Provider-neutral core, honest adapters
217
+
218
+ Protocols are written against capability tiers, not vendor model names:
219
+
220
+ ```yaml
221
+ model_tiers:
222
+ orchestrator: [strongest_reasoning, delegation, long_context]
223
+ complex_worker: [strong_coding, autonomous_execution]
224
+ fast_worker: [low_latency, low_cost]
28
225
  ```
29
226
 
30
- ## Komutlar
227
+ Adapters map those tiers onto the real model IDs of whichever provider you're running, with overrides resolving session → project → workspace → provider default. **Silent fallback is banned.** If a requested model isn't available, or the provider doesn't support per-subagent model selection, or the main session model can't be changed mid-flight, you are told — by `doctor` and again at session confirmation. Synorch will never let a markdown file imply a capability the host doesn't actually have.
228
+
229
+ ---
230
+
231
+ ## Commands
31
232
 
32
233
  ```bash
33
234
  syn inspect [--target <path>] [--scope workspace|repository]
34
- syn init [--target <path>] [--scope workspace|repository] [--force]
35
- syn sync [--target <path>] [--force] [--json]
36
- syn doctor [--target <path>] [--json]
235
+ syn init [--target <path>] [--scope workspace|repository] [--force]
236
+ syn sync [--target <path>] [--force] [--json]
237
+ syn doctor [--target <path>] [--json]
238
+ ```
239
+
240
+ | Command | What it does |
241
+ | --- | --- |
242
+ | `inspect` | Dry run. Prints every file that would be created, updated, left unchanged, or flagged as a conflict. Writes nothing. |
243
+ | `init` | Installs the canonical structure and provider entrypoints. Never touches your source code. Existing differing files are preserved unless `--force`. |
244
+ | `sync` | Manually triggered discovery. Records project facts with evidence, resolves skills, writes registries. Refuses to clobber hand-edited generated files without `--force`. |
245
+ | `doctor` | Validates the full reference chain — workspace entry → project record → module dirs → manifests → command `cwd` → skill registry → skill file — plus canonical base-skill completeness and path containment (both lexical traversal and `realpath` symlink/junction escapes). |
246
+
247
+ `--json` on `sync` and `doctor` gives machine-readable output for CI pipelines.
248
+
249
+ **Safety defaults that actually hold:** existing differing files are never overwritten without an explicit `--force`, and the observation ledger `.ai/tasks/observations.yaml` is never overwritten even with it — it is seeded once and reported as `preserved` thereafter; the active skill registry is written *last*, after every prerequisite output, so a failed write leaves the previous working registry intact; and nothing is reported `healthy` while a single reference is missing, broken, duplicated, or pointing outside the root.
250
+
251
+ ---
252
+
253
+ ## Generated structure
254
+
255
+ ```text
256
+ .ai/
257
+ ├── manifest.yaml
258
+ ├── constitution.md # constitutional, non-overridable rules
259
+ ├── workspace.yaml
260
+ ├── projects/
261
+ │ ├── <project-id>.yaml # evidence-backed project facts
262
+ │ └── <project-id>.skills.yaml # skill selections + rationale + matched evidence
263
+ ├── protocols/
264
+ │ ├── registry.yaml
265
+ │ └── core/
266
+ │ ├── orchestration.md planning-and-approval.md
267
+ │ ├── delegation.md model-routing.md
268
+ │ ├── context-handoff.md verification.md
269
+ │ ├── failure-recovery.md user-communication.md
270
+ ├── agents/
271
+ │ └── <role>/AGENT.md # Canonical Agent Manifest v1, one per role:
272
+ │ # orchestrator · explorer · implementer · reviewer · debugger
273
+ ├── skills/
274
+ │ ├── <canonical base skills>/SKILL.md # Canonical Skill Contract v1
275
+ │ │ └── references/*.md # depth loaded only when a step needs it
276
+ │ ├── technology/<selected>/SKILL.md
277
+ │ ├── project/<generated>/SKILL.md # earned project skills; sync never writes here
278
+ │ ├── library/ingenium/** # bundled, on-demand
279
+ │ └── catalog.yaml # provenance, license, activation mode
280
+ ├── model-profiles/
281
+ │ ├── openai.yaml
282
+ │ └── claude.yaml
283
+ ├── tasks/ # plans, context packets, decision log
284
+ │ ├── observations.yaml # the Git-tracked observation ledger
285
+ │ └── .gitignore # per-task working records stay local
286
+ └── providers/
287
+ ├── codex.md
288
+ └── claude-code.md
289
+ ```
290
+
291
+ Plus `AGENTS.md` and `CLAUDE.md` at the root as provider entrypoints.
292
+
293
+ ### Workspace mode vs. repository mode
294
+
295
+ **Repository mode** puts the structure inside a single repo, so it travels through Git and the whole team shares it.
296
+
297
+ **Workspace mode** puts one shared system in a parent folder above several repositories, each tracked as its own project record:
298
+
299
+ ```text
300
+ workspace/
301
+ ├── AGENTS.md
302
+ ├── CLAUDE.md
303
+ ├── .ai/
304
+ ├── repo-a/
305
+ └── repo-b/
306
+ ```
307
+
308
+ Cloned a new repo into the workspace? Run `syn sync`. There is no watcher and no full re-`init`.
309
+
310
+ On an empty folder, Synorch installs the generic orchestration core and stops. No invented stack, no imaginary architecture, `projects: []`.
311
+
312
+ ---
313
+
314
+ ## Contributing
315
+
316
+ ```bash
317
+ pnpm install
318
+ pnpm check # typecheck + test + build
319
+ pnpm dev -- inspect # run the CLI from source
37
320
  ```
38
321
 
39
- ## Skill havuzu
322
+ `pnpm check` also runs as a `prepack` gate, so nothing ships without passing typecheck, tests, and build. Package contents are restricted by an explicit allowlist, CI uses read-only default permissions with pinned action SHAs, and npm releases go out through Trusted Publishing (OIDC) — no long-lived tokens stored anywhere.
40
323
 
41
- `init`, Ingenium'dan bağımsız canonical `task-conductor` dahil sekiz base skill üretir. Task Conductor yalnız non-trivial brief'lerde merkezi decomposition/routing disiplini olarak kullanılır; tek satırlık işler için orkestra kurulmaz.
324
+ ---
42
325
 
43
- `sync`, proje sahibinin 32 skill'lik Ingenium havuzunu destek dosyalarıyla birlikte `.ai/skills/library/ingenium/` altına materialize eder ve kaynak/lisans/provenance bilgisini `.ai/skills/catalog.yaml` içinde tutar. Katalog girdileri yalnız `available` durumundadır ve varsayılan olarak context'e yüklenmez. React, Java, Node, Vue, JPA ve Tailwind skill'leri yalnız verified stack kanıtıyla aktive edilir; diğer skill'ler görev açıklaması gerçekten eşleştiğinde just-in-time yüklenir. Bütün havuzun aynı anda taranması veya context'e alınması yasaktır.
326
+ ## Documentation
44
327
 
45
- Görevler `trivial`, `standard` veya `high-risk` olarak sınıflandırılır. Trivial işler tek fast worker ve claim-specific kanıtla tamamlanır; bağımsız reviewer, full-project kontroller ve headed browser varsayılan olarak kullanılmaz. Browser doğrulaması yalnız kullanıcı isteğiyle veya daha ucuz kanıtların çözemediği isimlendirilmiş bir kriter için ayrıca onay alınarak yapılır.
328
+ | Document | Contents |
329
+ | --- | --- |
330
+ | [Architecture](./docs/AI-ORCHESTRATION-ARCHITECTURE.md) | The full design: orchestration model, protocol system, context architecture, model routing, discovery, open decisions, and the dated decision log. |
331
+ | [Multi-provider harness vision](./docs/FUTURE-MULTI-PROVIDER-HARNESS.md) | Where this goes next — running different providers in different roles under one orchestrator. Proposal stage, not implemented. |
332
+ | [CHANGELOG](./CHANGELOG.md) | Version history, Keep a Changelog + SemVer. |
333
+ | [Release notes v0.3.0](./docs/releases/v0.3.0.md) | Human-readable notes for the current release. |
334
+ | [Security policy](./SECURITY.md) | Report vulnerabilities through the private channel, not a public issue. |
46
335
 
47
- Anthropic Agent Skills, Superpowers ve Microsoft Agent Skills kaynakları sabit commit kimlikleriyle kataloglanır ancak güvenlik ve lisans incelemesi yapılmadan içerikleri otomatik import veya execute edilmez.
336
+ ---
48
337
 
49
- `init`, kaynak koda dokunmadan canonical orchestration çekirdeğini kurar. Ardından `sync`, repository veya workspace modüllerini kanıta dayalı olarak keşfeder, proje/skill registry'lerini ve seçilen teknoloji skill'lerini üretir; kullanıcı tarafından değiştirilmiş generated teknoloji skill'lerini yalnızca açık `--force` ile yeniler. Son olarak `doctor`, referans zincirini, canonical base skill kümesini ve path/symlink sınırlarını doğrular.
338
+ ## Roadmap
50
339
 
51
- Mimari kararlar için [mimari planı](./docs/AI-ORCHESTRATION-ARCHITECTURE.md) inceleyin.
340
+ Today Synorch generates and validates the structure; your host agent executes it. The [multi-provider harness proposal](./docs/FUTURE-MULTI-PROVIDER-HARNESS.md) sketches a future layer that could connect authorized provider accounts, run different models in different roles under one orchestrator, persist task state, and manage the implementation-to-review flow across vendors. That layer is not implemented, and this README will not pretend otherwise.
52
341
 
53
- ## Gereksinimler ve proje bilgileri
342
+ ---
54
343
 
55
- - Node.js 24 veya daha yeni bir sürüm gerekir.
56
- - Sürüm geçmişi için [CHANGELOG.md](./CHANGELOG.md) dosyasını inceleyin.
57
- - Güvenlik açıklarını herkese açık issue yerine [güvenlik politikasındaki](./SECURITY.md) özel bildirim akışıyla paylaşın.
58
- - Synorch, [MIT lisansı](./LICENSE) altında yayımlanır.
344
+ ## License
59
345
 
60
- Güncel sürüm notları [Synorch v0.2.0](./docs/releases/v0.2.0.md) belgesinde yer alır.
346
+ MIT © [Tunahan Tuna](https://github.com/TunahanTuna) — see [LICENSE](./LICENSE).
@@ -16,6 +16,22 @@ export declare class DoctorService {
16
16
  private validateCommandPaths;
17
17
  private validateSkillRegistry;
18
18
  private validateRegisteredSkills;
19
+ /**
20
+ * Canonical Agent Manifest v1 and Canonical Skill Contract v1 enforcement.
21
+ * Contract violations are errors; layer size overruns are warnings.
22
+ */
23
+ private validateCanonicalContracts;
24
+ private validateAgentManifest;
25
+ private validateSkillContract;
26
+ /**
27
+ * A declared reference must resolve inside its own skill directory both
28
+ * lexically and after symbolic links are canonicalized.
29
+ */
30
+ private validateSkillReferences;
31
+ private checkFileSize;
32
+ private readOptionalText;
33
+ private listDirectoryNames;
34
+ private listMarkdownFiles;
19
35
  private isExistingDirectory;
20
36
  private isExistingRegularFile;
21
37
  private isCanonicalPathWithin;
@@ -1 +1 @@
1
- {"version":3,"file":"doctor-service.d.ts","sourceRoot":"","sources":["../../src/application/doctor-service.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kCAAkC,CAAC;AAGnE,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAE9D,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAWD,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;gBAErB,UAAU,EAAE,UAAU;IAI5B,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC;YAyFhE,sBAAsB;YAkItB,0BAA0B;YA+F1B,2BAA2B;YA+B3B,oBAAoB;YAqDpB,qBAAqB;YA4DrB,wBAAwB;YAiHxB,mBAAmB;YAOnB,qBAAqB;YAOrB,qBAAqB;YASrB,gBAAgB;CAgD/B"}
1
+ {"version":3,"file":"doctor-service.d.ts","sourceRoot":"","sources":["../../src/application/doctor-service.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kCAAkC,CAAC;AAgBnE,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAE9D,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAoBD,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;gBAErB,UAAU,EAAE,UAAU;IAI5B,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC;YA4FhE,sBAAsB;YAkItB,0BAA0B;YA+F1B,2BAA2B;YA+B3B,oBAAoB;YAqDpB,qBAAqB;YA4DrB,wBAAwB;IAiHtC;;;OAGG;YACW,0BAA0B;YAmB1B,qBAAqB;YA0DrB,qBAAqB;IAgDnC;;;OAGG;YACW,uBAAuB;YAgDvB,aAAa;YAWb,gBAAgB;YAShB,kBAAkB;YAalB,iBAAiB;YAajB,mBAAmB;YAOnB,qBAAqB;YAOrB,qBAAqB;YASrB,gBAAgB;CAgD/B"}