ci: expand CodeQL coverage and tighten repo guardrails

.clusterfuzzlite/build.sh

@@ -6,8 +6,8 @@ cd "$SRC/newsdom-api"
 uv sync --frozen --extra fuzz
 export PATH="$SRC/newsdom-api/.venv/bin:$PATH"
 
-for fuzzer in $(find fuzzers -name '*_fuzzer.py'); do
-	fuzzer_basename=$(basename -s .py "$fuzzer")
+while IFS= read -r -d '' fuzzer; do
+	fuzzer_basename=$(basename "$fuzzer" .py)
 	fuzzer_package="${fuzzer_basename}.pkg"
 
 	pyinstaller --distpath "$OUT" --onefile --name "$fuzzer_package" "$fuzzer"
@@ -18,4 +18,4 @@ this_dir=\$(dirname "\$0")
 exec "\$this_dir/$fuzzer_package" "\$@"
 EOF
 	chmod +x "$OUT/$fuzzer_basename"
-done
+done < <(find fuzzers -type f -name '*_fuzzer.py' -print0)

.github/CODEOWNERS

@@ -0,0 +1,6 @@
+* @Seongho-Bae
+
+# Security and workflow ownership
+.github/ @Seongho-Bae
+docs/ @Seongho-Bae
+manual/ @Seongho-Bae

.github/workflows/clusterfuzzlite.yml

@@ -22,6 +22,7 @@ jobs:
           language: python
           sanitizer: address
           github-token: ${{ github.token }}
+          bad-build-check: false
 
       - name: Run fuzzers
         uses: google/clusterfuzzlite/actions/run_fuzzers@52ecc61cb587ee99c26825a112a21abf19c7448c

.github/workflows/codeql.yml

@@ -13,7 +13,7 @@ permissions:
 
 jobs:
   analyze:
-    name: codeql (python)
+    name: codeql (python, actions)
     runs-on: ubuntu-latest
     permissions:
       contents: read
@@ -27,7 +27,7 @@ jobs:
       - name: Initialize CodeQL
         uses: github/codeql-action/init@c10b8064de6f491fea524254123dbe5e09572f13
         with:
-          languages: python
+          languages: python, actions
 
       - name: Autobuild
         uses: github/codeql-action/autobuild@c10b8064de6f491fea524254123dbe5e09572f13

.github/workflows/gh-pages.yml

@@ -4,7 +4,6 @@ on:
   push:
     branches:
       - main
-      - master
       - develop
     paths:
       - 'manual/**'

.gitignore

@@ -9,5 +9,8 @@ build/
 *.pyc
 private/
 tmp/
+site/
+registered_agents.json
+task_agent_mapping.json
 content_file_3982.pdf
 page1_300dpi-1.png

.markdownlint-cli2.jsonc

@@ -0,0 +1,10 @@
+{
+  "ignores": [
+    "docs/plans/2026-04-08-git-flow-design.md",
+    "docs/plans/2026-04-08-git-flow.md",
+    "docs/plans/2026-04-08-newsdom-design.md",
+    "docs/plans/2026-04-08-newsdom-implementation.md",
+    "docs/plans/2026-04-08-quality-gate-design.md",
+    "docs/plans/2026-04-08-quality-gate.md"
+  ]
+}

AGENTS.md

@@ -0,0 +1,57 @@
+# AGENTS.md
+
+## Project overview
+
+- Repository: `newsdom-api`
+- Product: FastAPI service that converts MinerU OCR output into
+  canonical NewsDOM JSON.
+- Primary branch model: manual Git Flow (`develop` integration,
+  `main` stable).
+
+## Authoritative docs
+
+Read these first when making repository changes:
+
+- `docs/engineering/canonical-docs.md`
+- `docs/engineering/execution-policy.md`
+- `docs/engineering/acceptance-criteria.md`
+- `docs/engineering/harness-engineering.md`
+- `docs/engineering/review-policy.md`
+- `docs/engineering/runtime-data-policy.md`
+- `docs/engineering/skills-subagents-mcp.md`
+- `docs/workflow/git-flow.md`
+- `docs/workflow/pr-continuity.md`
+- `docs/workflow/one-day-delivery-plan.md`
+- `docs/operations/deploy-runbook.md`
+- `docs/security/api-security-checklist.md`
+- `docs/coderabbit/review-commands.md`
+- `ARCHITECTURE.md`
+
+## Setup and verification defaults
+
+- Install: `uv sync --frozen --all-extras`
+- Test: `uv run pytest`
+- Coverage gate:
+  `uv run pytest --cov=src/newsdom_api --cov-branch --cov-report=term-missing --cov-fail-under=100`
+- Docs build: `uv run mkdocs build --strict`
+- Local API: `uv run uvicorn --app-dir src newsdom_api.main:app --reload`
+
+## Delivery defaults
+
+- Branch normal work from `develop` unless the task is a `main`-only
+  release or hotfix path.
+- Keep PR continuity explicit with `gh pr view` / `gh pr list` /
+  `pr_continuity` before opening duplicates.
+- Treat CodeRabbit as advisory automation; required human approvals
+  still follow the repository ruleset.
+- When PRs are blocked externally, continue local adjacent tasks
+  instead of stopping.
+
+## Safety rules
+
+- Keep synthetic fixtures public and private reference inputs
+  local-only.
+- Do not commit secrets, credentials, or copyrighted source
+  newspaper material.
+- Prefer durable evidence in tracked docs, tests, workflow runs,
+  PR comments, and release assets over scratch notes.

