mirror of
https://github.com/morluto/rea.git
synced 2026-11-08 07:46:28 +00:00
a67525cdf1
* docs: organize canonical documentation layout (URGENTE) Group all existing authored guides by domain and ownership, expose complete navigation, and preserve their public routes. Update physical path consumers and release configuration while retaining historical records. Document domain-based specs and ADR slugs without global numbering. Co-Authored-By: Codex <noreply@openai.com> * fix(docs): honor home layout in all-page route verification * style: format reviewed source changes * fix(docs): preserve routes and navigation cache inputs * fix: repair the static-check failures on the default branch (#2895) * fix: repair the static-check failures on the default branch The default branch fails its own required `Static checks` job three ways, so every pull request reports that job as failed regardless of its own change. - `npm run format:check` reports `src/domain/functionComparison.test.ts` and `src/ida/IdaOperationRunner.ts`. - `npm run lint` reports a duplicate `import { join } from "node:path"` in `tests/boundary/mcp/ghidraInventoryMcp.test.ts` (lines 4 and 17). - `npm run typecheck` reports `format: "devin"` missing from the client format union in `src/application/SupportedClients.ts`, and an unchecked index in `tests/boundary/cli/clientProfileLifecycle.test.ts`, whose pair array is inferred as `string[][]`. Apply the pinned formatter, drop the duplicate import, list the `"devin"` format that its own definition already uses, and mark the pair array `as const`. Validation: `npm run check:fast` and `npm run format:check` pass. * fix(setup): keep Devin on the JSON configuration dialect --------- Co-authored-by: 吴佳浩 <wujiahao@supremind.com> Co-authored-by: morluto <76467478+morluto@users.noreply.github.com> * fix(docs): update links after guide relocation * docs: correct verified documentation route counts * fix(docs): update browser capture guide link after move (#2820) Refresh gettext protected-link comments alongside the authored href. Co-authored-by: Codex <noreply@openai.com> * fix(docs): include http3 lab in stable routes * fix(docs): preserve historical release evidence and links * fix(ghidra): restore Windows verifier identity import * docs(wakaru): preserve pinned upstream policy link * docs(index): retain recently added guide links * docs(mcp): preserve parent retention clarification * fix(cli): preserve standalone import guidance * fix(test): preserve translated guide link drift coverage --------- Co-authored-by: Matheus Breguêz <matbrgz@gmail.com> Co-authored-by: Codex <noreply@openai.com> Co-authored-by: morluto <17176810+morluto@users.noreply.github.com> Co-authored-by: 吴佳浩Alben <35291372+XiaoBinGan@users.noreply.github.com> Co-authored-by: 吴佳浩 <wujiahao@supremind.com>
83 lines
4.8 KiB
Markdown
83 lines
4.8 KiB
Markdown
# Documentation ownership and authoring
|
|
|
|
Use the [documentation directory](../README.md) to find existing material before
|
|
adding another guide. Preserve one canonical owner for each contract or workflow;
|
|
link to that owner instead of copying its claims into several guides.
|
|
|
|
## Choose a destination
|
|
|
|
| Document | Destination |
|
|
| -------------------------------------------------------- | -------------------------------------- |
|
|
| Installation, client setup and first CLI/MCP steps | `docs/getting-started/` |
|
|
| Analyst workflows and evidence interpretation | `docs/guides/<domain>/` |
|
|
| Analysis-engine configuration and format prerequisites | `docs/providers/` |
|
|
| Shared runtime contracts and evidence semantics | `docs/reference/` |
|
|
| Development, testing, release and authoring instructions | `docs/development/` |
|
|
| Composition diagrams | `docs/architecture/` |
|
|
| Compatibility changes for a released version | `docs/migrations/` |
|
|
| One feature specification, plan and tasks | `docs/specs/<domain>/<feature-slug>/` |
|
|
| One architectural decision | `docs/adr/<domain>/<decision-slug>.md` |
|
|
|
|
Use meaningful, lowercase domain and feature slugs. Global numeric prefixes are
|
|
unnecessary: different domains can add features independently, and branches do
|
|
not compete for the next sequence number. Check the existing domain directory
|
|
and linked issues before creating a feature with the same slug.
|
|
|
|
Guides describe existing behavior and limitations. Specs define one proposed
|
|
feature or domain change; an existing guide does not become a specification by
|
|
moving it into `specs/`.
|
|
|
|
## Feature lifecycle
|
|
|
|
Create the specification before implementation. Each feature directory contains:
|
|
|
|
- `spec.md`: problem, desired behavior, requirements, acceptance and non-goals.
|
|
- `plan.md`: the single implementation plan, contracts and architectural choices.
|
|
- `tasks.md`: incremental, testable steps linked to requirements and verification.
|
|
|
|
Split independent domains or separately reviewable features before writing their
|
|
specs. A broad `ROADMAP.md`, when useful, only lists child specifications, order
|
|
and dependencies; requirements and implementation tasks belong to each child.
|
|
Cross-repository contracts have one producer-owned specification. Consumers link
|
|
to that contract instead of maintaining competing copies.
|
|
|
|
Record an isolated architectural decision separately in
|
|
`docs/adr/<domain>/<decision-slug>.md`, with **Status**, **Context**,
|
|
**Decision** and **Consequences**. Link the ADR from affected specifications.
|
|
Do not create decision records for routine file moves or invent past decisions.
|
|
|
|
Specs do not replace the contribution-scope decision required for a new provider
|
|
or expanded execution authority. Follow
|
|
[contribution scope](https://github.com/morluto/rea/blob/main/CONTRIBUTING.md#contribution-scope).
|
|
|
|
## Links and public routes
|
|
|
|
Use relative links to physical Markdown files so GitHub readers can follow them.
|
|
Link repository files outside `docs/` with their full GitHub URLs. Preserve
|
|
existing heading anchors when moving a guide.
|
|
|
|
[`documentation.ts`](https://github.com/morluto/rea/blob/main/docs/.vitepress/documentation.ts)
|
|
owns categorized site navigation and the existing guides' stable public routes.
|
|
Update it when adding or moving a guide. VitePress rewrites categorized sources
|
|
to the existing public paths; its Markdown hook resolves repository links from
|
|
the physical source and renders them against those public routes. Keep basenames
|
|
and route assignments unique. Edit links use the physical source file.
|
|
|
|
For a move, search for both the basename and its old full path. Update README
|
|
translations, authored skills, verification instructions, documentation-fact
|
|
readers and release configuration when they consume that path. Preserve
|
|
historical release records and references bound to earlier commits or tags.
|
|
|
|
## Generated ownership and checks
|
|
|
|
The [documentation directory](../README.md#machine-owned-documentation) identifies
|
|
the machine-owned outputs and their producers. Their existing paths are retained
|
|
because scripts, package consumers and release history depend on them. Change
|
|
canonical sources and regenerate; do not fix a generated projection by hand.
|
|
|
|
Run `npm run docs:check` for documentation facts and generated consistency, and
|
|
`npm run verify:docs:routes` to build the complete production site and check local
|
|
links, anchors and physical edit targets.
|
|
When a physical path moves, also run the tests that read it. Follow
|
|
[development checks](testing.md#developer-commands) before requesting review.
|