org-knowledge-layer 0.1.2__tar.gz → 0.1.3__tar.gz

{org_knowledge_layer-0.1.2 → org_knowledge_layer-0.1.3}/.claude/settings.local.json

@@ -90,7 +90,14 @@
       "Bash(git -c core.hooksPath=/dev/null commit -qm 'Post 1: concede the crowded category, name the narrow differentiator *)",
       "Bash(git -c core.hooksPath=/dev/null commit -qm 'Public-repo hygiene: SECURITY.md, CONTRIBUTING.md, templates, provenance wording *)",
       "Bash(grep -n \"^  [a-z-]*:$\\\\|^name:\\\\|runs-on\" .github/workflows/ci.yml)",
-      "Bash(git -C /Users/joshuadell/Dev/okl push --dry-run origin main)"
+      "Bash(git -C /Users/joshuadell/Dev/okl push --dry-run origin main)",
+      "Bash(git -c core.hooksPath=/dev/null commit -qm 'v0.1.2: ship the provenance fix and the security warning *)",
+      "Bash(rm -rf v12test)",
+      "Bash(python3 -m venv v12test)",
+      "Bash(./v12test/bin/pip install *)",
+      "Bash(./v12test/bin/okl --help)",
+      "Bash(./v12test/bin/python -c ' *)",
+      "Bash(ruff check *)"
     ],
     "additionalDirectories": [
       "/Users/joshuadell/Dev/okl/e2e/scratch-briefed/.okl",

{org_knowledge_layer-0.1.2 → org_knowledge_layer-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: org-knowledge-layer
-Version: 0.1.2
+Version: 0.1.3
 Summary: Org Knowledge Layer — an installable sixth surface that carries encoded engineering lessons across repos.
 Author: Joshua Dell
 License: MIT
@@ -246,6 +246,29 @@ okl init --repo my-repo        # writes .okl/config.json; installs the pre-task
 okl connect https://okl.myorg.dev   # optional: point at the shared service (else local file)
 ```
 
+### What `okl init` writes to your repo
+
+Run `okl init --dry-run` first: it lists every path and writes nothing. In full, `init`
+touches only the current directory, and only these:
+
+| Path | What it is |
+|---|---|
+| `.okl/config.json` | repo name, subject interests, and the path to your `okl` binary |
+| `.claude/hooks/userpromptsubmit-okl-check.sh` | **executable**; runs when you submit a task, injects the briefing |
+| `.claude/hooks/stop-okl-encode.sh` | **executable**; runs at session end, asks what was learned |
+| `.claude/settings.json` | registers those two hooks (merged in place; your existing keys are preserved) |
+| `.mcp.json` | registers the okl MCP server — only when the `mcp` extra is installed |
+| `.github/workflows/okl-verify.yml` | **a CI workflow** running the drift gate on pull requests |
+
+Two of those deserve a second look before you run it: the hooks are shell scripts that
+execute automatically during agent sessions (the check hook can *block* a task when the
+store is unreachable — that is the fail-closed design), and the CI workflow will run in
+your Actions. Both are plain text you can read first, in
+[`src/okl/scaffold/hooks/`](src/okl/scaffold/hooks/) and
+[`src/okl/scaffold/ci/`](src/okl/scaffold/ci/). Nothing executes at install time; nothing
+is written outside the directory you run `init` in; nothing contacts a network unless you
+run `okl connect` and point it somewhere yourself.
+
 `init` writes `.okl/config.json`. If the repo uses a coding agent with a `.claude/`
 directory, it also installs two hooks: a `UserPromptSubmit` hook that runs `check` on
 the prompt you actually typed and puts the briefing into the model's context (the

{org_knowledge_layer-0.1.2 → org_knowledge_layer-0.1.3}/README.md

@@ -214,6 +214,29 @@ okl init --repo my-repo        # writes .okl/config.json; installs the pre-task
 okl connect https://okl.myorg.dev   # optional: point at the shared service (else local file)
 ```
 
+### What `okl init` writes to your repo
+
+Run `okl init --dry-run` first: it lists every path and writes nothing. In full, `init`
+touches only the current directory, and only these:
+
+| Path | What it is |
+|---|---|
+| `.okl/config.json` | repo name, subject interests, and the path to your `okl` binary |
+| `.claude/hooks/userpromptsubmit-okl-check.sh` | **executable**; runs when you submit a task, injects the briefing |
+| `.claude/hooks/stop-okl-encode.sh` | **executable**; runs at session end, asks what was learned |
+| `.claude/settings.json` | registers those two hooks (merged in place; your existing keys are preserved) |
+| `.mcp.json` | registers the okl MCP server — only when the `mcp` extra is installed |
+| `.github/workflows/okl-verify.yml` | **a CI workflow** running the drift gate on pull requests |
+
+Two of those deserve a second look before you run it: the hooks are shell scripts that
+execute automatically during agent sessions (the check hook can *block* a task when the
+store is unreachable — that is the fail-closed design), and the CI workflow will run in
+your Actions. Both are plain text you can read first, in
+[`src/okl/scaffold/hooks/`](src/okl/scaffold/hooks/) and
+[`src/okl/scaffold/ci/`](src/okl/scaffold/ci/). Nothing executes at install time; nothing
+is written outside the directory you run `init` in; nothing contacts a network unless you
+run `okl connect` and point it somewhere yourself.
+
 `init` writes `.okl/config.json`. If the repo uses a coding agent with a `.claude/`
 directory, it also installs two hooks: a `UserPromptSubmit` hook that runs `check` on
 the prompt you actually typed and puts the briefing into the model's context (the

{org_knowledge_layer-0.1.2 → org_knowledge_layer-0.1.3}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 # Distribution name only. The CLI command, the import package, and the repo are all `okl`;
 # PyPI rejects `okl` as too similar to the existing `oki` (l/i are treated as confusable).
 name = "org-knowledge-layer"
-version = "0.1.2"
+version = "0.1.3"
 description = "Org Knowledge Layer — an installable sixth surface that carries encoded engineering lessons across repos."
 readme = "README.md"
 requires-python = ">=3.10"

{org_knowledge_layer-0.1.2 → org_knowledge_layer-0.1.3}/src/okl/cli.py

@@ -54,8 +54,30 @@ def _merge_hook_settings(claude: Path) -> bool:
 
 def cmd_init(args) -> int:
     """Wire the current repo so the loop runs without manual follow-up steps:
-    config, hooks (installed AND registered), CI verifier, MCP registration."""
+    config, hooks (installed AND registered), CI verifier, MCP registration.
+
+    `--dry-run` prints every path it would touch and writes nothing. This command
+    installs executable hooks and a CI workflow into your repo; you should be able
+    to see that list before it happens."""
     import shutil
+    if getattr(args, "dry_run", False):
+        repo = args.repo or Path.cwd().name
+        print(f"DRY RUN — nothing will be written. `okl init --repo {repo}` would:\n")
+        print("  .okl/config.json                        repo name, interests, and the path to this okl")
+        if Path(".claude").exists():
+            print("  .claude/hooks/userpromptsubmit-okl-check.sh   executable; runs when you submit a task")
+            print("  .claude/hooks/stop-okl-encode.sh             executable; runs when a session ends")
+            print("  .claude/settings.json                   registers those two hooks (merged, existing keys kept)")
+            print("  .mcp.json                               registers the okl MCP server (only if okl[mcp] is installed)")
+        else:
+            print("  (no .claude/ directory here, so no hooks would be installed)")
+        if Path(".git").exists():
+            print("  .github/workflows/okl-verify.yml        a CI workflow running the drift gate on PRs")
+        else:
+            print("  (not a git repository, so no CI workflow and no drift gate)")
+        print("\nNothing is written outside this directory. Read the hooks before you register them:")
+        print("  https://github.com/emeraldleaf/okl/blob/main/src/okl/scaffold/hooks/")
+        return 0
     repo = args.repo or Path.cwd().name
     cfg = load_config()
     cfg["repo"] = repo
@@ -385,6 +407,8 @@ def build_parser() -> argparse.ArgumentParser:
     pi.add_argument("--repo"); pi.add_argument("--service")
     pi.add_argument("--interests", help="comma-sep subject tags this repo cares about "
                     "(filters org-scope lessons in `check`; see store.KNOWN_TAGS)")
+    pi.add_argument("--dry-run", dest="dry_run", action="store_true",
+                    help="list every file init would write or modify, and write nothing")
     pi.set_defaults(func=cmd_init)
 
     pc = sub.add_parser("connect", help="point this repo at a shared OKL service URL")

{org_knowledge_layer-0.1.2 → org_knowledge_layer-0.1.3}/tests/test_okl.py

@@ -341,3 +341,25 @@ def test_seed_node_without_repo_stays_unattributed(store, tmp_path, capsys):
     (n,) = store.all_nodes()
     assert n.repo is None, "seed node without repo must not inherit the seeding repo"
     assert "no 'repo'" in capsys.readouterr().err
+
+def test_init_dry_run_writes_nothing(tmp_path, monkeypatch, capsys):
+    """--dry-run must list what init would touch and leave the filesystem alone.
+    Anyone about to let a package install executable hooks and a CI workflow into
+    their repo should be able to see the list first."""
+    import argparse
+
+    from okl.cli import cmd_init
+    monkeypatch.chdir(tmp_path)
+    (tmp_path / ".claude").mkdir()
+    (tmp_path / ".git").mkdir()
+    before = sorted(p.name for p in tmp_path.iterdir())
+    args = argparse.Namespace(repo="demo", service=None, interests=None, dry_run=True)
+    assert cmd_init(args) == 0
+    out = capsys.readouterr().out
+    assert "DRY RUN" in out
+    for expected in ("hooks/userpromptsubmit-okl-check.sh", "settings.json",
+                     ".github/workflows/okl-verify.yml", ".okl/config.json"):
+        assert expected in out, f"dry run must disclose {expected}"
+    assert sorted(p.name for p in tmp_path.iterdir()) == before, "dry run wrote something"
+    assert not (tmp_path / ".okl").exists()
+    assert not (tmp_path / ".github").exists()