org-knowledge-layer 0.4.1__tar.gz → 0.6.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 (144) hide show
  1. org_knowledge_layer-0.6.0/PKG-INFO +33 -0
  2. org_knowledge_layer-0.6.0/README.md +14 -0
  3. org_knowledge_layer-0.6.0/org_knowledge_layer.egg-info/PKG-INFO +33 -0
  4. org_knowledge_layer-0.6.0/org_knowledge_layer.egg-info/SOURCES.txt +8 -0
  5. org_knowledge_layer-0.6.0/org_knowledge_layer.egg-info/dependency_links.txt +1 -0
  6. org_knowledge_layer-0.6.0/org_knowledge_layer.egg-info/entry_points.txt +2 -0
  7. org_knowledge_layer-0.6.0/org_knowledge_layer.egg-info/requires.txt +13 -0
  8. org_knowledge_layer-0.6.0/org_knowledge_layer.egg-info/top_level.txt +1 -0
  9. org_knowledge_layer-0.6.0/pyproject.toml +37 -0
  10. org_knowledge_layer-0.6.0/setup.cfg +4 -0
  11. org_knowledge_layer-0.4.1/.claude/agents/architecture-reviewer.md +0 -41
  12. org_knowledge_layer-0.4.1/.claude/hooks/stop-okl-encode.sh +0 -78
  13. org_knowledge_layer-0.4.1/.claude/hooks/userpromptsubmit-okl-check.sh +0 -68
  14. org_knowledge_layer-0.4.1/.claude/settings.json +0 -24
  15. org_knowledge_layer-0.4.1/.coverage +0 -0
  16. org_knowledge_layer-0.4.1/.github/ISSUE_TEMPLATE/bug_report.md +0 -21
  17. org_knowledge_layer-0.4.1/.github/ISSUE_TEMPLATE/feature_request.md +0 -15
  18. org_knowledge_layer-0.4.1/.github/dependabot.yml +0 -32
  19. org_knowledge_layer-0.4.1/.github/pull_request_template.md +0 -15
  20. org_knowledge_layer-0.4.1/.github/workflows/ci.yml +0 -100
  21. org_knowledge_layer-0.4.1/.github/workflows/okl-verify.yml +0 -85
  22. org_knowledge_layer-0.4.1/.github/workflows/publish.yml +0 -90
  23. org_knowledge_layer-0.4.1/.gitignore +0 -21
  24. org_knowledge_layer-0.4.1/AGENTS.md +0 -63
  25. org_knowledge_layer-0.4.1/CHANGELOG.md +0 -145
  26. org_knowledge_layer-0.4.1/CLAUDE.md +0 -63
  27. org_knowledge_layer-0.4.1/CONTRIBUTING.md +0 -81
  28. org_knowledge_layer-0.4.1/LICENSE +0 -21
  29. org_knowledge_layer-0.4.1/PKG-INFO +0 -743
  30. org_knowledge_layer-0.4.1/README.md +0 -709
  31. org_knowledge_layer-0.4.1/SECURITY.md +0 -56
  32. org_knowledge_layer-0.4.1/ci/check-diagram-figures.sh +0 -82
  33. org_knowledge_layer-0.4.1/ci/okl-verify.yml +0 -85
  34. org_knowledge_layer-0.4.1/ci/review-agent.sh +0 -133
  35. org_knowledge_layer-0.4.1/docs/DEPLOY.md +0 -171
  36. org_knowledge_layer-0.4.1/docs/ab-results-chart.png +0 -0
  37. org_knowledge_layer-0.4.1/docs/ab-results-chart.svg +0 -27
  38. org_knowledge_layer-0.4.1/docs/decisions/2026-07-17-flat-retrieval-until-scale.md +0 -55
  39. org_knowledge_layer-0.4.1/docs/decisions/2026-07-21-subject-tags-controlled-vocabulary.md +0 -59
  40. org_knowledge_layer-0.4.1/docs/okl-how-it-works.excalidraw +0 -3053
  41. org_knowledge_layer-0.4.1/docs/okl-how-it-works.svg +0 -2
  42. org_knowledge_layer-0.4.1/docs/okl-sixth-surface.excalidraw +0 -3819
  43. org_knowledge_layer-0.4.1/docs/okl-sixth-surface.svg +0 -2
  44. org_knowledge_layer-0.4.1/docs/posts/01-memory-that-outlives-the-run.md +0 -65
  45. org_knowledge_layer-0.4.1/docs/posts/02-dont-let-a-step-grade-itself.md +0 -45
  46. org_knowledge_layer-0.4.1/docs/posts/03-enforcement-or-good-intentions.md +0 -37
  47. org_knowledge_layer-0.4.1/evals/README.md +0 -49
  48. org_knowledge_layer-0.4.1/evals/REPORT.md +0 -369
  49. org_knowledge_layer-0.4.1/evals/ab_harness.py +0 -196
  50. org_knowledge_layer-0.4.1/evals/results/ab-20260829-2300.json +0 -41
  51. org_knowledge_layer-0.4.1/evals/results/ab-20260829-2315.json +0 -137
  52. org_knowledge_layer-0.4.1/evals/results/ab-20260830-0003.json +0 -441
  53. org_knowledge_layer-0.4.1/evals/results/ab-20260830-0148.json +0 -441
  54. org_knowledge_layer-0.4.1/evals/results/ab-20260901-0133.json +0 -441
  55. org_knowledge_layer-0.4.1/evals/results/ab-20260901-1238.json +0 -441
  56. org_knowledge_layer-0.4.1/evals/results/e2e-20260830/README.md +0 -23
  57. org_knowledge_layer-0.4.1/evals/results/e2e-20260830/briefed-userpromptsubmit-lint.yml +0 -27
  58. org_knowledge_layer-0.4.1/evals/results/e2e-20260830/control-lint.yml +0 -22
  59. org_knowledge_layer-0.4.1/evals/results/e2e-20260830/hook.log +0 -3
  60. org_knowledge_layer-0.4.1/evals/results/e2e-20260830/service-record-500.log +0 -47
  61. org_knowledge_layer-0.4.1/evals/results/e2e-20260830/session-briefed-pretooluse.txt +0 -3
  62. org_knowledge_layer-0.4.1/evals/results/e2e-20260830/session-briefed-userpromptsubmit.txt +0 -7
  63. org_knowledge_layer-0.4.1/evals/results/e2e-20260830/session-control.txt +0 -3
  64. org_knowledge_layer-0.4.1/evals/tasks.jsonl +0 -8
  65. org_knowledge_layer-0.4.1/gates/check-canon-size.sh +0 -11
  66. org_knowledge_layer-0.4.1/gates/check-diagram-pairs.sh +0 -39
  67. org_knowledge_layer-0.4.1/gates/check-doc-orphans.sh +0 -23
  68. org_knowledge_layer-0.4.1/gates/check-links.sh +0 -41
  69. org_knowledge_layer-0.4.1/gates/check-retractions.sh +0 -22
  70. org_knowledge_layer-0.4.1/gates/check-tombstones.sh +0 -22
  71. org_knowledge_layer-0.4.1/gates/run-gates.sh +0 -33
  72. org_knowledge_layer-0.4.1/hooks/stop-okl-encode.sh +0 -78
  73. org_knowledge_layer-0.4.1/hooks/userpromptsubmit-okl-check.sh +0 -68
  74. org_knowledge_layer-0.4.1/pyproject.toml +0 -118
  75. org_knowledge_layer-0.4.1/seed/dotnet-canon.json +0 -489
  76. org_knowledge_layer-0.4.1/seed/dotnet-decisions.json +0 -328
  77. org_knowledge_layer-0.4.1/seed/dotnet-defects.json +0 -133
  78. org_knowledge_layer-0.4.1/seed/dotnet-review-surfaces.json +0 -147
  79. org_knowledge_layer-0.4.1/seed/frontend-canon.json +0 -116
  80. org_knowledge_layer-0.4.1/seed/geospatial-deeptime-defects.json +0 -59
  81. org_knowledge_layer-0.4.1/seed/geospatial-defects.json +0 -154
  82. org_knowledge_layer-0.4.1/seed/geospatial-enforcement-defects.json +0 -121
  83. org_knowledge_layer-0.4.1/seed/geospatial-eval-defects.json +0 -25
  84. org_knowledge_layer-0.4.1/seed/rag-defects.json +0 -120
  85. org_knowledge_layer-0.4.1/seed/react-defects.json +0 -45
  86. org_knowledge_layer-0.4.1/src/okl/__init__.py +0 -12
  87. org_knowledge_layer-0.4.1/src/okl/__main__.py +0 -8
  88. org_knowledge_layer-0.4.1/src/okl/bootstrap.py +0 -89
  89. org_knowledge_layer-0.4.1/src/okl/cli.py +0 -729
  90. org_knowledge_layer-0.4.1/src/okl/client.py +0 -249
  91. org_knowledge_layer-0.4.1/src/okl/core.py +0 -524
  92. org_knowledge_layer-0.4.1/src/okl/drift.py +0 -134
  93. org_knowledge_layer-0.4.1/src/okl/mcp_server.py +0 -112
  94. org_knowledge_layer-0.4.1/src/okl/scaffold/MANIFEST.md +0 -67
  95. org_knowledge_layer-0.4.1/src/okl/scaffold/ci/dependabot.yml +0 -17
  96. org_knowledge_layer-0.4.1/src/okl/scaffold/ci/method-gates.yml +0 -74
  97. org_knowledge_layer-0.4.1/src/okl/scaffold/ci/okl-verify.yml +0 -85
  98. org_knowledge_layer-0.4.1/src/okl/scaffold/ci/review-agent.sh +0 -133
  99. org_knowledge_layer-0.4.1/src/okl/scaffold/claude/agents/architecture-reviewer.md +0 -41
  100. org_knowledge_layer-0.4.1/src/okl/scaffold/claude/commands/check-rules.md +0 -24
  101. org_knowledge_layer-0.4.1/src/okl/scaffold/claude/commands/feature-spec.md +0 -37
  102. org_knowledge_layer-0.4.1/src/okl/scaffold/claude/commands/seed-from-codebase.md +0 -90
  103. org_knowledge_layer-0.4.1/src/okl/scaffold/claude/commands/seed-from-docs.md +0 -123
  104. org_knowledge_layer-0.4.1/src/okl/scaffold/claude/rules/example-area.md +0 -22
  105. org_knowledge_layer-0.4.1/src/okl/scaffold/claude/skills/RECOMMENDED-COMPANIONS.md +0 -40
  106. org_knowledge_layer-0.4.1/src/okl/scaffold/claude/skills/encoding-loop/SKILL.md +0 -48
  107. org_knowledge_layer-0.4.1/src/okl/scaffold/claude/skills/verify-before-claiming/SKILL.md +0 -56
  108. org_knowledge_layer-0.4.1/src/okl/scaffold/evals/README.md +0 -32
  109. org_knowledge_layer-0.4.1/src/okl/scaffold/evals/cases.jsonl +0 -1
  110. org_knowledge_layer-0.4.1/src/okl/scaffold/evals/run_evals.py +0 -109
  111. org_knowledge_layer-0.4.1/src/okl/scaffold/gates/check-canon-size.sh +0 -11
  112. org_knowledge_layer-0.4.1/src/okl/scaffold/gates/check-diagram-pairs.sh +0 -39
  113. org_knowledge_layer-0.4.1/src/okl/scaffold/gates/check-doc-orphans.sh +0 -23
  114. org_knowledge_layer-0.4.1/src/okl/scaffold/gates/check-links.sh +0 -41
  115. org_knowledge_layer-0.4.1/src/okl/scaffold/gates/check-retractions.sh +0 -22
  116. org_knowledge_layer-0.4.1/src/okl/scaffold/gates/check-tombstones.sh +0 -22
  117. org_knowledge_layer-0.4.1/src/okl/scaffold/gates/run-gates.sh +0 -33
  118. org_knowledge_layer-0.4.1/src/okl/scaffold/hooks/hooks.json +0 -16
  119. org_knowledge_layer-0.4.1/src/okl/scaffold/hooks/stop-okl-encode.sh +0 -78
  120. org_knowledge_layer-0.4.1/src/okl/scaffold/hooks/userpromptsubmit-okl-check.sh +0 -68
  121. org_knowledge_layer-0.4.1/src/okl/scaffold/plugin/plugin.json +0 -10
  122. org_knowledge_layer-0.4.1/src/okl/scaffold/profiles/dotnet/README.md +0 -12
  123. org_knowledge_layer-0.4.1/src/okl/scaffold/profiles/dotnet/rules/architecture.md +0 -55
  124. org_knowledge_layer-0.4.1/src/okl/scaffold/profiles/dotnet/rules/messaging.md +0 -31
  125. org_knowledge_layer-0.4.1/src/okl/scaffold/profiles/dotnet/rules/performance-and-data.md +0 -36
  126. org_knowledge_layer-0.4.1/src/okl/scaffold/profiles/dotnet/rules/security.md +0 -42
  127. org_knowledge_layer-0.4.1/src/okl/scaffold/profiles/geospatial/README.md +0 -6
  128. org_knowledge_layer-0.4.1/src/okl/scaffold/profiles/geospatial/rules/geospatial-ml.md +0 -38
  129. org_knowledge_layer-0.4.1/src/okl/scaffold/profiles/python-rag/README.md +0 -13
  130. org_knowledge_layer-0.4.1/src/okl/scaffold/profiles/python-rag/rules/fastapi-backend.md +0 -37
  131. org_knowledge_layer-0.4.1/src/okl/scaffold/profiles/python-rag/rules/project-structure.md +0 -28
  132. org_knowledge_layer-0.4.1/src/okl/scaffold/profiles/python-rag/rules/rag-pipeline.md +0 -73
  133. org_knowledge_layer-0.4.1/src/okl/scaffold/profiles/react/README.md +0 -18
  134. org_knowledge_layer-0.4.1/src/okl/scaffold/profiles/react/rules/frontend.md +0 -57
  135. org_knowledge_layer-0.4.1/src/okl/scaffold/registries/RETRACTIONS.md +0 -19
  136. org_knowledge_layer-0.4.1/src/okl/scaffold/registries/tombstones.txt +0 -7
  137. org_knowledge_layer-0.4.1/src/okl/scaffold/root/CLAUDE.md +0 -55
  138. org_knowledge_layer-0.4.1/src/okl/scaffold/root/METHOD.md +0 -64
  139. org_knowledge_layer-0.4.1/src/okl/scaffold_cmd.py +0 -129
  140. org_knowledge_layer-0.4.1/src/okl/seed.py +0 -119
  141. org_knowledge_layer-0.4.1/src/okl/service.py +0 -181
  142. org_knowledge_layer-0.4.1/src/okl/store.py +0 -524
  143. org_knowledge_layer-0.4.1/tests/test_okl.py +0 -1333
  144. org_knowledge_layer-0.4.1/tests/test_scaffold.py +0 -557
