docs(dev): extract infrahub-collect knowledge (ADRs, knowledge, guidelines)

[fatih-acar]

Summary

Extracts durable engineering knowledge from the completed 003-collect-tool spec into a new dev/ documentation system, and archives the spec. Produced by /speckit.opsmill.extract.

Stacked on fac/collect-tool-implem-opip6 (PR #140). This PR's diff is only the extraction; it can merge once #140 lands (and may need a rebase/retarget onto main afterward, like the implementation branch did).

What's here

Bootstraps dev/ (this repo had no dev/ docs system) with a Go/ops-CLI-adapted layout: dev/adr/, dev/knowledge/, dev/guidelines/, and a dev/README.md index.

7 ADRs capturing the load-bearing decisions and the alternatives rejected:

1. Shell out to docker/kubectl instead of client libraries
2. Non-fatal, timeout-bounded collector framework
3. Collection is strictly read-only (never mutates the workload lifecycle)
4. Key-name secret masking through a single choke-point
5. Single .tar.gz bundle + manifest, uniform across Docker/Kubernetes
6. --include-backup reuses CreateBackup non-interactively (force=true) as a standalone artifact
7. Offline by default; image pulls / benchmark strictly opt-in with graceful degradation

Knowledge — dev/knowledge/infrahub-collect.md: how the tool works today (CLI surface, bundle layout, manifest schema, the collectBackend seam, and the "services log to stderr → combined pipe" gotcha).

Guidelines — dev/guidelines/collectors.md: prescriptive conventions for future collectors (bound every subprocess; failures non-fatal; distinguish absent-vs-failed; route sensitive dumps through the masking choke-point; stay read-only; add bounded variants of shared backend helpers rather than mutating them; non-interactive paths must not gate on unbounded waits).

Archive — specs/003-collect-tool/ → specs/archive/003-collect-tool/ (history preserved via git mv), spec marked Status: Extracted, with an EXTRACTED.md record.

Notes

• No source code changes; docs and spec relocation only.
• rumdl markdown lint passes on all new files.
• ADR 0006 records the force=true decision that fixed the Enterprise-edition --include-backup CI failure.

🤖 Generated with Claude Code

---

Summary by cubic

Extracts durable engineering knowledge for infrahub-collect into a new dev/ docs system (ADRs, knowledge, guidelines) and archives the 003-collect-tool spec. Improves clarity and future maintenance with no code changes.

• Documentation
  • Bootstraps dev/ docs (adr/, knowledge/, guidelines/) with an index.
  • Adds 7 ADRs (CLI shell-out, non-fatal timeouts, read-only scope, masking choke-point, uniform bundle+manifest, --include-backup reuse, offline-by-default benchmark).
  • Adds knowledge/infrahub-collect.md (CLI, bundle layout, manifest, backend seam, gotchas) and guidelines/collectors.md (timeouts, non-fatal errors, masking, read-only, bounded helpers, testing).
  • Archives specs/003-collect-tool/ to specs/archive/003-collect-tool/ with an extraction record; no source code changes.

^{Written for commit 64cfae2. Summary will update on new commits.}

[cloudflare-workers-and-pages]

Deploying infrahub-ops-cli with    Cloudflare Pages

Latest commit:	64cfae2
Status:	✅  Deploy successful!
Preview URL:	https://d27af8b0.infrahub-ops-cli.pages.dev
Branch Preview URL:	https://fac-collect-tool-extract.infrahub-ops-cli.pages.dev

View logs

[cubic-dev-ai]

1 issue found across 23 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="specs/archive/003-collect-tool/EXTRACTED.md">

<violation number="1" location="specs/archive/003-collect-tool/EXTRACTED.md:1">
P3: This is a pure docs/archive change (no product code), which per branch policy belongs on stable, not develop. The PR description acknowledges the potential need to retarget to main, so this is likely already tracked — confirming it's intentional before merge avoids a retarget delay later.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P3: This is a pure docs/archive change (no product code), which per branch policy belongs on stable, not develop. The PR description acknowledges the potential need to retarget to main, so this is likely already tracked — confirming it's intentional before merge avoids a retarget delay later.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At specs/archive/003-collect-tool/EXTRACTED.md, line 1:

<comment>This is a pure docs/archive change (no product code), which per branch policy belongs on stable, not develop. The PR description acknowledges the potential need to retarget to main, so this is likely already tracked — confirming it's intentional before merge avoids a retarget delay later.</comment>

<file context>
@@ -0,0 +1,26 @@
+# Extraction Record
+
+**Extracted on**: 2026-07-09
</file context>