Initialize repository governance, handbook, and docs CI workflows

docs/engineering-handbook/11-documentation-standards.md

@@ -1,17 +1,187 @@
 # Documentation Standards
 
-## Purpose
+## Overview
 
-This page is reserved for future NTARI Engineering Handbook guidance on documentation standards.
+Documentation is an engineering deliverable in COSDS. It explains how people
+understand, use, operate, review, and maintain NTARI systems. Documentation must
+be accurate, accessible, version-controlled, and reviewable through the same
+GitHub workflow used for code.
 
-## Placeholder Sections
+These standards apply to handbook chapters, project documentation, repository
+README files, runbooks, RFCs, architecture notes, and contributor guidance.
 
-- Overview
-- Scope
-- Standards
-- Responsibilities
-- References
+## Documentation Principles
 
-## Status
+| Principle | Practice |
+| --- | --- |
+| Write for the next contributor | Assume the reader was not present for prior discussions. |
+| Keep docs close to the work | Place documentation near the repository, feature, or process it describes. |
+| Prefer explicit structure | Use headings, lists, tables, and examples to reduce ambiguity. |
+| Keep links durable | Prefer relative internal links and stable public references. |
+| Document decisions | Capture the reason for important choices, not only the final state. |
+| Review documentation like code | Check accuracy, scope, accessibility, and maintainability. |
 
-Content coming soon.
+## Required Qualities
+
+Good NTARI documentation is:
+
+- **Accurate**: it matches the current repository behavior or clearly describes
+  future work.
+- **Actionable**: it helps the reader complete a task or make a decision.
+- **Accessible**: it uses plain language, descriptive links, and text
+  alternatives for visual material.
+- **Traceable**: it links to related issues, pull requests, RFCs, or chapters.
+- **Maintainable**: it has a clear owner or review path.
+- **License-aware**: copied material, examples, and assets respect AGPL-3.0 and
+  third-party licensing obligations.
+
+## Document Types
+
+| Type | Purpose | Typical location |
+| --- | --- | --- |
+| README | Repository introduction and navigation | Repository root |
+| Handbook chapter | Shared engineering policy or process | `docs/engineering-handbook/` |
+| Project documentation | Project-specific overview and usage | Project repository or project docs area |
+| Runbook | Operational procedure | Operations documentation area |
+| RFC | Proposal for significant change | RFC documentation area or issue form |
+| Decision record | Captures a durable technical decision | Architecture or project docs area |
+
+See [Project Documentation](15-project-documentation.md) for project-level
+expectations.
+
+## Markdown Structure
+
+Use GitHub-flavored Markdown. Prefer predictable structure:
+
+```markdown
+# Page Title
+
+## Overview
+
+A short explanation of what the page covers.
+
+## Requirements
+
+- Requirement one.
+- Requirement two.
+
+## Examples
+
+Concrete examples that contributors can adapt.
+
+## Related Chapters
+
+- Related page link
+```
+
+Rules:
+
+- Use one top-level `#` heading per page.
+- Use sentence-style headings.
+- Keep sections focused.
+- Use fenced code blocks with language identifiers when practical.
+- Use tables for comparisons, ownership, status, or checklists.
+- Avoid unexplained acronyms.
+
+## Examples
+
+Good example:
+
+```markdown
+## Validation
+
+Run the following before requesting review:
+
+- `npm test`
+- `npm run lint`
+- Review rendered Markdown for broken formatting.
+```
+
+Poor example:
+
+```markdown
+## Stuff
+
+Do the normal checks.
+```
+
+The good example is specific, actionable, and reviewable. The poor example
+requires private knowledge.
+
+## Internal Links
+
+Use relative links for repository files:
+
+```markdown
+See [Pull Request Process](08-pull-request-process.md).
+```
+
+Avoid absolute GitHub links for files in the same repository unless the link
+must point to a specific historical revision.
+
+Internal links should be checked before merge. For pull request guidance, see
+[Pull Request Process](08-pull-request-process.md).
+
+## External Links
+
+External links should be:
+
+- Publicly accessible.
+- Stable enough for long-term documentation.
+- Relevant to the surrounding text.
+- Described with meaningful link text.
+
+Avoid linking to private documents, expiring chat threads, or inaccessible
+resources from public documentation.
+
+## Accessibility Standards
+
+Documentation should be usable by contributors with different tools, abilities,
+and network conditions.
+
+Checklist:
+
+- Use descriptive link text.
+- Provide alt text for images.
+- Do not rely on color alone to convey meaning.
+- Provide text summaries for diagrams.
+- Use tables only when tabular structure improves comprehension.
+- Keep sentences direct and avoid unnecessary jargon.
+
+Mermaid diagrams are useful when they clarify flow, but the surrounding text
+must still explain the process.
+
+## Review Checklist
+
+Before merging documentation changes, confirm:
+
+- The page has a clear purpose.
+- The content is accurate for the current repository state.
+- Internal links resolve.
+- Examples are safe to copy.
+- Commands are fenced and include language identifiers where helpful.
+- Accessibility expectations are met.
+- Licensing and attribution are appropriate.
+- Related handbook chapters are linked.
+
+## Maintenance Expectations
+
+Documentation should be updated when:
+
+- A workflow changes.
+- A command changes.
+- A repository structure changes.
+- A policy changes.
+- Review comments show repeated confusion.
+- A contributor needs private explanation to complete a public task.
+
+Documentation debt should be captured as issues rather than left in untracked
+notes.
+
+## Related Chapters
+
+- [Purpose](01-purpose.md)
+- [Communication Standards](04-communication-standards.md)
+- [Pull Request Process](08-pull-request-process.md)
+- [Code Review Standards](09-code-review-standards.md)
+- [Repository Standards](10-repository-standards.md)

