Skip to content

OKF-11 - #12

Merged
eltmon merged 40 commits into
mainfrom
feature/okf-11
Nov 15, 2026
Merged

eltmon merged 40 commits into
mainfrom
feature/okf-11

Conversation

@eltmon

@eltmon eltmon commented Nov 15, 2026

Copy link
Copy Markdown
Owner

Issue: #11

Acceptance Criteria

  • Add a pytest harness that CI runs after the selftest
  • Add the escaped stdlib Markdown renderer for published pages
  • Add the redaction profile loader, built-in rules, redact and scan
  • Add the publish model: bundle walk, visibility, trust tier, link classes and the fixture bundle
  • Render concept pages and index pages with page-relative links
  • Add the client-side search index, search page and script
  • Add publish.py --out with redaction, output-directory safety and clean rebuilds
  • Add the publish.py --check redaction gate
  • Add the /okf publish command row, SKILL.md section and selftest loop entry
  • Document publishing in README, references/publish.md and docs/USAGE.md

eltmon and others added 30 commits November 15, 2026 10:21
Plan-Finalized: 53f1486f30f003fa1e8d5962f18e5c55c0ec595408ef820b612b659b7ae906bd
Overdeck-Agent: agent-okf-11
tests/conftest.py puts the repo scripts/ directory on sys.path and
provides the scripts_dir and fixture_bundle fixtures. CI now installs
pytest and runs `python -m pytest -q tests` after scripts/selftest.sh.

Item: pytest-harness
Item: pytest-harness.ac1
Item: pytest-harness.ac2
Item: pytest-harness.ac3

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Overdeck-Agent: agent-okf-11
Overdeck-Agent: agent-okf-11
Overdeck-Agent: agent-okf-11
render_markdown renders the supported Markdown subset (headings with
slug ids, paragraphs, fenced code, blockquotes, nested lists, thematic
breaks, pipe tables, footnotes, inline code, links, images as alt text,
autolinks, emphasis) with every text run HTML-escaped. Raw HTML stays
escaped text, and every emitted href is re-checked so only relative,
http, https and mailto hrefs survive. Underscore emphasis needs
non-word boundaries so identifiers like x_visibility_default stay
intact.

Item: markdown-renderer
Item: markdown-renderer.ac1
Item: markdown-renderer.ac2
Item: markdown-renderer.ac3

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Overdeck-Agent: agent-okf-11
The renderer commit's tests cover headings, nested lists, blockquote,
fenced python and pipe table (ac4) and the full test file (ac5).

Item: markdown-renderer.ac4
Item: markdown-renderer.ac5

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Overdeck-Agent: agent-okf-11
Overdeck-Agent: agent-okf-11
Overdeck-Agent: agent-okf-11
…nd scan

publish_redact.py defines the eight built-in rules, loads and strictly
validates okf-publish.yaml (version, unknown keys, disabled ids, rule
ids, duplicate ids, regex compile errors, private strings), applies
rules in order with literal replacements, and scans text for rule ids
and line numbers without returning matched text.
templates/okf-publish.yaml is the starter profile; a test keeps its
listed built-in ids equal to DEFAULT_RULES.

Item: redaction-rules
Item: redaction-rules.ac1
Item: redaction-rules.ac2
Item: redaction-rules.ac3
Item: redaction-rules.ac4
Item: redaction-rules.ac5

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Overdeck-Agent: agent-okf-11
Overdeck-Agent: agent-okf-11
Overdeck-Agent: agent-okf-11
publish_model.py walks bundle Markdown (skipping dot-components,
node_modules and the --out directory), resolves visibility from
x_visibility and the schema.md x_visibility_default (private when
absent; invalid values are P_VISIBILITY_INVALID), derives the trust
tier from verified entries, normalises tags and sources, classifies
link targets, and computes public directories and public-only
backlinks. Unparseable frontmatter is P_FRONTMATTER_PARSE.

The model also records index_offsets (frontmatter lines stripped from
each index.md) so --check can report true file line numbers for the
root index.