@@ -0,0 +1,33 @@
1
+ Metadata-Version: 2.4
2
+ Name: org-knowledge-layer
3
+ Version: 0.6.0
4
+ Summary: Renamed: install observed-knowledge-ledger. This package only depends on it.
5
+ Author: Joshua Dell
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/emeraldleaf/okl
8
+ Requires-Python: >=3.10
9
+ Description-Content-Type: text/markdown
10
+ Requires-Dist: observed-knowledge-ledger>=0.6.0
11
+ Provides-Extra: service
12
+ Requires-Dist: observed-knowledge-ledger[service]>=0.6.0; extra == "service"
13
+ Provides-Extra: postgres
14
+ Requires-Dist: observed-knowledge-ledger[postgres]>=0.6.0; extra == "postgres"
15
+ Provides-Extra: mcp
16
+ Requires-Dist: observed-knowledge-ledger[mcp]>=0.6.0; extra == "mcp"
17
+ Provides-Extra: all
18
+ Requires-Dist: observed-knowledge-ledger[all]>=0.6.0; extra == "all"
19
+
20
+ # org-knowledge-layer → observed-knowledge-ledger
21
+
22
+ This package has been renamed. Install the new one:
23
+
24
+ ```bash
25
+ pipx install observed-knowledge-ledger
26
+ ```
27
+
28
+ `okl` — the command, the import package and the `.okl/` folder — is unchanged. This final
29
+ release of `org-knowledge-layer` contains no code; it only depends on
30
+ `observed-knowledge-ledger`, so existing installs and CI steps keep working. Switch the name
31
+ when convenient.
32
+
33
+ Project: https://github.com/emeraldleaf/okl
@@ -0,0 +1,14 @@
1
+ # org-knowledge-layer → observed-knowledge-ledger
2
+
3
+ This package has been renamed. Install the new one:
4
+
5
+ ```bash
6
+ pipx install observed-knowledge-ledger
7
+ ```
8
+
9
+ `okl` — the command, the import package and the `.okl/` folder — is unchanged. This final
10
+ release of `org-knowledge-layer` contains no code; it only depends on
11
+ `observed-knowledge-ledger`, so existing installs and CI steps keep working. Switch the name
12
+ when convenient.
13
+
14
+ Project: https://github.com/emeraldleaf/okl
@@ -0,0 +1,33 @@
1
+ Metadata-Version: 2.4
2
+ Name: org-knowledge-layer
3
+ Version: 0.6.0
4
+ Summary: Renamed: install observed-knowledge-ledger. This package only depends on it.
5
+ Author: Joshua Dell
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/emeraldleaf/okl
8
+ Requires-Python: >=3.10
9
+ Description-Content-Type: text/markdown
10
+ Requires-Dist: observed-knowledge-ledger>=0.6.0
11
+ Provides-Extra: service
12
+ Requires-Dist: observed-knowledge-ledger[service]>=0.6.0; extra == "service"
13
+ Provides-Extra: postgres
14
+ Requires-Dist: observed-knowledge-ledger[postgres]>=0.6.0; extra == "postgres"
15
+ Provides-Extra: mcp
16
+ Requires-Dist: observed-knowledge-ledger[mcp]>=0.6.0; extra == "mcp"
17
+ Provides-Extra: all
18
+ Requires-Dist: observed-knowledge-ledger[all]>=0.6.0; extra == "all"
19
+
20
+ # org-knowledge-layer → observed-knowledge-ledger
21
+
22
+ This package has been renamed. Install the new one:
23
+
24
+ ```bash
25
+ pipx install observed-knowledge-ledger
26
+ ```
27
+
28
+ `okl` — the command, the import package and the `.okl/` folder — is unchanged. This final
29
+ release of `org-knowledge-layer` contains no code; it only depends on
30
+ `observed-knowledge-ledger`, so existing installs and CI steps keep working. Switch the name
31
+ when convenient.
32
+
33
+ Project: https://github.com/emeraldleaf/okl
@@ -0,0 +1,8 @@
1
+ README.md
2
+ pyproject.toml
3
+ org_knowledge_layer.egg-info/PKG-INFO
4
+ org_knowledge_layer.egg-info/SOURCES.txt
5
+ org_knowledge_layer.egg-info/dependency_links.txt
6
+ org_knowledge_layer.egg-info/entry_points.txt
7
+ org_knowledge_layer.egg-info/requires.txt
8
+ org_knowledge_layer.egg-info/top_level.txt
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ okl = okl.cli:main
@@ -0,0 +1,13 @@
1
+ observed-knowledge-ledger>=0.6.0
2
+
3
+ [all]
4
+ observed-knowledge-ledger[all]>=0.6.0
5
+
6
+ [mcp]
7
+ observed-knowledge-ledger[mcp]>=0.6.0
8
+
9
+ [postgres]
10
+ observed-knowledge-ledger[postgres]>=0.6.0
11
+
12
+ [service]
13
+ observed-knowledge-ledger[service]>=0.6.0
@@ -0,0 +1,37 @@
1
+ # The old distribution name, kept installable. okl was published as org-knowledge-layer
2
+ # until 0.5.0 and renamed to observed-knowledge-ledger (the name now says what is different
3
+ # about it: knowledge proven by observed checks). PyPI cannot rename a project, so this
4
+ # final release carries no code and depends on the new name; installs of the old name,
5
+ # extras included, keep working. publish.yml builds it only on the tag matching `version`.
6
+ [build-system]
7
+ requires = ["setuptools>=68"]
8
+ build-backend = "setuptools.build_meta"
9
+
10
+ [project]
11
+ name = "org-knowledge-layer"
12
+ version = "0.6.0"
13
+ description = "Renamed: install observed-knowledge-ledger. This package only depends on it."
14
+ readme = "README.md"
15
+ requires-python = ">=3.10"
16
+ license = { text = "MIT" }
17
+ authors = [{ name = "Joshua Dell" }]
18
+ dependencies = ["observed-knowledge-ledger>=0.6.0"]
19
+
20
+ [project.optional-dependencies]
21
+ service = ["observed-knowledge-ledger[service]>=0.6.0"]
22
+ postgres = ["observed-knowledge-ledger[postgres]>=0.6.0"]
23
+ mcp = ["observed-knowledge-ledger[mcp]>=0.6.0"]
24
+ all = ["observed-knowledge-ledger[all]>=0.6.0"]
25
+
26
+ # The same `okl` command, pointing at code the dependency installs. Without it, `pipx
27
+ # install org-knowledge-layer` refuses outright: pipx exposes only the named package's own
28
+ # apps, never a dependency's, and a code-free package has none (found in review of #46,
29
+ # reproduced with pipx before this line was added).
30
+ [project.scripts]
31
+ okl = "okl.cli:main"
32
+
33
+ [project.urls]
34
+ Homepage = "https://github.com/emeraldleaf/okl"
35
+
36
+ [tool.setuptools]
37
+ packages = []
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -1,41 +0,0 @@
1
- ---
2
- name: architecture-reviewer
3
- description: Reviews a diff or a proposed change against this repo's encoded rules and the org knowledge layer. Invoke on non-pattern-conforming changes (new bounded context, novel dependency, security-model change, multi-step refactor) and before merging anything touching published results. Returns a pattern-checklist verdict, not a rewrite.
4
- tools: Read, Grep, Glob, Bash
5
- model: inherit
6
- memory: project # persists to .claude/agent-memory/architecture-reviewer/ (committed, team-shared)
7
- skills:
8
- - encoding-loop
9
- ---
10
-
11
- # Architecture reviewer
12
-
13
- You are a reviewer, not an implementer. You read the change and judge it against the encoded body —
14
- you do not rewrite it. Your output is a checklist verdict with specific file:line findings.
15
-
16
- ## Before you start
17
- 1. Run `okl check --task "<one-line summary of the change under review>"` and treat the returned
18
- armed gates, retractions, tombstones, and THREAT prior-art as binding review criteria.
19
- 2. Read `.claude/rules/` entries whose `paths:` match the changed files.
20
-
21
- ## Pattern checklist (extend as the repo encodes new rules)
22
- - **Smallest-surface / speculative coupling** — is there an abstraction (interface, factory, layer)
23
- with exactly one implementation and no test substitution and no concrete second impl on the
24
- roadmap? If so, flag it as speculative — the concrete class should be used directly.
25
- - **Assert-from-memory** — does any spec/config/scaffold claim something is "correct"/"valid"
26
- without a mechanical `validate` step? Flag it; this is the #14-class defect.
27
- - **Retracted claim restated** — does any prose restate a claim in `registries/RETRACTIONS.md`
28
- without also retracting it? Fail.
29
- - **Resurrected identifier** — does the diff reintroduce anything in `registries/tombstones.txt`? Fail.
30
- - **Missing gate receipt** — does a fix reference a defect class that has a gate, without the gate
31
- running in CI on this change?
32
- - **Report-the-result** — if this change is a "fix" that confirms a hypothesis, was the control run?
33
-
34
- <!-- <<FILL: STACK-SPECIFIC REVIEW CHECKS>>
35
- Add checks specific to this stack (e.g. IDOR predicate in the SQL Where clause; N+1 queries;
36
- async-over-sync; mass-assignment of server-controlled fields). Keep each as one scan rule. -->
37
-
38
- ## Memory
39
- Use your persistent memory dir to accumulate this repo's recurring findings and architectural
40
- decisions across reviews. When you see the same finding class a third time, propose promoting it to
41
- a mechanical gate (surface 5) via the encoding-loop skill.
@@ -1,78 +0,0 @@
1
- #!/usr/bin/env bash
2
- # Stop hook — the write-side mechanical catch for the encoding loop.
3
- #
4
- # The read side (okl check) is enforced by the PreToolUse hook; nothing enforced the WRITE
5
- # side, so a session could end without recording what it learned ("a merged fix without the
6
- # rule is a half-finished job"). This hook asks the question at the ship moment, once:
7
- # if the session changed the working tree, block the first stop (exit 2) with a prompt to
8
- # either `okl record` the lesson or state that there is none. It never fires twice in one
9
- # session (marker file) and never loops (stop_hook_active guard).
10
- set -uo pipefail
11
-
12
- # Same resolver as pretooluse-okl-check.sh (env → pinned config → PATH → python3 -m okl);
13
- # the reminder is best-effort, so an unresolvable okl silently disables it rather than blocking.
14
- resolve_okl() {
15
- if [ -n "${OKL_BIN:-}" ]; then printf '%s' "$OKL_BIN"; return 0; fi
16
- local d="$PWD"
17
- while [ "$d" != "/" ]; do
18
- if [ -f "$d/.okl/config.json" ]; then
19
- local bin
20
- bin=$(python3 -c 'import json,sys; print(json.load(open(sys.argv[1])).get("okl_bin") or "")' \
21
- "$d/.okl/config.json" 2>/dev/null || true)
22
- if [ -n "$bin" ]; then printf '%s' "$bin"; return 0; fi
23
- break
24
- fi
25
- d=$(dirname "$d")
26
- done
27
- if command -v okl >/dev/null 2>&1; then printf '%s' "okl"; return 0; fi
28
- if python3 -c "import okl" >/dev/null 2>&1; then printf '%s' "python3 -m okl"; return 0; fi
29
- return 1
30
- }
31
-
32
- OKL=$(resolve_okl) || exit 0
33
-
34
- payload=$(cat 2>/dev/null || true)
35
- parsed=$(printf '%s' "$payload" | python3 -c '
36
- import json, sys
37
- try:
38
- d = json.load(sys.stdin)
39
- except Exception:
40
- d = {}
41
- print(d.get("session_id", ""))
42
- print("true" if d.get("stop_hook_active") else "false")
43
- ' 2>/dev/null) || parsed=""
44
- session_id=$(printf '%s\n' "$parsed" | sed -n 1p)
45
- stop_hook_active=$(printf '%s\n' "$parsed" | sed -n 2p)
46
- [ -n "$stop_hook_active" ] || stop_hook_active="false"
47
-
48
- # Never loop: if we already blocked once and Claude is stopping again, let it stop.
49
- [ "${stop_hook_active}" = "true" ] && exit 0
50
-
51
- # Only fire when the session plausibly did work: uncommitted changes, or a commit in the
52
- # last hour (covers commit-then-stop sessions).
53
- changed=0
54
- if [ -n "$(git status --porcelain 2>/dev/null)" ]; then
55
- changed=1
56
- elif last=$(git log -1 --format=%ct 2>/dev/null); then
57
- now=$(date +%s)
58
- [ $((now - last)) -lt 3600 ] && changed=1
59
- fi
60
- [ "$changed" = "1" ] || exit 0
61
-
62
- # Once per session (fall back to a repo-scoped marker when no session id is provided).
63
- marker="${TMPDIR:-/tmp}/okl-encode-reminder-${session_id:-$(pwd | cksum | cut -d' ' -f1)}"
64
- [ -e "$marker" ] && exit 0
65
- touch "$marker" 2>/dev/null || true
66
-
67
- cat >&2 <<'MSG'
68
- ENCODING LOOP — before this session ends: did it surface a lesson worth keeping?
69
- A non-obvious failure mode, a rule discovered the hard way, a decision that shouldn't be
70
- silently reversed? If yes, record it now (choose the scope deliberately — 'org' spreads
71
- to every repo, 'repo' stays local — and tag the subject):
72
-
73
- okl record --type Defect|Rule|Decision --scope org|repo --tags "<subjects>" \
74
- --title "..." --symptom "..." --body "cause: ..." --fix "..."
75
-
76
- If the session genuinely learned nothing durable, state that explicitly and finish.
77
- MSG
78
- exit 2
@@ -1,68 +0,0 @@
1
- #!/usr/bin/env bash
2
- # UserPromptSubmit hook — inject the org's relevant lessons into the model's context
3
- # BEFORE it starts the task. This event is the only correct one for delivery: its stdout
4
- # (exit 0) is added to Claude's context, and its stdin carries the actual prompt text, so
5
- # the briefing is retrieved for the task the user really asked for.
6
- #
7
- # (The earlier PreToolUse version fired on every edit and printed the briefing to a channel
8
- # the model never sees — PreToolUse exit-0 stdout goes to the transcript only. Discovered by
9
- # an end-to-end test: hook fired, briefing correct, defect reproduced anyway.)
10
- #
11
- # FAILS CLOSED via exit 2: if the knowledge layer is unreachable, the prompt is blocked
12
- # rather than letting the agent proceed blind. A check that reports "clean" while broken is
13
- # worse than no check.
14
- set -uo pipefail
15
-
16
- # Resolve how to invoke okl (env → pinned config → PATH → python3 -m okl); hooks run in
17
- # whatever environment the harness spawns, which often lacks the venv/pipx bin dir.
18
- resolve_okl() {
19
- if [ -n "${OKL_BIN:-}" ]; then printf '%s' "$OKL_BIN"; return 0; fi
20
- local d="$PWD"
21
- while [ "$d" != "/" ]; do
22
- if [ -f "$d/.okl/config.json" ]; then
23
- local bin
24
- bin=$(python3 -c 'import json,sys; print(json.load(open(sys.argv[1])).get("okl_bin") or "")' \
25
- "$d/.okl/config.json" 2>/dev/null || true)
26
- if [ -n "$bin" ]; then printf '%s' "$bin"; return 0; fi
27
- break
28
- fi
29
- d=$(dirname "$d")
30
- done
31
- if command -v okl >/dev/null 2>&1; then printf '%s' "okl"; return 0; fi
32
- if python3 -c "import okl" >/dev/null 2>&1; then printf '%s' "python3 -m okl"; return 0; fi
33
- return 1
34
- }
35
-
36
- if ! OKL=$(resolve_okl); then
37
- [ "${OKL_OFFLINE:-0}" = "1" ] && exit 0
38
- echo "okl NOT FOUND — blocking (a check that can't run must not pass as clean)." >&2
39
- echo "Install it (pip install okl), set OKL_BIN, or re-run 'okl init' from a shell where it" >&2
40
- echo "works (pins okl_bin into .okl/config.json). OKL_OFFLINE=1 proceeds without the layer." >&2
41
- exit 2
42
- fi
43
-
44
- # The task is the prompt itself (stdin JSON: {"prompt": "..."}); OKL_TASK overrides;
45
- # last-commit-message is only the fallback of last resort.
46
- payload=$(cat 2>/dev/null || true)
47
- prompt=$(printf '%s' "$payload" | python3 -c '
48
- import json, sys
49
- try:
50
- print((json.load(sys.stdin).get("prompt") or "").strip()[:2000])
51
- except Exception:
52
- print("")
53
- ' 2>/dev/null || true)
54
- TASK="${OKL_TASK:-${prompt:-$(git log -1 --pretty=%s 2>/dev/null || echo 'general work')}}"
55
-
56
- # $OKL unquoted on purpose: it may be a command + args ("python3 -m okl").
57
- if out=$($OKL check --task "$TASK" --format agent 2>/dev/null); then
58
- printf '%s\n' "$out" # stdout → the model's context
59
- exit 0
60
- fi
61
-
62
- if [ "${OKL_OFFLINE:-0}" = "1" ]; then
63
- echo "OKL offline (OKL_OFFLINE=1 acknowledged) — proceeding without the layer." >&2
64
- exit 0
65
- fi
66
- echo "OKL UNREACHABLE — blocking this prompt. A check that reports 'clean' while broken is worse than no check." >&2
67
- echo "Fix connectivity, or set OKL_OFFLINE=1 to explicitly proceed without the org knowledge layer." >&2
68
- exit 2
@@ -1,24 +0,0 @@
1
- {
2
- "hooks": {
3
- "Stop": [
4
- {
5
- "hooks": [
6
- {
7
- "type": "command",
8
- "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/stop-okl-encode.sh"
9
- }
10
- ]
11
- }
12
- ],
13
- "UserPromptSubmit": [
14
- {
15
- "hooks": [
16
- {
17
- "type": "command",
18
- "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/userpromptsubmit-okl-check.sh"
19
- }
20
- ]
21
- }
22
- ]
23
- }
24
- }
Binary file
@@ -1,21 +0,0 @@
1
- ---
2
- name: Bug report
3
- about: Something behaves differently than documented
4
- labels: bug
5
- ---
6
-
7
- **What you ran** (the exact command, and `okl --help` version if relevant)
8
-
9
- **What you expected**
10
-
11
- **What actually happened** (paste the real output, not a summary)
12
-
13
- **Environment**
14
- - OS:
15
- - Python:
16
- - Installed via: `pip install org-knowledge-layer` / `pip install -e .`
17
- - Mode: local store / shared service
18
-
19
- **Especially useful:** if the tool reported success it had not earned (a check that
20
- passed without running, a stamp without evidence, a hook that fired but changed
21
- nothing), say so explicitly. That class of defect is this project's subject.
@@ -1,15 +0,0 @@
1
- ---
2
- name: Proposal
3
- about: Suggest a change to how the loop works
4
- labels: proposal
5
- ---
6
-
7
- **The symptom you hit** (what went wrong in real use, not the feature you want)
8
-
9
- **Why the current design does not cover it**
10
-
11
- **What you would change**
12
-
13
- **How you would know it worked** — the check, measurement, or test that would show it.
14
- Proposals that name their own evidence get adopted faster; see `evals/REPORT.md` for
15
- the standard this repo holds itself to.
@@ -1,32 +0,0 @@
1
- # Dependabot.
2
- #
3
- # This exists because of the SHA pinning, not despite it. Pinning actions to a commit
4
- # closes the "a mutable tag moved under me" hole and opens a quieter one: the pin never
5
- # updates, so a security fix in an action never arrives. Pinning without an update path
6
- # is how a repo ends up on a two-year-old checkout action and calls it hardening.
7
- # Dependabot rewrites the SHA and the trailing `# v5` comment together.
8
- version: 2
9
-
10
- updates:
11
- - package-ecosystem: github-actions
12
- directory: "/"
13
- schedule:
14
- interval: weekly
15
- labels: ["dependencies", "ci"]
16
- commit-message:
17
- prefix: "ci"
18
-
19
- - package-ecosystem: pip
20
- directory: "/"
21
- schedule:
22
- interval: weekly
23
- labels: ["dependencies"]
24
- commit-message:
25
- prefix: "deps"
26
- # The gating tools are pinned exactly on purpose (a range lets a new release
27
- # retro-fail a branch that changed nothing). Dependabot is the intended way to move
28
- # those pins: a PR that runs the full suite against the new version before it lands,
29
- # rather than a range that upgrades silently mid-branch.
30
- groups:
31
- dev-tooling:
32
- patterns: ["pytest", "ruff", "mypy"]
@@ -1,15 +0,0 @@
1
- ## What changed
2
-
3
- ## Why
4
-
5
- ## What you ran to check it
6
-
7
- <!-- Paste real output. `pytest -q`, `ruff check .`, and `okl drift` at minimum. -->
8
-
9
- ## Checklist
10
-
11
- - [ ] `pytest -q` green
12
- - [ ] `ruff check .` clean
13
- - [ ] `okl drift` green, or affected records re-verified with `okl verify --run`
14
- - [ ] Mirror files still byte-identical (`ci/`, `.github/workflows/`, `hooks/` and their `src/okl/scaffold/` twins)
15
- - [ ] Any number quoted has a committed receipt in `evals/results/`
@@ -1,100 +0,0 @@
1
- # Repo CI — lints, type-checks and tests okl itself. (okl-verify.yml is different: it
2
- # demonstrates the product's own drift/method gates, the workflow consumers copy.)
3
- #
4
- # Hardened per the org rule this repo's own store carries ("CI workflow baseline:
5
- # pipefail, no persisted credentials, least-privilege permissions, concurrency groups —
6
- # pin actions"). It satisfied none of the five until this commit, which is the rule's own
7
- # symptom: an enforcement surface nothing triggers runs never.
8
- name: ci
9
-
10
- on:
11
- push:
12
- branches: [ "main" ]
13
- pull_request:
14
- branches: [ "main" ]
15
-
16
- # Least privilege: this job reads code and reports status. It never pushes.
17
- permissions:
18
- contents: read
19
-
20
- # One run per ref. A superseded push should stop burning minutes on a result nobody
21
- # will read.
22
- concurrency:
23
- group: ci-${{ github.ref }}
24
- cancel-in-progress: true
25
-
26
- defaults:
27
- run:
28
- # Without pipefail a run block continues past a failed segment of a pipeline, so a
29
- # green step can hide a red command.
30
- shell: bash -euo pipefail {0}
31
-
32
- jobs:
33
- lint-and-test:
34
- runs-on: ubuntu-latest
35
- steps:
36
- # Actions pinned to a commit SHA, not a tag: a tag is mutable, so `@v5` is an
37
- # unpinned dependency with write access to the runner.
38
- - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
39
- with:
40
- # The diagram gate reads committed history (git show HEAD:...), not the
41
- # checkout tree, so it needs more than the default shallow fetch.
42
- fetch-depth: 0
43
- # This job never pushes; leaving the token in .git/config lets any later step
44
- # (or a compromised dependency) use it.
45
- persist-credentials: false
46
-
47
- - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
48
- with:
49
- python-version: "3.12"
50
-
51
- - name: Install (dev extras)
52
- run: pip install -e ".[dev]"
53
-
54
- - name: Lint — ruff (config in pyproject.toml)
55
- run: ruff check .
56
-
57
- - name: Types — mypy
58
- run: mypy src/okl
59
-
60
- - name: Tests (with the coverage ratchet)
61
- run: pytest -q --cov=okl
62
-
63
- - name: Diagram figures trace to committed receipts
64
- run: ./ci/check-diagram-figures.sh
65
-
66
- # The content audits okl ships to consumers, run against okl itself. They were
67
- # shipped for weeks without this repo running any of them — the "enforcement
68
- # surface nothing triggers" failure, one level up: a gate whose author has never
69
- # run it on their own tree.
70
- - name: Method gates (links, doc orphans, diagram pairs, tombstones, canon size)
71
- run: bash gates/run-gates.sh
72
-
73
- # Secret scan over the FULL history, not the working tree. okl writes a bearer
74
- # token into .okl/config.json, and the .gitignore it now drops there is the only
75
- # thing between that and a commit — this is the check for when that fails.
76
- #
77
- # The upstream gitleaks-action is deliberately not used: it requires a paid licence
78
- # key for organization-owned repositories, so it would break for anyone who forks
79
- # this into an org. The binary has no such condition, and pinning the release keeps
80
- # a new detection rule from retro-failing a branch that changed nothing.
81
- # The reviewer okl ships, run on okl. It was listed as a review surface with nothing
82
- # triggering it — the "enforcement surface that only runs on-demand runs never"
83
- # failure this repo's own store names. Off unless REVIEW_CMD is set, so it costs
84
- # nothing until someone decides it should.
85
- - name: Architecture review (off unless REVIEW_CMD is set)
86
- if: github.event_name == 'pull_request'
87
- env:
88
- REVIEW_CMD: ${{ vars.REVIEW_CMD }}
89
- ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
90
- REVIEW_BASE_REF: origin/${{ github.base_ref }}
91
- run: bash ci/review-agent.sh
92
-
93
- - name: Secret scan — gitleaks
94
- env:
95
- GITLEAKS_VERSION: "8.30.1"
96
- run: |
97
- curl -sSfL -o /tmp/gitleaks.tar.gz \
98
- "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz"
99
- tar -xzf /tmp/gitleaks.tar.gz -C /tmp gitleaks
100
- /tmp/gitleaks git . --no-banner --redact --exit-code 1
@@ -1,85 +0,0 @@
1
- # Installed by `okl init` into .github/workflows/okl-verify.yml (also stamped by `okl scaffold`).
2
- #
3
- # The knowledge layer's CI verifier — real checks, not placeholders:
4
- # 1. `okl drift --gate` — fails the build when a rule's governed files changed after the
5
- # rule was last verified (a stale rule is a rule nobody re-checked).
6
- # 2. `gates/run-gates.sh` — the repo's mechanical method gates, when the scaffold is present.
7
- #
8
- # Shared-layer connection is optional: without OKL_SERVICE_URL the drift gate runs against
9
- # the repo's local .okl store. Configure the secrets to verify against the org layer and to
10
- # let gate scripts emit receipts (`okl link <gate_id> VERIFIED_ON <defect_id>`) — emit those
11
- # from inside the gate that proved itself against real drift, where the ids are known.
12
- name: okl-verify
13
-
14
- on:
15
- pull_request:
16
- push:
17
- branches: [main]
18
-
19
- # Least privilege: this workflow reads code and reports a status. It never writes.
20
- permissions:
21
- contents: read
22
-
23
- concurrency:
24
- group: okl-verify-${{ github.ref }}
25
- cancel-in-progress: true
26
-
27
- defaults:
28
- run:
29
- # Without pipefail a run block continues past a failed segment of a pipeline, so a
30
- # green step can hide a red command.
31
- shell: bash -euo pipefail {0}
32
-
33
- jobs:
34
- okl-verify:
35
- runs-on: ubuntu-latest
36
- env:
37
- # Set at job level so every okl command below resolves the shared layer from the
38
- # environment. This replaces an `okl connect --token` step, which wrote the bearer
39
- # token into .okl/config.json on the runner — needless, since the client reads both
40
- # variables directly, and one more place for a credential to end up.
41
- # Unset secrets leave these empty, and okl falls back to the repo-local store.
42
- OKL_SERVICE_URL: ${{ secrets.OKL_SERVICE_URL }}
43
- OKL_TOKEN: ${{ secrets.OKL_TOKEN }}
44
- steps:
45
- # Actions are pinned to a commit SHA: a tag is mutable, so `@v5` is an unpinned
46
- # dependency with access to your runner. If you copy this file into your own repo,
47
- # add a .github/dependabot.yml with the `github-actions` ecosystem so these pins get
48
- # security updates — a pin with no update path goes stale and that is its own risk.
49
- - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
50
- with:
51
- fetch-depth: 0 # drift needs history: it compares governed-file commits vs verified_at
52
- persist-credentials: false # this job never pushes
53
-
54
- - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
55
- with:
56
- python-version: "3.13"
57
-
58
- - name: Install okl
59
- # Detect by the package source, not the distribution name: the name changed once
60
- # (PyPI rejects "okl" as confusable) and a name-based check silently broke with it.
61
- run: |
62
- if [ -f src/okl/cli.py ]; then
63
- pip install -e .
64
- else
65
- pip install org-knowledge-layer
66
- fi
67
-
68
- - name: Report which store the gate will run against
69
- run: |
70
- if [ -n "${OKL_SERVICE_URL:-}" ]; then
71
- echo "verifying against the shared layer at $OKL_SERVICE_URL"
72
- else
73
- echo "no OKL_SERVICE_URL secret — verifying against the repo-local store"
74
- fi
75
-
76
- - name: Drift gate — rules whose governed code changed after last verification
77
- run: okl drift --gate
78
-
79
- - name: Method gates (when the scaffold kit is present)
80
- run: |
81
- if [ -x gates/run-gates.sh ]; then
82
- bash gates/run-gates.sh
83
- else
84
- echo "no gates/run-gates.sh — method-kit gates not installed (okl scaffold adds them)"
85
- fi