docs/engineering-handbook/12-ci-cd-standards.md

@@ -1,17 +1,158 @@
 # CI/CD Standards
 
-## Purpose
+## Overview
 
-This page is reserved for future NTARI Engineering Handbook guidance on ci/cd standards.
+Continuous integration and continuous delivery help NTARI repositories stay
+reviewable, reproducible, and safe. In COSDS, automation should support
+contributors without hiding important decisions from maintainers.
 
-## Placeholder Sections
+CI/CD standards apply to GitHub Actions workflows, status checks, build scripts,
+test commands, release automation, and deployment gates.
 
-- Overview
-- Scope
-- Standards
-- Responsibilities
-- References
+## Goals
 
-## Status
+CI/CD should:
 
-Content coming soon.
+- Catch errors before merge.
+- Provide fast feedback to contributors.
+- Use least-privilege permissions.
+- Make failures actionable.
+- Avoid leaking secrets or private data.
+- Support AGPL-3.0 source availability and reproducible release practices.
+
+## Workflow Design Principles
+
+| Principle | Practice |
+| --- | --- |
+| Keep checks relevant | Run workflows only for paths that can affect them. |
+| Fail clearly | Error output should tell contributors what to fix. |
+| Minimize permissions | Use read-only permissions unless write access is required. |
+| Prefer reproducibility | Pin runtime versions and document build commands. |
+| Separate concerns | Keep lint, test, security, and release workflows distinct. |
+| Avoid surprise deployment | Deploy only from protected branches or approved release workflows. |
+
+## Recommended Workflow Categories
+
+| Workflow | Purpose | Example trigger |
+| --- | --- | --- |
+| Markdown lint | Enforce documentation style | Pull requests changing `*.md` |
+| Link check | Detect broken documentation links | Pull requests and scheduled runs |
+| Spellcheck | Catch spelling and terminology errors | Pull requests changing docs |
+| Unit tests | Validate code behavior | Pull requests changing source files |
+| Security scan | Detect dependency or configuration risk | Pull requests and scheduled runs |
+| Release | Build and publish artifacts | Tags or maintainer-approved dispatch |
+
+## GitHub Actions Standards
+
+GitHub Actions workflows should:
+
+- Declare explicit `permissions`.
+- Use descriptive workflow and job names.
+- Use maintained actions from trusted sources.
+- Avoid secrets in pull request workflows from forks unless explicitly safe.
+- Use path filters when appropriate.
+- Keep deployment separate from validation.
+
+Example read-only workflow header:
+
+```yaml
+name: Markdown Lint
+
+on:
+  pull_request:
+    paths:
+      - "**/*.md"
+
+permissions:
+  contents: read
+```
+
+## Secrets and Sensitive Data
+
+CI must never print secrets, tokens, private keys, or sensitive repository
+configuration.
+
+Checklist:
+
+- Store secrets only in approved GitHub secret stores or external secret
+  management systems.
+- Do not echo secrets in logs.
+- Do not run untrusted pull request code with privileged credentials.
+- Redact sensitive values from debug output.
+- Rotate credentials if accidental exposure is suspected.
+
+Report concerns through [`../../SECURITY.md`](../../SECURITY.md).
+
+## Status Checks
+
+Maintainers should require checks that match repository risk.
+
+For documentation repositories:
+
+- Markdown lint.
+- Broken link check.
+- Spellcheck.
+
+For software repositories:
+
+- Formatting or linting.
+- Unit tests.
+- Integration tests when practical.
+- Dependency or vulnerability scanning.
+- Build verification.
+
+Required checks should be stable. If a check is flaky, fix or tune it before
+making it a hard merge requirement.
+
+## CI Failure Triage
+
+```mermaid
+flowchart TD
+  A[CI failure] --> B{Failure reproducible?}
+  B -- Yes --> C[Fix code, docs, or config]
+  B -- No --> D[Check external service or flaky test]
+  D --> E{Flake confirmed?}
+  E -- Yes --> F[Open issue and tune workflow]
+  E -- No --> C
+  C --> G[Push update]
+  G --> H[Checks pass]
+```
+
+When CI fails, contributors should include the failing check name and relevant
+log excerpt in the pull request discussion if help is needed.
+
+## Release and Deployment Controls
+
+Release and deployment automation should be conservative.
+
+Minimum expectations:
+
+- Deploy only from protected branches, signed tags, or maintainer-approved
+  manual workflows.
+- Document release commands and rollback steps.
+- Separate validation from production deployment.
+- Require maintainer review for workflow changes that affect credentials or
+  publishing.
+
+See [Release Management](19-release-management.md) when that chapter is
+available.
+
+## Review Checklist
+
+Before merging CI/CD changes, confirm:
+
+- Workflow YAML is valid.
+- Permissions are least-privilege.
+- Triggers are appropriate.
+- Secrets are not exposed to untrusted code.
+- Failure messages are actionable.
+- The workflow does not introduce Docusaurus or other tooling unless approved.
+- Documentation explains new commands or checks.
+
+## Related Chapters
+
+- [GitHub Workflow](05-github-workflow.md)
+- [Pull Request Process](08-pull-request-process.md)
+- [Code Review Standards](09-code-review-standards.md)
+- [Repository Standards](10-repository-standards.md)
+- [Security Standards](13-security-standards.md)