tests/fixtures/publish_bundle is the shared fixture: three public
concepts, two private ones holding home paths, an IP and a private
string, a log.md, a profile, and a dot-directory file.

Item: publish-model
Item: publish-model.ac1
Item: publish-model.ac2
Item: publish-model.ac3
Item: publish-model.ac4
Item: publish-model.ac5

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Overdeck-Agent: agent-okf-11
Overdeck-Agent: agent-okf-11
Overdeck-Agent: agent-okf-11
publish_render.py writes one page per public concept (ID, title, type,
status and trust badges, tags, description, body, sources, public-only
backlinks) and one index page per published directory, inside a fixed
page shell that uses only page-relative hrefs. Index listing lines for
private concepts and unpublished directories are dropped; a directory
without index.md gets a generated listing. Links to private, missing
or non-Markdown targets render as their text.

Two details beyond the PRD text: the OKF index marker comments are
removed before rendering so they do not show as escaped text, and
filtering is built on kept_index_lines so --check can map filtered
index text back to file line numbers.

Item: site-pages
Item: site-pages.ac1
Item: site-pages.ac2
Item: site-pages.ac3
Item: site-pages.ac4
Item: site-pages.ac5

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Overdeck-Agent: agent-okf-11
Overdeck-Agent: agent-okf-11
Overdeck-Agent: agent-okf-11
publish_search.py writes search-index.json (one record per public
concept, link targets and footnote markers stripped from the text),
search.html with the single search.js script tag, and copies
publish_assets/search.js. The script reads q, fetches the JSON index,
requires every term, scores title/description/text matches, and
builds results with createElement, textContent and setAttribute only.

scripts/publish_render.py is also touched: its private _write helper
is renamed write_file because publish_search.py now shares it.

Browser check (ac4): served the published fixture with python3 -m
http.server and loaded search.html?q=spoilers in headless Chrome with
an isolated profile. The results list showed "No spoilers" and "Old
spoiler rule" (2 result(s)) and the DOM held no ZZ-PRIVATE text.

Item: search-index
Item: search-index.ac1
Item: search-index.ac2
Item: search-index.ac3
Item: search-index.ac4
Item: search-index.ac5

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Overdeck-Agent: agent-okf-11
Overdeck-Agent: agent-okf-11
Overdeck-Agent: agent-okf-11
…uilds

publish.py loads the profile, builds the model (excluding --out when it
lies inside the bundle), refuses rule matches in public concept IDs or
published directory paths (P_ID_REDACTION), and refuses an unsafe
--out (P_OUT_UNSAFE: the bundle or an ancestor, a file, or a non-empty
directory without the .okf-publish marker). With no findings it
clears a marked --out, writes the marker, redacts every published
string and filtered index text, and renders pages, search and assets.
Any finding exits 2 before anything is written.

The --out/--check group is in place; --check itself is filled in by
the publish-check-mode item and stops with an argparse error until
then.

Item: publish-command
Item: publish-command.ac1
Item: publish-command.ac2
Item: publish-command.ac3
Item: publish-command.ac4
Item: publish-command.ac5

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Overdeck-Agent: agent-okf-11
Overdeck-Agent: agent-okf-11
Overdeck-Agent: agent-okf-11
--check scans the published text of public concepts (title,
description, type, status, tags, source fields and body) and of
published index pages. Each matching rule is one P_REDACTION finding
naming the rule id and the file line (body and index) or field name
(frontmatter); the matched text is never printed. It exits 2 on any
finding, 0 otherwise, and writes nothing.

Index line numbers map through the kept listing lines and the stripped
frontmatter offset, so they match the index.md file even when private
listing lines are dropped or the root index carries frontmatter.

Item: publish-check-mode
Item: publish-check-mode.ac1
Item: publish-check-mode.ac2
Item: publish-check-mode.ac3
Item: publish-check-mode.ac4

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Overdeck-Agent: agent-okf-11
Overdeck-Agent: agent-okf-11
Overdeck-Agent: agent-okf-11
…test entry

