kd-cli 2.6.0__tar.gz → 2.6.1__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 (87) hide show
  1. {kd_cli-2.6.0/kd_cli.egg-info → kd_cli-2.6.1}/PKG-INFO +1 -1
  2. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/resources/CHANGELOG.md +11 -0
  3. kd_cli-2.6.1/kd/resources/sdlc-doctrine.md +602 -0
  4. {kd_cli-2.6.0 → kd_cli-2.6.1/kd_cli.egg-info}/PKG-INFO +1 -1
  5. {kd_cli-2.6.0 → kd_cli-2.6.1}/pyproject.toml +1 -1
  6. kd_cli-2.6.0/kd/resources/sdlc-doctrine.md +0 -479
  7. {kd_cli-2.6.0 → kd_cli-2.6.1}/LICENSE +0 -0
  8. {kd_cli-2.6.0 → kd_cli-2.6.1}/MANIFEST.in +0 -0
  9. {kd_cli-2.6.0 → kd_cli-2.6.1}/README.md +0 -0
  10. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/__init__.py +0 -0
  11. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/api/__init__.py +0 -0
  12. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/api/articles.py +0 -0
  13. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/api/http.py +0 -0
  14. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/api/hub.py +0 -0
  15. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/api/saved_queries.py +0 -0
  16. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/api/tags.py +0 -0
  17. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/api/youtrack.py +0 -0
  18. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/article_marker.py +0 -0
  19. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/auth.py +0 -0
  20. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/cache.py +0 -0
  21. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/cli/__init__.py +0 -0
  22. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/cli/core/__init__.py +0 -0
  23. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/cli/core/command_base.py +0 -0
  24. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/cli/core/command_parser.py +0 -0
  25. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/cli/core/confirm.py +0 -0
  26. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/cli/core/namespaces.py +0 -0
  27. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/cli/core/option_registry.py +0 -0
  28. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/cli/input.py +0 -0
  29. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/cli/main.py +0 -0
  30. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/cli/namespaces/__init__.py +0 -0
  31. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/cli/namespaces/alias/__init__.py +0 -0
  32. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/cli/namespaces/article/__init__.py +0 -0
  33. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/cli/namespaces/cache/__init__.py +0 -0
  34. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/cli/namespaces/init.py +0 -0
  35. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/cli/namespaces/issue/__init__.py +0 -0
  36. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/cli/namespaces/primer/__init__.py +0 -0
  37. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/cli/namespaces/project/__init__.py +0 -0
  38. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/cli/namespaces/query/__init__.py +0 -0
  39. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/cli/namespaces/release_notes.py +0 -0
  40. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/cli/namespaces/search/__init__.py +0 -0
  41. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/cli/namespaces/system/__init__.py +0 -0
  42. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/cli/namespaces/tag/__init__.py +0 -0
  43. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/cli/namespaces/time/__init__.py +0 -0
  44. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/cli/namespaces/user/__init__.py +0 -0
  45. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/cli/output.py +0 -0
  46. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/cli/tree.py +0 -0
  47. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/client.py +0 -0
  48. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/config.py +0 -0
  49. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/config_read.py +0 -0
  50. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/config_schema.py +0 -0
  51. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/connection.py +0 -0
  52. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/debug.py +0 -0
  53. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/exceptions.py +0 -0
  54. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/history.py +0 -0
  55. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/locking.py +0 -0
  56. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/models/__init__.py +0 -0
  57. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/models/article.py +0 -0
  58. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/models/assist.py +0 -0
  59. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/models/attachment.py +0 -0
  60. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/models/comment.py +0 -0
  61. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/models/common.py +0 -0
  62. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/models/issue.py +0 -0
  63. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/models/project.py +0 -0
  64. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/models/saved_query.py +0 -0
  65. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/models/search.py +0 -0
  66. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/models/tag.py +0 -0
  67. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/models/tag_entities.py +0 -0
  68. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/models/user.py +0 -0
  69. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/models/work_item.py +0 -0
  70. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/operating_guide.py +0 -0
  71. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/primer.py +0 -0
  72. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/query_parser.py +0 -0
  73. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/release_notes.py +0 -0
  74. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/resources/__init__.py +0 -0
  75. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/resources/command-synonyms.yaml +0 -0
  76. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/resources/config-template.yaml +0 -0
  77. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/resources/error-messages.yaml +0 -0
  78. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/resources/operating-guide.md +0 -0
  79. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/resources/primers/__init__.py +0 -0
  80. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/resources/primers/hitl.yaml +0 -0
  81. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd/sdlc.py +0 -0
  82. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd_cli.egg-info/SOURCES.txt +0 -0
  83. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd_cli.egg-info/dependency_links.txt +0 -0
  84. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd_cli.egg-info/entry_points.txt +0 -0
  85. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd_cli.egg-info/requires.txt +0 -0
  86. {kd_cli-2.6.0 → kd_cli-2.6.1}/kd_cli.egg-info/top_level.txt +0 -0
  87. {kd_cli-2.6.0 → kd_cli-2.6.1}/setup.cfg +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: kd-cli