ARCHITECTURE.md

@@ -0,0 +1,49 @@
+# Architecture
+
+## Runtime shape
+
+`newsdom-api` is a small service-oriented Python application with a
+thin FastAPI entrypoint and explicit separation between request
+orchestration, MinerU process execution, and DOM normalization.
+
+## Primary modules
+
+- `src/newsdom_api/main.py` exposes `/health` and `/parse`
+  through FastAPI.
+- `src/newsdom_api/service.py` orchestrates PDF parsing,
+  temporary files, and response construction.
+- `src/newsdom_api/mineru_runner.py` shells out to the MinerU CLI,
+  collects JSON outputs, and surfaces process errors.
+- `src/newsdom_api/dom_builder.py` converts MinerU `content_list`
+  blocks into the canonical NewsDOM response model.
+- `src/newsdom_api/schemas.py` defines the public response schema.
+- `src/newsdom_api/synthetic.py` and
+  `src/newsdom_api/equivalence.py` support synthetic fixture
+  generation and structural comparisons.
+
+## Request flow
+
+1. `src/newsdom_api/main.py` receives an uploaded PDF.
+2. `src/newsdom_api/service.py` writes the upload to a temporary
+   workspace and calls MinerU.
+3. `src/newsdom_api/mineru_runner.py` resolves the executable, runs
+   the OCR pipeline, and loads generated JSON artifacts.
+4. `src/newsdom_api/dom_builder.py` normalizes OCR blocks into the canonical response.
+5. FastAPI returns typed JSON from `src/newsdom_api/schemas.py`.
+
+## Supporting systems
+
+- `tests/fixtures` holds synthetic PDFs, JSON baselines, and
+  provenance notes; private reference inputs stay out of git.
+- `manual/` is the published user manual rendered by MkDocs.
+- `.github/workflows/` encodes CI, security scanning, Pages,
+  release, and image-delivery policy.
+- `scripts/release/` builds release manifests and exports GitHub attestation bundles.
+
+## Delivery boundaries
+
+- `develop` is the integration line for normal feature, fix,
+  and chore work.
+- `main` is the stable release line that receives tagged releases.
+- The service is production-grade only when code, docs, workflows,
+  and release evidence agree.

CONTRIBUTING.md

@@ -2,46 +2,76 @@
 
 ## Development setup
 
+Install `uv` first if it is not already available in your `PATH`, then sync the
+repository-managed virtual environment:
+
 ```bash
-python3.10 -m venv .venv
-source .venv/bin/activate
-pip install -e ".[dev]"
+uv sync --frozen --all-extras
 ```
 
 Install the parser stack only when you need live MinerU execution:
 
 ```bash
-pip install "mineru[pipeline]==3.0.9"
+uv pip install --python .venv/bin/python "mineru[pipeline]==3.0.9"
 ```
 
+On Windows, replace `.venv/bin/python` with `.venv\Scripts\python.exe`.
+
 ## Test commands
 
 ```bash
-pytest
-PYTHONWARNINGS=error pytest
-pytest --cov=src/newsdom_api --cov-branch --cov-report=term-missing --cov-fail-under=100
+uv run pytest
+PYTHONWARNINGS=error uv run pytest
+uv run pytest --cov=src/newsdom_api --cov-branch --cov-report=term-missing --cov-fail-under=100
 ```
 
-CI installs dependencies from `uv.lock`, and workflow actions are pinned by immutable commit SHA. Keep both policies intact when editing `.github/` automation.
+CI installs dependencies from `uv.lock`, and workflow actions are
+pinned by immutable commit SHA. Keep both policies intact when editing
+`.github/` automation.
 