SKILL.md and README.md command tables gain the same /okf publish row
(the selftest drift check compares them), SKILL.md gains the
/okf publish section, and the selftest command loop now requires it.

Item: skill-command-row
Item: skill-command-row.ac1
Item: skill-command-row.ac2

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Overdeck-Agent: agent-okf-11
Overdeck-Agent: agent-okf-11
Overdeck-Agent: agent-okf-11
eltmon and others added 8 commits November 15, 2026 15:17
…nd USAGE

README gains a "Publishing a bundle" section: what the site is,
visibility (x_visibility, x_visibility_default, private by default,
private links render as text), the okf-publish.yaml redaction profile
and built-in rule ids, --check as the CI gate, a sample Cloudflare
Pages workflow, and notes for GitHub Pages and local preview.
references/publish.md is the full reference: synopsis, visibility,
link and trust-tier rules, profile schema and built-in rules (with the
ipv4 false-positive note), output layout, --out safety and rebuilds,
all seven P_* finding codes with exit codes, and what is never
published. docs/USAGE.md gains the /okf publish section.

Item: publishing-docs
Item: publishing-docs.ac1
Item: publishing-docs.ac2
Item: publishing-docs.ac3
Item: publishing-docs.ac4

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Overdeck-Agent: agent-okf-11
Overdeck-Agent: agent-okf-11
search_records wrote the raw concept page path as the record url, and
search.js puts it straight into href. A concept file named c#.md gave a
dead search link, and a root file named javascript:x.md gave a
javascript: href, which NFR-4 forbids. Record urls now go through
relative_href from search.html, which quotes each path segment. For the
fixture the urls are unchanged. This deviates from the literal PRD
section 4.7 text (url = concept_page_path(id)) to keep NFR-4.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Overdeck-Agent: agent-okf-11
A private string such as "Alice Example" wrapped as "Alice\nExample"
in a body slipped past both --check and --out redaction, because the
rule was re.escape(s). The browser then showed it as "Alice Example",
and search_text collapsed the whitespace, so the name also landed
verbatim in search-index.json. Each private string now compiles to its
escaped words joined by \s+, case-insensitive, so any whitespace run
between words matches. A whitespace-only private string is now an
error, like an empty one. README and references/publish.md say so.