3
- Version: 2.6.0
3
+ Version: 2.6.1
4
4
  Summary: Knowledge Dispatcher for issue trackers and knowledge bases
5
5
  Author: Sergiy Gladkyy
6
6
  License-Expression: MIT
@@ -4,6 +4,17 @@ All notable changes to kd-cli are recorded here. The project follows [Semantic V
4
4
 
5
5
  ## [Unreleased]
6
6
 
7
+ ## [2.6.1] — 2026-04-27
8
+
9
+ ### Documentation
10
+ - `kd --sdlc` now opens with a reader-first mental model and vocabulary before
11
+ the layer, cache, marker-bridged, and closeout rules. The packaged doctrine
12
+ keeps the same tool contracts while making the SDLC easier for first-time
13
+ human readers and LLM agents to explain.
14
+ - `kd --sdlc` now defines daybooks, surfaces the session starter checklist
15
+ near the front, and clarifies the planning path from ideation through setup
16
+ into the repeatable session loop.
17
+
7
18
  ## [2.6.0] — 2026-04-27
8
19
 
9
20
  ### Added
@@ -0,0 +1,602 @@
1
+ # SDLC Doctrine (Portable)
2
+
3
+ This is the portable SDLC reference bundled with kd-cli and printed by
4
+ `kd --sdlc`. It explains the working method for projects that use kd and
5
+ YouTrack as a knowledge-network substrate.
6
+
7
+ The short version:
8
+
9
+ 1. YouTrack is the canonical place for planning and durable knowledge.
10
+ 2. The repository stays thin: code, build machinery, session harness files,
11
+ and a narrow class of repo-reviewed knowledge files.
12
+ 3. `.kd/` is local context: primer plus disposable cache, never authority.
13
+ 4. A session starts by pulling context, proceeds through work and verification,
14
+ and closes by pushing focused results back to the tracker.
15
+
16
+ This document is not a command catalog. Use `kd --reference` for exact syntax
17
+ and `kd --guide` for kd-specific operating guidance.
18
+
19
+ ## The mental model
20
+
21
+ The SDLC is a loop:
22
+
23
+ ```text
24
+ pull context -> reason and work -> verify -> publish the outcome
25
+ ```
26
+
27
+ The operator, human or LLM, begins with a small local primer, pulls the issue
28
+ or article context needed for the task, performs the work in the repository,
29
+ then records the outcome upstream. kd supports that loop with narrow commands:
30
+
31
+ - `kd /primer show` reads the workspace's curated starting context.
32
+ - `kd /issue show`, `kd /article show`, `kd /tag entities`, and saved queries
33
+ pull live context from YouTrack.
34
+ - `kd /cache refresh`, `kd /cache status`, and `kd /cache search` support
35
+ read-side local resilience.
36
+ - `kd /article push` publishes a repo-authored article render upstream.
37
+ - `kd /issue touched --git-range A..B` helps reconcile offline work from git
38
+ history.
39
+
40
+ The doctrine is deliberately upstream-first, not repo-doc-first. Most durable
41
+ knowledge belongs in YouTrack articles. The repo keeps only what needs to live
42
+ beside code or be loaded by the tool and harness.
43
+
44
+ ## Vocabulary
45
+
46
+ These terms are used throughout the doctrine.
47
+
48
+ | Term | Meaning |
49
+ |------|---------|
50
+ | Upstream | The live tracker and knowledge base, normally YouTrack. |
51
+ | Issue | The execution record for work: task, bug, story, epic, or subtask. |
52
+ | Epic | The upstream container for milestone-sized work. |
53
+ | Article | A durable knowledge page in YouTrack: design note, how-to, index, playbook, daybook, accepted proposal. |
54
+ | Daybook | A chronological project article for operational memory: context shifts, notable decisions, incidents, and narrative breadcrumbs that do not belong in a single issue closeout or timeless design record. |
55
+ | Primer | Workspace-local `.kd/primer.yaml`: short notes plus pinned references that tell the operator what to read first. |
56
+ | Cache | Disposable `.kd/cache/` mirror of selected upstream content for reading and offline resilience. |
57
+ | Session | One bounded work cycle against an issue or, for non-code exploration, an explicitly chosen no-ticket path. |
58
+ | HITL | Human-in-the-loop validation against a real upstream system. |
59
+ | Publication tier | The rule that decides how much of a session becomes upstream record: full closeout, compact capsule, article, or summary only. |
60
+ | Profile | A project-local article that records conventions not shared by every project using this portable doctrine. |
61
+ | Umbrella ticket | One fixed project ticket for tiny hygiene commits that genuinely have no story worth telling. |
62
+ | Marker-bridged file | A repo file with a `kd-meta` marker that is reviewed in git but rendered as an upstream article. |
63
+
64
+ ## Session starter checklist
65
+
66
+ When beginning a session:
67
+
68
+ 1. Run `kd /primer show`.
69
+ 2. Read this doctrine with `kd --sdlc` when the method is not already loaded.
70
+ 3. Read the project profile article if the primer pins one.
71
+ 4. Read the assigned issue, or create/select one before committing.
72
+ 5. Classify the cycle variant: standard, offline, no-HITL, no-ticket, or
73
+ cold-start.
74
+ 6. Plan the work in the project's chosen session record.
75
+ 7. Execute code, tests, and docs.
76
+ 8. Verify with the project's test, lint, type-check, and HITL expectations.
77
+ 9. Close out per publication tier and record the verification mode.
78
+ 10. Run the repo-doc audit when documentation changed.
79
+ 11. Commit with `PROJ-N:` prefix.
80
+ 12. Transition the ticket when upstream is reachable.
81
+
82
+ ## The three layers
83
+
84
+ Every artifact belongs to exactly one layer.
85
+
86
+ ### Layer A - Upstream
87
+
88
+ YouTrack is canonical for planning and durable knowledge.
89
+
90
+ - Epic issues contain milestone-sized plans.
91
+ - Child issues contain session-sized execution work.
92
+ - Articles contain durable knowledge: designs, accepted proposals, how-tos,
93
+ indexes, daybooks, and migration playbooks.
94
+ - Tags and saved queries make that knowledge discoverable.
95
+
96
+ If a document does not need to be in the repository for code review, build,
97
+ packaging, or session bootstrapping, it normally belongs upstream as an
98
+ article.
99
+
100
+ ### Layer B - Thin repo
101
+
102
+ The repository is committed, reviewed, and built. A non-code file belongs here
103
+ only when it satisfies one of the mechanical categories in the next section.
104
+
105
+ Layer B exists because some files must travel with the code: harness rules,
106
+ packaged resources, release machinery, and the few knowledge files whose
107
+ source must be reviewed in the same pull request as the code they govern.
108
+
109
+ ### Layer C - Workspace-local
110
+
111
+ `.kd/` is local context and never committed.
112
+
113
+ - `.kd/primer.yaml` is curated by the operator.
114
+ - `.kd/cache/` is disposable upstream mirror content.
115
+
116
+ Deleting cache loses no authority because upstream can rehydrate it. Deleting
117
+ the primer loses local orientation, not upstream truth.
118
+
119
+ ## Where does this file go?
120
+
121
+ Layer B membership is mechanical. Do not decide by asking whether a document
122
+ "feels code-adjacent." Decide by category.
123
+
124
+ | Category | Contents | Examples |
125
+ |----------|----------|----------|
126
+ | Harness-consumed | Loaded every session by humans or LLM harnesses. | `AGENTS.md`, `RULES.md`, coding-style files. |
127
+ | Tool-packaged | Ships in the wheel or is read by the installed tool. | Embedded guides, packaged resources. |
128
+ | Build-essential | Required for build, test, CI, release, or changelog flow. | `pyproject.toml`, CI config, `CHANGELOG.md`. |
129
+ | Marker-bridged | Repo source with a `kd-meta` marker and an upstream article render. | ADRs or code-coupled specs that need PR review and upstream discoverability. |
130
+
131
+ Decision flow:
132
+
133
+ 1. Loaded at session start by the harness or humans? Keep in Layer B.
134
+ 2. Shipped or read by the installed tool? Keep in Layer B.
135
+ 3. Needed for build, test, CI, release, or changelog flow? Keep in Layer B.
136
+ 4. Needs both PR review with code and upstream discoverability? Make it
137
+ marker-bridged.
138
+ 5. Otherwise publish it upstream as an article.
139
+
140
+ **Repo documentation audit.** At closeout, every committed documentation file
141
+ must still satisfy one Layer B category. If a document moved upstream, delete
142
+ the repo copy unless it still has a named Layer B reason or a recorded
143
+ compliance/audit exception.
144
+
145
+ **Incubation exception.** A project may keep a repo-local proposal staging
146
+ area for design drafts before acceptance. At acceptance, the proposal becomes
147
+ an upstream article tagged as accepted, and the local draft is deleted. This is
148
+ not a general place for durable docs.
149
+
150
+ ## What belongs upstream as an article?
151
+
152
+ Use articles for durable knowledge that does not need repo review coupling:
153
+
154
+ - Design records.
155
+ - Specs not tied to a code review.
156
+ - How-tos that do not require the source tree.
157
+ - Branch or topic indexes, such as "Index: Proposals" or "Index: How-to".
158
+ - Migration playbooks.
159
+ - Daybooks.
160
+ - Accepted proposals.
161
+
162
+ Operational articles should be network-shaped, not just searchable prose.
163
+ Minimum structure:
164
+
165
+ - `kind:*` tag for artifact type.
166
+ - `lifecycle:*` tag for state.
167
+ - Owning project.
168
+ - Backrefs to governing epics, issues, proposals, or code-coupled artifacts.
169
+
170
+ ### Proposal shape in YouTrack
171
+
172
+ A proposal is knowledge, not an execution container.
173
+
174
+ - During incubation, a draft may live in the repo's proposal staging area.
175
+ - Once accepted, the canonical proposal is a YouTrack article.
176
+ - Epics and session issues may link to the proposal when it governs the work.
177
+ - The proposal does not replace the epic -> child-issue hierarchy.
178
+
179
+ ### Tag taxonomy pattern
180
+
181
+ Adapt tags per project, but keep common namespaces stable:
182
+
183
+ - `kind:*` for artifact type, such as `kind:proposal`, `kind:how-to`,
184
+ `kind:spec`, `kind:design`, `kind:adr`, `kind:sdlc`, `kind:index`,
185
+ `kind:daybook`, `kind:history`, `kind:digest`.
186
+ - `lifecycle:*` for state, such as `lifecycle:draft`,
187
+ `lifecycle:accepted`, `lifecycle:deprecated`, `lifecycle:historical`.
188
+ - `area:*`, `component:*`, and `module:*` for project structure.
189
+ - Domain-specific namespaces when the project needs them.
190
+
191
+ ## How does planning start?
192
+
193
+ The repeated session loop is only the mechanical part of the SDLC. Before that
194
+ loop is useful, the project needs direction and executable structure.
195
+
196
+ The planning shape is:
197
+
198
+ ```text
199
+ ideation -> setup -> mechanical loop
200
+ ```
201
+
202
+ ### Ideation
203
+
204
+ Ideation is where direction becomes durable knowledge. It may start as a
205
+ vision, design sketch, proposal, migration playbook, incident lesson, or open
206
+ question. In the kd-native shape, accepted durable thinking lives upstream as
207
+ articles, tagged and cross-linked. Draft proposals may temporarily live in the
208
+ repo's proposal staging area, but accepted knowledge moves upstream.
209
+
210
+ The point of ideation is not to create a perfect plan. It is to make the
211
+ reasoning discoverable enough that future epics and sessions inherit context
212
+ instead of reconstructing it.
213
+
214
+ ### Setup
215
+
216
+ Setup turns direction into executable tracker structure.
217
+
218
+ Typical setup work:
219
+
220
+ - Identify the governing article or create one.
221
+ - Create one epic issue for a milestone-sized body of work.
222
+ - Split the epic into child session issues.
223
+ - Record required ordering on child issues or in the epic plan.
224
+ - Add tags, saved queries, or index articles that make the work discoverable.
225
+ - Pin high-signal references in the primer when they should be read at session
226
+ start.
227
+
228
+ This is the planning session. It is where an operator converts "we should do
229
+ this" into "here are the epics and session issues that make it executable."
230
+
231
+ ### Mechanical loop
232
+
233
+ Once setup exists, normal sessions repeat the bounded execution cycle:
234
+
235
+ ```text
236
+ read context -> plan session -> execute -> verify -> close out -> optionally release -> repeat
237
+ ```
238
+
239
+ The old paper workflow maps to the kd-native shape like this:
240
+
241
+ | Paper-era artifact | kd-native home |
242
+ |--------------------|----------------|
243
+ | Main design or vision document | Upstream design, proposal, vision, or playbook article. |
244
+ | Master plan document | Usually an upstream planning/index article plus epic hierarchy; not mandatory as a fixed artifact. |
245
+ | Milestone document | Epic issue, optionally backed by a governing article. |
246
+ | Session slice inside a milestone | Child issue under the epic. |
247
+ | Session plan and execution notes | Session issue plus local session record when the project still uses one. |
248
+ | Session conclusion | Issue closeout comment; durable reference output becomes an article link. |
249
+
250
+ The conclusion is simple: planning becomes graph-shaped upstream knowledge, but
251
+ execution stays mechanical. Ideation creates the "why"; setup creates the
252
+ tracker shape; sessions repeatedly move one slice through verification and
253
+ publication.
254
+
255
+ ## How do I model milestone-sized work?
256
+
257
+ Use native YouTrack hierarchy for execution. Do not flatten planning into a
258
+ free-text custom field.
259
+
260
+ - **Rationale** lives as an article: proposal, design note, or playbook.
261
+ - **Epic issue** is the canonical container for one milestone-sized body of
262
+ work.
263
+ - **Session issue** is a child of the epic and holds one execution slice with
264
+ its own closeout.
265
+ - **Subtasks or checklists** break a session down further when useful.
266
+ - **Custom fields** can support filtering, boards, and reports, but they do
267
+ not replace the epic -> child-issue structure.
268
+ - **Ordering** is explicit on child issues or the epic plan when order matters.
269
+
270
+ ## How do I run a session?
271
+
272
+ A session is one bounded pass through the loop:
273
+
274
+ ```text
275
+ load context -> choose cycle variant -> plan -> execute -> verify -> publish -> commit/transition
276
+ ```
277
+
278
+ Start with:
279
+
280
+ 1. `kd /primer show` to load workspace context.
281
+ 2. The portable doctrine, usually from `kd --sdlc`.
282
+ 3. The project profile article if the primer pins one.
283
+ 4. The assigned issue, usually with `kd /issue show PROJ-123 -o yaml`.
284
+
285
+ Then classify the session. Four inputs decide the cycle variant.
286
+
287
+ | Input | State(s) | Consequence |
288
+ |-------|----------|-------------|
289
+ | Tracker | Reachable / unreachable | Unreachable means offline cycle if cache is warm. |
290
+ | Ticket | Exists / missing | Missing means create/select a ticket or use the umbrella only when allowed. |
291
+ | HITL | N/A / executed / deferred | Deferred means name the reason; no automatic follow-up ticket. |
292
+ | Cache | Warm / cold | Cold plus tracker unreachable means cold-start limits. |
293
+
294
+ ### Standard cycle
295
+
296
+ Tracker is reachable, a real ticket exists, and HITL is either completed or
297
+ not applicable. Work normally, verify normally, close out per publication
298
+ tiers, and use commit subjects prefixed with `PROJ-N:`.
299
+
300
+ ### Offline cycle
301
+
302
+ Tracker is unreachable but cache is warm. Work proceeds against cached context.
303
+ Commits still use `PROJ-N:` prefixes. Reconciliation happens later with
304
+ `kd /issue touched --git-range A..B`, issue closeout comments, transitions, and
305
+ article pushes.
306
+
307
+ ### No-HITL cycle
308
+
309
+ Use the verification vocabulary precisely:
310
+
311
+ - **HITL not applicable.** The work has no upstream-facing behavior. Close out
312
+ normally and record `not_applicable` when a verification mode is needed.
313
+ - **HITL deferred.** The work touches upstream behavior but a live check was
314
+ not run. Closeout names the limitation. Do not create a placeholder follow-up
315
+ automatically; a future session or real incident can create real work.
316
+
317
+ ### No-ticket cycle
318
+
319
+ No commit lands without a ticket prefix.
320
+
321
+ - **New-ticket path.** If exploration produces code or operator-visible docs
322
+ worth keeping, create or select a real ticket before committing.
323
+ - **Umbrella path.** Use the fixed project umbrella only for hygiene that has
324
+ no story worth telling.
325
+
326
+ ### Cold-start cycle
327
+
328
+ Fresh clone, no tracker, and no cache. Work is limited to repo-local reading,
329
+ code review, and proposal drafting in the project's staging area for later
330
+ publication.
331
+
332
+ ## How do I verify HITL?
333
+
334
+ Use this closed vocabulary in closeouts and session records.
335
+
336
+ | Mode | Meaning | Closeout consequence |
337
+ |------|---------|----------------------|
338
+ | `live_hitl` | Real upstream read and write verification completed. | Full closeout. |
339
+ | `read_only_hitl` | Real upstream reads completed; writes not exercised. | Closeout names the limitation. |
340
+ | `cached` | Verified against hydrated cache only. | Closeout notes upstream validation debt. |
341
+ | `simulated` | Unit tests or fixtures only. | Defer closeout if behavior touches upstream. |
342
+ | `not_applicable` | No upstream-facing behavior. | No HITL mention required. |
343
+
344
+ ## How do I close out a session?
345
+
346
+ Publication is tiered. The goal is durable trace, not log migration.
347
+
348
+ | Session kind | Upstream record |
349
+ |--------------|-----------------|
350
+ | Short session | Full closeout comment on the issue: changes, files, decisions, test results. |
351
+ | Long session | Compact issue capsule plus article link for durable parts. |
352
+ | Durable reference produced | Publish the artifact as an article and reference it from the issue. |
353
+ | Ephemeral raw thinking | Do not publish raw. Summarize the outcome and discard the rest. |
354
+
355
+ Test question: would a future reader of this issue benefit from the full
356
+ session, or only from the outcome? Full session means publish the durable part.
357
+ Outcome only means summarize.
358
+
359
+ For sessions that change both code and operator-visible docs, the recommended
360
+ commit shape is:
361
+
362
+ 1. Code and tests.
363
+ 2. Docs and session conclusion.
364
+
365
+ Single-commit closeout is fine for docs-only, hygiene-only, or small sessions.
366
+ The invariant is that every commit subject carries a `PROJ-N:` prefix.
367
+
368
+ ## What happens when the tracker is down?
369
+
370
+ Tracker-down work is an offline cycle, not a separate state machine.
371
+
372
+ Use cache only for reading:
373
+
374
+ ```bash
375
+ kd /cache refresh --primer-scope
376
+ kd /cache refresh --issue PROJ-123
377
+ kd /cache refresh --article PROJ-A-1
378
+ kd /cache status
379
+ kd /cache search "phrase"
380
+ ```
381
+
382
+ The cache never becomes a write buffer. Mutations still require a live tracker.
383
+
384
+ When the tracker returns, reconcile from git:
385
+
386
+ ```bash
387
+ kd /issue touched --git-range origin/main..HEAD -o yaml
388
+ ```
389
+
390
+ Then, for each touched ticket:
391
+
392
+ 1. Push commits if needed.
393
+ 2. Post the closeout record required by the publication tier.
394
+ 3. Transition the issue.
395
+ 4. Push any article edits that were drafted locally.
396
+
397
+ There is no local `pending-syncs.yaml`. Git history is the queue; commit
398
+ prefixes are the index.
399
+
400
+ ## What's in `.kd/`?
401
+
402
+ `.kd/` contains local context. Do not commit it.
403
+
404
+ | Concept | Source of truth | Deletion loss | Where |
405
+ |---------|-----------------|---------------|-------|
406
+ | Primer | Operator-curated local context. | Loses workspace orientation. | `.kd/primer.yaml` |
407
+ | Cache | Upstream. | None; rehydrate from tracker. | `.kd/cache/` |
408
+ | Durable state | Not introduced by this doctrine. | Would need its own contract. | Not used today. |
409
+ | Scratch | Operator or LLM transient work. | None by construction. | Use `/tmp` or untracked files. |
410
+
411
+ ### Cache contract
412
+
413
+ `.kd/cache/` contains rehydratable upstream-mirror content: article bodies,
414
+ issues, query results, tag/entity results, field schemas, and fetch metadata.
415
+
416
+ Multi-connection workspaces materialize one scope per connection:
417
+
418
+ ```text
419
+ .kd/cache/connections/<slug>/articles/
420
+ .kd/cache/connections/<slug>/issues/
421
+ .kd/cache/connections/<slug>/queries/
422
+ ```
423
+
424
+ Each scope has `scope.yaml` with the immutable identity tuple
425
+ `{kind, connection, provider, base_url, compat_tier, created_at}`. Refresh is
426
+ idempotent on full identity match and refuses to write into a scope whose
427
+ recorded identity diverges from the active connection.
428
+
429
+ Cache rules:
430
+
431
+ - **Explicit hydration.** Cache writes happen through `kd /cache refresh`.
432
+ Implicit read-through writes are out of scope.
433
+ - **Disposable.** Deletion is safe; upstream is authoritative.
434
+ - **Staleness is visible.** Cached entries carry fetched and upstream updated
435
+ timestamps where available.
436
+ - **Read-side only.** No sync queue, no write buffer, no mutation from stale
437
+ context.
438
+
439
+ `kd /cache clear` is local-only and defaults to the active scope. `--all`
440
+ clears every scope. `kd /cache status` is also local-only and reports counts,
441
+ fetch age, stale counts, and warnings for parse failures.
442
+
443
+ Cached artifacts are marked as disposable mirrors. Markdown article bodies use
444
+ a comment banner:
445
+
446
+ ```text
447
+ <!-- kd-cache: upstream=PROJ-A-1 fetched=2026-04-21T10:12:00Z.
448
+ Disposable mirror. Edits lost on refresh. Not authoritative. -->
449
+ ```
450
+
451
+ YAML payloads use `#` comments:
452
+
453
+ ```text
454
+ # kd-cache: upstream=PROJ-105 fetched=2026-04-21T10:12:00Z.
455
+ # Disposable mirror. Edits lost on refresh. Not authoritative.
456
+ ```
457
+
458
+ The banner is informational. It is not a `kd-meta` marker.
459
+
460
+ ### Three operations that look alike
461
+
462
+ These operations all copy text near the repository, but they have different
463
+ ownership rules.
464
+
465
+ | Operation | Destination | Ownership | Mutability |
466
+ |-----------|-------------|-----------|------------|
467
+ | Cache hydrate | `.kd/cache/` | kd-managed | Refresh overwrites; operator never edits. |
468
+ | Article pull as claim | Repo file chosen by operator | Operator | One-shot transfer; operator authors thereafter. |
469
+ | Marker-bridged pull | Repo file with `kd-meta` | Operator | Repo source can push back through the marker. |
470
+
471
+ Only marker-bridged files are part of the ongoing repo-to-upstream publication
472
+ loop.
473
+
474
+ ### Write-gating
475
+
476
+ Commands that mutate upstream require a live tracker. They refuse to operate
477
+ on cache-only context. This includes creating or updating issues, pushing
478
+ articles, changing tags, assigning work, commenting, linking, deleting, and
479
+ transitioning state.
480
+
481
+ No stale cache read can silently become a destructive upstream write.
482
+
483
+ ## Marker-bridged files
484
+
485
+ Most durable knowledge belongs directly upstream as articles. Marker-bridged
486
+ files are the exception for knowledge that must be reviewed in git and also be
487
+ discoverable upstream.
488
+
489
+ A marker-bridged file is one artifact in two forms:
490
+
491
+ - The repo file is authoritative and reviewed in pull requests.
492
+ - The upstream article is a rendered, linkable view.
493
+
494
+ `kd /article push` publishes from the repo file to the upstream article.
495
+ Nothing flows back automatically. If the upstream article changed and the repo
496
+ source needs those edits, the operator runs `kd /article pull`, diffs, and
497
+ merges by hand.
498
+
499
+ The `kd-meta` marker is identity, not tool state:
500
+
501
+ ```html
502
+ <!-- kd-meta
503
+ slug: docs/architecture/example
504
+ upstream-id: 2-123
505
+ -->
506
+ ```
507
+
508
+ Rules:
509
+
510
+ - Push writes the marker on first creation or when resolving a missing/stale
511
+ upstream ID.
512
+ - Commit that one-time marker insertion with the content.
513
+ - Subsequent pushes leave the local file unchanged.
514
+ - Older markers may contain an `upstream-updated` field; kd still reads it for
515
+ compatibility, but new pushes and pulls do not emit it.
516
+ - Every update push performs a live upstream read for conflict detection.
517
+ - Baseline priority is `cache > legacy_marker > none`.
518
+ - If both upstream and repo changed, pull, diff, merge by hand, then push.
519
+ - `--force` is only for an inspected overwrite.
520
+
521
+ ## What's project-specific?
522
+
523
+ The portable doctrine defines the invariant method:
524
+
525
+ - Layer model.
526
+ - Session cycle variants.
527
+ - Verification modes.
528
+ - Publication tiers.
529
+ - Repo-doc audit.
530
+ - Cache semantics.
531
+ - Marker-bridged behavior.
532
+ - Reconciliation flow.
533
+ - Umbrella rule.
534
+
535
+ Project-specific agreements belong in an SDLC profile: a project-local upstream
536
+ article pinned from `.kd/primer.yaml`. Examples:
537
+
538
+ - Document naming.
539
+ - Required metadata fields.
540
+ - Routing tables.
541
+ - Closeout checklists.
542
+ - Timeless-doc rules.
543
+ - Project-specific publication-tier variations.
544
+
545
+ Session-start load sequence becomes:
546
+
547
+ ```text
548
+ primer -> portable doctrine -> project profile -> assigned issue
549
+ ```
550
+
551
+ A project may operate without a profile when it follows the portable doctrine
552
+ verbatim.
553
+
554
+ ## When do I use the umbrella ticket?
555
+
556
+ Each project declares one fixed umbrella ticket in its primer or profile. The
557
+ umbrella exists only to preserve the "no commit without a ticket" rule for work
558
+ that genuinely has no story.
559
+
560
+ Use umbrella for:
561
+
562
+ - Formatting, lint, or whitespace sweeps.
563
+ - Typo and comment fixes.
564
+ - Dependency bumps with no behavior change.
565
+ - Internal hygiene with no narrative.
566
+
567
+ Do not use umbrella for:
568
+
569
+ - Behavior changes.
570
+ - Work that merits a changelog entry.
571
+ - API, test, or documentation-contract changes.
572
+ - Anything a future reader would expect to find under its own issue.
573
+
574
+ Test question: does this commit have a story worth telling? If yes, use a real
575
+ ticket. If no, umbrella is acceptable.
576
+
577
+ ## Migration safety rules
578
+
579
+ When moving repo-local operational docs upstream, keep the migration thin and
580
+ auditable:
581
+
582
+ - Create tag taxonomy and root/index articles first.
583
+ - Migrate in small slices: read, classify, push, read back, verify tags, delete
584
+ local shadow, commit.
585
+ - Do not delete a local document before upstream readback confirms the article
586
+ exists, is readable, and carries intended tags/backrefs.
587
+ - The primer points to the migration plan; it does not track session progress.
588
+ - Do not leave duplicate repo copies unless they satisfy a Layer B category or
589
+ a named compliance/audit exception.
590
+
591
+ ## Accepted tradeoffs
592
+
593
+ - Article history lives in YouTrack page history. There is no git-style
594
+ line-level diff or git blame for ordinary upstream articles.
595
+ - Marker-bridged files preserve repo review for the narrow class of knowledge
596
+ that needs it, at the cost of a manual push step.
597
+ - Cache is read-side only. kd does not run a sync daemon and does not buffer
598
+ upstream mutations while offline.
599
+ - Publication is summarized by value, not by volume. Durable outcomes are kept;
600
+ raw session thinking is not automatically migrated.
601
+
602
+ Updated: 2026-04-27
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: kd-cli
3
- Version: 2.6.0
3
+ Version: 2.6.1
4
4
  Summary: Knowledge Dispatcher for issue trackers and knowledge bases
5
5
  Author: Sergiy Gladkyy
6
6
  License-Expression: MIT
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "kd-cli"
7
- version = "2.6.0"
7
+ version = "2.6.1"
8
8
  description = "Knowledge Dispatcher for issue trackers and knowledge bases"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.11"