Skip to content

5e6fd577: stale docs/CI leftovers, CLI aliases, legacy view routes; Trello importer decision prepared - #334

Merged
alexeygrigorev merged 4 commits into
mainfrom
fix/stale-docs-cleanup
Nov 4, 2026
Merged

alexeygrigorev merged 4 commits into
mainfrom
fix/stale-docs-cleanup

Conversation

@alexeygrigorev

Copy link
Copy Markdown
Member

Task 5e6fd577 — cleanup inventory + safe removals of unambiguously dead items. Worktree fix/stale-docs-cleanup (base origin/main @ f2da8e6). Per the task, nothing here is merged, and the Trello importer decision is prepared but NOT made.

Inventory

Removed (unambiguously dead, with zero-usage evidence)

# Area Item Evidence
1 CI deploy-dataops-v1.yml path filters content/**, scripts/deploy/** (push+PR) content/ removed in 1b6e9b2 (corpus moved to dataops-knowledge); scripts/deploy/ removed in 63afe3b. ls both missing; no test/validator references them.
2 CI validate-dataops-content.yml path filter content/** (push+PR) same content/ removal; filter can never match.
3 CI validate-planning-docs.yml path filter content/tasks/templates/** (push+PR) content/ gone. The validator-required filters (_docs/**, templates/**, docs/**) are kept — scripts/validate_planning_docs.py REQUIRED_WORKFLOW_PATHS enforces them.
4 Makefile dead search-index entry in .PHONY no search-index: target exists; no doc/test references make search-index.
5 CLI offers set alias of offers update (cli/src/commands/offers.mjs) absent from family help text, cli/skill/SKILL.md, cli/README.md; grep "offers set" over repo + bots-management skills: zero hits; no test calls it.
6 CLI crm touches alias of crm touch (cli/src/commands/crm.mjs) help documents only crm touch; grep "crm touches": zero hits (tests only hit the API path /api/sponsor-crm/touches).
7 Portal Account-menu "CLI sessions" link to /device/sessions (frontend/index.html) the /device approval page, cli-sessions.js, device.html, device.css, surfaces/operations/device.js were deleted in 4f50bb2 (API tokens + device grants retired). No backend route, no workspace route (parseWorkspaceLocation → "unknown path" → falls back to docs library). Only reference was this link.
8 Docs README.md: content/ layout bullet; mermaid "GitHub repo: content/ markdown"; "single workspace is backend/"; nonexistent npm run export:templates:backend content/ missing; root package.json workspaces = backend+cli; no export:templates:backend script anywhere.
9 Docs backend/README.md: "backend/ as the single Node package"; Build + Project Structure describing src/public/ and src/pages/; whole "Agent and invoice reader service credential" (dops_svc_) section backend/src/public and backend/src/pages missing; build script packages frontend/ via copy-frontend-artifact; dops_svc_/InvoiceReaderTokenSha256 removed in 4f50bb2 (zero grep hits in backend/src, infra, workflows).
10 Docs docs/README.md: "content/ - transitional operational documentation" section, archive/ bullet, "reads operational docs from content/ ... until private knowledge-repo sync is implemented" docs/archive/ missing; the knowledge-repo sync shipped (deploy workflow DOCS_GITHUB_REPO: dataops-knowledge).
11 Docs docs/local-development.md: search-index example --content-dir ../content ../content missing; aligned with the neighbouring --content-root ../dataops-knowledge/content example.

Kept for decision (used by prod data / ambiguous)

# Area Item Evidence / why kept
A Trello importer backend/scripts/import-trello-csv.ts (2.1k lines) + 3 test files (trello-import-{templates,assignee,loom}.test.ts) DECISION NEEDED: keep / delete. Usage evidence: not wired to any npm script, Makefile target, workflow or doc; referenced only by its own 3 test files, which run in CI (npm test glob tests/*.test.ts). Its bundled data (backend/data/qVB6fAUG - datatalksclub.json, TODO list - todo/done.csv) is absent from the repo and was never committed (git log -- backend/data empty), so without external --source* files the script cannot run. backend/docs/data.md (its analysis) IS still referenced by .goal-v1.md, JTBD docs and enforced by validate_planning_docs.py. Delete = remove script + 3 test files; the original Trello migration is long done and re-import data is gone.
B Portal routes None found dead: every WORKSPACE_ROUTE_DEFINITIONS path is linked (sidebar index.html, sponsor-routes.js CRM nav, planning-newsletter.js issue links) and covered by frontend/test/routing.test.mjs. Minor dead defensive branches kept for decision: surface-composition.js showWorkspaceSurface legacy "search"/"processes" view names and dataset.workspaceTarget have zero producers (grep). Tiny; safe to remove later.
C Docs docs/STRUCTURE.md, docs/sop-format.md (content/-era corpus conventions) describe the private knowledge corpus conventions that still apply to .knowledge/content (frontmatter/IDs); a rewrite to point at the knowledge repo is a content decision, not a removal.
D Docs backend/docs/ historical specs (specs.md, data.md, templates.md, parts) actively enforced: validate_planning_docs.py requires JTBD docs to reference them; .goal-v1.md lists them.
E CI validate-dataops-content.yml trigger inconsistency: push includes docs/**, pull_request does not behavior change (more PR triggers) — not a removal; flagged for a follow-up.
F Tooling backend/package.json validate:docs-links default --content-root content default points at the removed dir; CI always overrides with --content-root .knowledge/content. Changing the default is a small fix but affects bare local runs — left for decision.
G Repo root DONE-*.md session evidence files (9 files, Nov 2-4) deliberate recent practice (HEAD commit f2da8e6 adds one); not stale.

Checks run

  • uv run --with pytest python -m pytest tests/planning_docs tests/infra — 62 passed (covers Makefile-help contract, workflow trigger/execution contracts, planning docs links).
  • npm run test:cli (workspaces dataops-cli) — same result as pristine origin/main in this environment: 4 pre-existing Windows-env failures (tokens.test.mjs, headless scoped agent tokens, managed-engine sessions, invoice PDF), verified identical with git stash on clean main. Targeted node --test test/offers.test.mjs test/crm.test.mjs test/cli.test.mjs: 53/53 pass.
  • node --test frontend/test/{routing,frontend-architecture,dakit-tokens,app-coordinator}.test.mjs — identical to pristine main (2 pre-existing failures in CSS/readability contracts on files not touched here); the routing and nav-structure contracts over index.html pass with the menu-link removal.

Files changed

.github/workflows/deploy-dataops-v1.yml, .github/workflows/validate-dataops-content.yml, .github/workflows/validate-planning-docs.yml, Makefile, README.md, backend/README.md, cli/src/commands/crm.mjs, cli/src/commands/offers.mjs, docs/README.md, docs/local-development.md, frontend/index.html (11 files, +23/-63).

Commits: 0c954ee9 (CI), 770a98d5 (CLI aliases), 2b458328 (portal link), ab4a1058 (docs).

…aths (5e6fd577)

content/, _docs/, templates/ and scripts/deploy/ no longer exist in the
repo (the process corpus moved to DataTalksClub/dataops-knowledge in
1b6e9b2, _docs/scripts-deploy in 990e046/63afe3b4), so their workflow
path filters can never match. The guarded entries in
validate-planning-docs.yml required by scripts/validate_planning_docs.py
REQUIRED_WORKFLOW_PATHS (_docs/**, templates/**, docs/**) stay; only the
unguarded leftovers (content/**, content/tasks/templates/**,
scripts/deploy/**) are removed. Also drop the dead 'search-index' entry
from the Makefile .PHONY line: no such target exists.

Evidence: ls of content/ _docs/ templates/ scripts/deploy/ all missing;
git log shows the removing commits; tests/planning_docs + tests/infra
pass (62 passed) after the change.
'dataops offers set' was an alias of 'offers update' and 'dataops crm
touches' an alias of 'crm touch'; neither name appears in any help text,
cli/skill/SKILL.md, cli/README.md, tests or other docs, and the repo
rules forbid undocumented compatibility aliases.

Evidence: grep for 'offers set' and 'crm touches' across the repo and
bots-management skills returns nothing; cli --help texts document only
update/touch. cli tests offers/crm/cli (53 tests) pass after removal.
The account menu still linked 'CLI sessions' to /device/sessions, but
the /device approval page, its frontend surface and the CLI-session
token list were deleted in 4f50bb2 (API tokens and device grants
retired; cli-sessions.js, device.html, device.css,
surfaces/operations/device.js all removed). The path has no backend
route and no workspace route: the SPA parses it as an unknown path and
falls back to the docs library.

Evidence: grep for device/sessions and CLI sessions across backend/src,
frontend/src, frontend/test and backend/e2e returns no handler and no
test; the only reference was this index.html link.
README.md: remove the content/ layout bullet (corpus moved to the
private dataops-knowledge repo), point the architecture diagram at the
knowledge repo, correct 'single workspace' to backend/ + cli/, and drop
the nonexistent 'npm run export:templates:backend' root script.

backend/README.md: correct 'backend/ as the single Node package' to the
two workspaces, rewrite the Build and Project Structure sections that
still described src/public/ and src/pages/ (deleted; the artifact now
packages the canonical frontend/ app), and replace the 'dops_svc_'
invoice-reader credential section (removed in 4f50bb2) with the
shared-issuer credential model.

docs/README.md: remove the 'content/ - transitional operational
documentation' section and the archive/ bullet (both gone), and drop
the stale 'reads operational docs from content/ until private
knowledge-repo sync is implemented' claim - that sync shipped.

docs/local-development.md: the search-index example pointed at
--content-dir ../content, which no longer exists; use the knowledge
checkout like the neighbouring docs-links example.

Evidence: ls shows content/, backend/src/public, backend/src/pages and
docs/archive missing; root package.json has no export:templates:backend;
grep finds no dops_svc_/InvoiceReaderTokenSha256 references in
backend/src, infra or the deploy workflow. tests/planning_docs passes
(62 passed) after the edits.
@alexeygrigorev
alexeygrigorev merged commit a7781d6 into main Nov 4, 2026
6 checks passed
alexeygrigorev added a commit that referenced this pull request Nov 4, 2026
…e (already implemented), pin the retired offers set alias (#341)

Handoff 0f847429 asked for ONE structured, CLI/API-queryable rate card
record. Verification on origin/main (982bb8e) and live prod shows the gap
was already closed by d2e96f9 (2026-10-31, pushed directly to main) and the
prod record seeded the same day (version 1, 15 offers / 6 non-offers /
9 inbound-routing rules); PR #334 removed the undocumented 'offers set'
alias. No product code changes were needed.

What this adds:
- DONE-0f847429.md: the re-verification evidence (inventory with file
  references, seed provenance, live read-only prod checks, test results,
  remaining gaps).
- cli/test/offers.test.mjs: negative pin that 'dataops offers set' stays
  inert — unknown subcommand, usage exit, no portal call (house style per
  the 2026-08-13 test suite review and PR #335), so the #334 cleanup cannot
  silently regress.

Tests: cli/test/offers.test.mjs 6/6, backend/tests/offers.test.ts 2/2,
backend typecheck clean on this tree.
@alexeygrigorev
alexeygrigorev deleted the fix/stale-docs-cleanup branch November 5, 2026 15:51
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