This goes beyond the literal PRD text ("literal strings, matched
case-insensitively") to close a leak of exactly what the profile is
meant to hide.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Overdeck-Agent: agent-okf-11
The diff is only the plan lifecycle fields (status, sequence, updated)
that Overdeck wrote when the work session started.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Overdeck-Agent: agent-okf-11
Overdeck-Agent: agent-okf-11
Overdeck-Agent: agent-okf-11
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Overdeck-Agent: agent-okf-11
@eltmon

eltmon commented Nov 15, 2026

Copy link
Copy Markdown
Owner Author

review verdict: blocked

Private concept titles/descriptions leak onto public index pages: kept_index_lines misses reindex lines with ']' in titles, spaces in filenames, or multi-line descriptions (FR-3); --check passes

@eltmon

eltmon commented Nov 15, 2026

Copy link
Copy Markdown
Owner Author

Review CHANGES REQUESTED for OKF-11

Review — OKF-11

Verdict: CHANGES REQUESTED — private concept titles and descriptions leak onto public index pages (FR-3)

Context

  • Run ID: agent-okf-11-review-2aa74173
  • Manifest: /home/eltmon/Projects/okf/workspaces/feature-okf-11/.pan/review/agent-okf-11-review-2aa74173/context.json
  • Branch / workspace: feature/okf-11 / /home/eltmon/Projects/okf/workspaces/feature-okf-11
  • PR: OKF-11 #12
  • HEAD reviewed: 2aa7417
  • Base / prior cycle SHA: origin/main 92a21fe (PR base); no prior review cycle. The local main ref in this worktree points at an unrelated history (fe73d46), so every diff here is against origin/main.

Blocking Findings

[security/requirements] Index filtering misses listing lines that reindex.py generates, so private titles and descriptions get published — scripts/publish_render.py:59

  • Severity: ! (MUST)

  • Classification / requirement scope: in_pr_scope (new kept_index_lines). It breaks FR-3 ("A private concept appears nowhere on the site … Its index listing line is dropped"). It also contradicts the shipped docs: references/publish.md says "What is never published: Private concepts, and their titles in index listings", and the README says "A private concept has no page, no index line". Triggers 1 and 3 are an implementation defect: the filter's link detection is narrower than what reindex produces and the renderer prints. Trigger 2 is a specification defect. PRD §4.6 says "Drop the line when that link is a concept that is not public … Keep every other line unchanged." The code follows that, so a multi-line description's continuation line survives. Spec correction: inside the OKF:INDEX markers, drop a dropped item's continuation lines, and keep only lines that positively resolve to a public concept or a published directory. All three triggers still block, because FR-3 fails either way.

  • Trigger and changed-code connection: kept_index_lines decides whether to drop a listing line by running okf_common.LINK_PATTERN.search(line). That regex is \[[^\]]+\]\(([^)\s]+)…\). When it finds no match, the line is kept unchanged. Then render_markdown renders the line with its own bracket-depth parser (_find_closing_bracket / _parse_destination), which does recognise the link. The resolver returns None for the private target, so the link text and the rest of the line render as plain text. scripts/reindex.py (unchanged, lines 28-35) writes listing lines as * [{title}]({file}){ - description} using the raw title and raw description. So the standard /okf sync → reindex flow produces lines that hit this gap in two ways:

    1. The title contains ] (for example Layoffs [draft], Outage [2026-11-01], or an unbalanced a] b). LINK_PATTERN cannot match [Layoffs [draft]](secret-plan.md), so the line is kept. The page shows Layoffs [draft] - <description>.
    2. The description has several lines (YAML description: |). reindex writes the second line of the description as its own line, which does not start with * . Only the first line is classified and dropped. The continuation line is kept and renders as a paragraph on the public page.
    3. The filename contains a space (rules/my file.md). reindex writes * [Space file](my file.md) - …. LINK_PATTERN's target class [^)\s]+ does not match it. The renderer's _parse_destination does not match it either, so the whole line, filename included, renders as literal text.
  • Expected / observed / impact: expected: the private concept is absent from rules/index.html. Observed: its title and description appear in the public HTML. --check exits 0, because no redaction rule matches. So nothing warns the author, and the private text ships on a public site. Preventing exactly this is the purpose of the feature.

  • Evidence: runtime reproduction against the fixture copy under the session scratchpad (probe4). I added two private concepts, rules/secret-plan.md (title: Layoffs [draft], description: ZZ-LEAK-DESC …) and rules/hr.md (description: | with a second line ZZ-LEAK-SECOND-LINE about Bob). Then I ran the real scripts/reindex.py --bundle b, publish.py --bundle b --check and publish.py --bundle b --out out:

    reindex=0
    ok - publish check passed: 3 public concept(s), no redaction rule matches
    ok - published 3 public concept(s) to out (4 private excluded, 0 redaction(s) applied)
    $ grep -o "ZZ-LEAK[^<]*\|Layoffs[^<]*" out/rules/index.html
    ZZ-LEAK-SECOND-LINE about Bob
    Layoffs [draft] - ZZ-LEAK-DESC fire the night crew
    

    Probe 5 (scratchpad probe5) adds rules/my file.md (private, description: ZZ-LEAK-SPACE) and rules/unbal.md (private, title: "a] ZZ-LEAK-UNBAL"). It also runs reindex, --check (exit 0) and --out:

    [Space file](my file.md) - ZZ-LEAK-SPACE
    [a] ZZ-LEAK-UNBAL](unbal.md) - ZZ-LEAK-UNBAL-DESC
    

    validate.py does not restrict titles, descriptions or filenames, so all these inputs are valid OKF.

  • Fix (must fail closed). Probe 5 shows that switching to the renderer's own parser is not enough: _parse_destination also fails on the space and unbalanced-bracket lines, so they would still be kept as literal text. Pick one of these:

    • (a) Inside the <!-- OKF:INDEX:BEGIN -->…END block, keep a line only when it positively resolves to a public concept or a published directory. Drop every other line in the block, continuation lines included.
    • (b) Ignore the marker block's contents and regenerate it from the model, reusing generated_listing. Keep the hand-written prose outside the markers.

    Outside the markers, the current behaviour (link text stays) is documented and acceptable. Add regression tests for a bracketed title, an unbalanced ] title, a filename with a space and a multi-line description, all on private concepts. Each test asserts that no private title, description or filename reaches any output file.