-CircleCI parity is defined in `.circleci/config.yml` and mirrors the same uv-locked warnings-as-errors and 100% coverage quality gate.
+CircleCI parity is defined in `.circleci/config.yml` and mirrors the
+same uv-locked warnings-as-errors and 100% coverage quality gate.
 
 ## Documentation build
 
-The GitHub Pages workflow installs documentation tooling from `uv.lock` via the optional `docs` extra. For local maintainer work, sync all extras so the docs build does not drop the test toolchain from the active environment.
+The GitHub Pages workflow installs documentation tooling from
+`uv.lock` via the optional `docs` extra. For local maintainer work,
+sync all extras so the docs build does not drop the test toolchain
+from the active environment.
+
+The supported docs toolchain stays on the MkDocs 1.x line for now.
+Keep `mkdocs<2.0` and `mkdocs-material<9.7` in place until the
+upstream Material team publishes a workable migration path or this
+repository validates a replacement docs stack. `uv.lock` is the source
+of truth for the currently supported docs build.
 
 ```bash
 uv sync --frozen --all-extras
 uv run mkdocs build --strict
 ```
 
-Tagged releases use `.github/workflows/release.yml` to build artifacts, generate SHA256 checksums, emit a JSON manifest, export `*.intoto.jsonl` provenance bundles, and publish a GitHub Release with provenance attestation.
+Use markdownlint for `AGENTS.md`, `ARCHITECTURE.md`, `CONTRIBUTING.md`,
+and `docs/**/*.md`. The sweep excludes only the legacy
+`git-flow-design`, `git-flow`, `newsdom-design`,
+`newsdom-implementation`, `quality-gate-design`, and `quality-gate`
+planning notes that predate the current markdown style policy.
+
+Tagged releases use `.github/workflows/release.yml` to build
+artifacts, generate SHA256 checksums, emit a JSON manifest, export
+`*.intoto.jsonl` provenance bundles, and publish a GitHub Release with
+provenance attestation.
 
-For full OpenSSF Scorecard branch-protection visibility against classic GitHub branch protection rules, set a repository secret named `SCORECARD_TOKEN` with the fine-grained administration-read scope recommended by the Scorecard Action documentation. Without that secret, Scorecard still runs but may report the Branch-Protection check as inconclusive.
+For full OpenSSF Scorecard branch-protection visibility against
+classic GitHub branch protection rules, set a repository secret named
+`SCORECARD_TOKEN` with the fine-grained administration-read scope
+recommended by the Scorecard Action documentation. Without that
+secret, Scorecard still runs but may report the Branch-Protection
+check as inconclusive.
 
 ## Fixture policy
 
-This project intentionally separates public test artifacts from private validation material.
+This project intentionally separates public test artifacts from
+private validation material.
 
 Allowed in the repository:
 
@@ -57,7 +87,8 @@ Not allowed in the repository:
 
 ## Private baseline refresh
 
-If you maintain a private reference page locally, refresh only the derived structural baseline:
+If you maintain a private reference page locally, refresh only the
+derived structural baseline:
 
 ```bash
 python tools/derive_private_baseline.py tests/fixtures/private_page_baseline.json
@@ -67,10 +98,24 @@ The source page must remain local.
 
 ## Documentation split
 
+- `AGENTS.md`: repository-local execution bootstrap for autonomous
+  maintenance
+- `ARCHITECTURE.md`: runtime structure and module boundaries
 - `README.md`: user-facing overview and quickstart
 - `CONTRIBUTING.md`: maintainer workflow and safety rules
 - `SECURITY.md`: vulnerability reporting and supported-branch policy
+- `manual/`: published end-user manual rendered by MkDocs
+- `docs/agents/README.md`: agent-specific read order and
+  repository-local behavior notes
+- `docs/coderabbit/review-commands.md`: supported CodeRabbit review
+  commands used in PRs
+- `docs/engineering/`: canonical maintainer policies and acceptance criteria
+- `docs/operations/`: delivery and verification runbooks
+- `docs/security/api-security-checklist.md`: API hardening checklist
+  for FastAPI surface changes
 - `docs/workflow/git-flow.md`: canonical branch workflow
+- `docs/workflow/pr-continuity.md`: canonical PR-selection and
+  stacked-PR guidance
 - `tests/fixtures/README.md`: fixture provenance and regeneration notes
 - `docs/plans/`: design and implementation planning notes