Non-blocking Findings

[security] search_text leaves private link targets in search-index.json when the link text contains brackets — scripts/publish_search.py:15

  • Severity: ~ (SHOULD)
  • Classification: implementation defect, in_pr_scope. It has the same root cause as the blocker: a regex link matcher that disagrees with the renderer.
  • Trigger: a public body contains [notes [v2]](team-notes.md), where team-notes is private. LINK = \[([^\]]+)\]\([^)]*\) does not match, so the raw [notes [v2]](team-notes.md) text, target included, lands in the record's text field. Probe1 output: "text":"Proposed in chat. See [notes [v2]](team-notes.md). …". Only the private concept's ID/path leaks, not its content, and only when the author writes nested brackets. FR-3 and §4.7 ("Link targets never reach the index") still say it should not happen.
  • Fix: strip links with the same renderer-parser helper suggested above. Add a test with a nested-bracket link to a private concept.

[security] Redaction runs on raw Markdown, so Markdown syntax can split a match the reader still sees — scripts/publish.py:88

  • Severity: ~ (SHOULD; behaviour confirmed, but it needs unusual source text)
  • Classification: specification defect. The PRD's FR-8 design ("Every rule applies to all published text before rendering") is followed as written.
  • The redaction rules match the source text before rendering. Probe 5 appended Esc: /home\/alice and 10.0.0\.12 and **Alice** Example to a public concept. --check exited 0 and the redaction count was 0. The page rendered Esc: /home/alice and 10.0.0.12 and <strong>Alice</strong> Example, which a reader sees as the home path, the IP and the private name. Backslash escapes are unlikely by accident, but a bold name is plausible. A later spec revision could also scan (and redact) the rendered plain text.

[performance] Backlinks and published-directory sets are recomputed per page, which makes publish time quadratic — scripts/publish_model.py:87, scripts/publish_render.py:43

  • Severity: ~ (SHOULD; a CLI that runs once per publish, not server code)
  • For each page, backlinks() re-sorts public_ids() and runs classify_link over every link of every public concept. make_resolver/kept_index_lines also rebuild public_dirs() each time. Measured end to end on a synthetic bundle with 1,501 public concepts and 10 links each (Python 3.12, this machine): real 0m29.9s. Attributing that time to these functions is a static inference; I did not profile it. A bundle of a few hundred concepts takes a few seconds. To make it linear, compute a reverse-link map and public_dirs once per model, for example with functools.cached_property or a precomputed dict in build_model/render_site.

[docs] The private-strings behaviour goes beyond the PRD wording

  • Commit a4de29d changed private_strings from re.escape(s) to whitespace-run matching (\s+ between words). This is stricter, which suits redaction, and README/references document it. The template comment still says "matched literally and case-insensitively". That is acceptable, but it could mention the line-break tolerance. No action is required.

Coverage

Changed-file ledger (37 files, diff vs origin/main 92a21fe)

File Status
.github/workflows/ci.yml Reviewed: adds pytest install and a python -m pytest -q tests step after the selftest (matches WI-1).
scripts/publish.py Reviewed: flow, finding ordering, --out safety, marker rebuild, redaction copies, check-mode line math.
scripts/publish_model.py Reviewed: walk, visibility fail-closed, trust tier, classify_link rules 1-10, body_start_line, index frontmatter offsets.
scripts/publish_redact.py Reviewed: profile validation, rule order, literal replacement, scan never returns matched text.
scripts/publish_markdown.py Reviewed: escaping (all text runs and attributes escaped, \x00 stripped before placeholder use), safe_href, fences, lists, tables, footnotes, autolinks. No XSS path found.
scripts/publish_render.py Reviewed: blocker in kept_index_lines; page shell, relative hrefs, generated listings, backlinks are otherwise correct.
scripts/publish_search.py Reviewed: advisory on search_text.
scripts/publish_assets/search.js Reviewed: uses only textContent/setAttribute/createElement; no innerHTML, eval or external URL; scoring matches §4.7.
scripts/publish_assets/style.css Grep-checked only: no @import, url( or http. It has a system font stack, max-width: 48rem and a prefers-color-scheme: dark block. I did not read individual rules.
scripts/selftest.sh Reviewed: only the command loop gains publish (NFR-3).
templates/okf-publish.yaml Reviewed: id list matches DEFAULT_RULES; loads cleanly (covered by the test).
README.md, SKILL.md, docs/USAGE.md, references/publish.md Reviewed: command rows identical in both tables; sections present; the "never published … titles in index listings" claim is currently false (blocker).
tests/conftest.py, tests/test_harness.py Read in full.
tests/test_publish_*.py (6) Partly read. I checked that every function name the PRD lists is present, plus extras (75 tests pass in CI). I read the bodies of test_no_unresolved_links, test_no_private_or_secret_bytes, test_out_safety and test_check_index_line_after_frontmatter_and_dropped_lines; they assert what the PRD requires. For the other tests I rely on the CI pass. No test covers bracketed or unbalanced titles, filenames with spaces, multi-line descriptions or nested-bracket links.
tests/fixtures/publish_bundle/** (11 files) Read in full (except rules/index.md, read through the probe copy). They match the PRD fixture table.
.pan/drafts/OKF-11.md, .pan/specs/…xbrief.json, .pan/continues/OKF-11.xbrief.json Not applicable for code review: planning artifacts. I read the PRD for requirements.

NFR-3 check: git diff origin/main...HEAD --stat touches no existing script except scripts/selftest.sh; okf_common.py, validate.py, reindex.py and the template scripts are unchanged.

Dimensions

  • Correctness: one blocker (index filtering), one advisory (search text). Visibility resolution, link classification, line numbers, --out safety and determinism are correct as traced.
  • Security: the renderer's HTML escaping and href scheme checks hold. The private-content leak is the blocker. The redaction pre-render gap is a hypothesis.
  • Performance: quadratic backlinks (advisory, measured).
  • Requirements/UX: see the matrix below.

Acceptance criteria

AC Status Evidence
AC-1 pytest in CI Met ci.yml step; CI log 75 passed in 2.58s (run 43757998023).
AC-2 Markdown renderer Met test_publish_markdown passes in CI; escaping traced manually.
AC-3 redaction rules Met test_publish_redact passes; scan returns ids and lines only.
AC-4 publish model Met test_publish_model passes.
AC-5 site pages: "private listing lines are dropped" Unmet for reindex-generated lines with bracketed titles or multi-line descriptions (blocker). Met for the fixture's simple lines.
AC-6 search Met for the unit tests (search.js has no innerHTML). Browser UAT is the test role's job, not verified here. Advisory on nested-bracket targets.
AC-7 --out Met per the CI tests. test_no_private_or_secret_bytes passes only because the fixture has no bracketed titles.
AC-8 --check gate Met (test passes in CI).
AC-9 selftest Met: CI log ok - SKILL.md documents /okf publish.
AC-10 docs Met: ## Publishing a bundle at README:102. It contains x_visibility, okf-publish.yaml, cloudflare/wrangler-action@v3 and publish.py --bundle . --check. references/publish.md lists all seven P_* codes.

Verification

  • gh pr checks 12: both selftest jobs pass on HEAD 2aa7417. The CI job runs bash scripts/selftest.sh and python -m pytest -q tests (75 passed). I reused this run and did not re-run the full suite.
  • Probe 1 (scratchpad probe1): hand-added bracketed private listing line plus nested-bracket body link. Private title and description appear in out/rules/index.html, and the private target appears in search-index.json.
  • Probe 4 (scratchpad probe4): the same leak using the real reindex.py output for a bracketed title and a multi-line description. --check exits 0 and --out publishes the private text.
  • Probe 5 (scratchpad probe5): a filename with a space and an unbalanced ] title, both private, leak through reindex → publish. The escape and emphasis split defeats redaction and --check.
  • Probe 2: the templates/repo bundle passes --check (0 public concepts), so its README.md/CONTRIBUTING.md frontmatter causes no parse errors.
  • Probe 3: synthetic 1,501-concept bundle, publish took 29.9 s.
  • npm run lint:effect-diagnostics: not applicable (Python/stdlib repo with no TypeScript or Effect).
  • All probes ran in the session scratchpad. No tracked files were edited.

Scope Note

  • The manifest's acceptanceCriteria list was empty. I used PRD §3 (FR/NFR) and §7 (AC-1 to AC-10) from .pan/drafts/OKF-11.md as the acceptance criteria.
  • The local main ref in this worktree does not match the PR base (origin/main 92a21fe). The PR diff itself is correct.

Source: /home/eltmon/Projects/okf/workspaces/feature-okf-11/.pan/review/agent-okf-11-review-2aa74173/review.md

Required action

Fix every blocking review finding, commit the fixes, then re-request review with:

pan review request OKF-11 -m "Fixed review issues"

eltmon and others added 2 commits November 15, 2026 15:37
Blocking review finding: kept_index_lines classified listing lines with
okf_common.LINK_PATTERN, which cannot parse reindex.py output for a
title containing "]", a file name with a space, or a multi-line
description's continuation line. Those lines were kept, so private
titles and descriptions reached public index pages while --check
passed.

- Inside the OKF:INDEX marker block, a line now survives only when it
  is a listing line whose first link positively resolves to a public
  concept or a published directory (review option a). Private entries,
  continuation lines and unparseable lines are dropped. Outside the
  block, hand-written listing lines to unpublished targets are dropped
  as before, and other prose is kept.
- Link detection uses new publish_markdown.find_links, built on the
  renderer's own bracket and destination parsers, so the filter and the
  renderer agree on what is a link.

Advisory findings:
- search_text strips links with the same parser (strip_links), so a
  nested-bracket link no longer leaves a private target in
  search-index.json.
- --check also scans each body and index line as the reader sees it
  (visible_text: links as text, backslash escapes and emphasis markers
  removed), so "**Alice** Example" or "/home\/alice" fail the gate.
- PublishModel caches public_ids, public_dirs and a reverse-link map,
  so publishing is linear: a 1,501-concept bundle with 10 links each
  now publishes in 0.82 s (reviewer measured 29.9 s).
- The template's private-strings comment mentions line breaks.

Regression tests run real reindex.py output with a bracketed title, an
unbalanced "]" title, a file name with a space and a multi-line
description on private concepts, and assert none of their text reaches
any output file; a public bracketed title stays listed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Overdeck-Agent: agent-okf-11
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Overdeck-Agent: agent-okf-11
@eltmon

eltmon commented Nov 15, 2026

Copy link
Copy Markdown
Owner Author

review verdict: passed

Prior leak blocker fixed: index block fails closed, search strips nested links, --check scans visible text, backlinks linear; probes clean, CI 82 passed

@eltmon
eltmon merged commit d97b469 into main Nov 15, 2026
2 checks passed
@eltmon
eltmon deleted the feature/okf-11 branch November 15, 2026 21:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant