This commit is contained in:
DevRunbook release export
@@ -0,0 +1,178 @@
|
||||
# 09 — Repository intelligence
|
||||
|
||||
## Purpose
|
||||
|
||||
Repository intelligence converts repository evidence into a reusable, human-reviewable profile. It does not attempt to understand every line of code or claim certainty beyond observed evidence.
|
||||
|
||||
## Profile sections
|
||||
|
||||
### Identity
|
||||
|
||||
- display name;
|
||||
- source and external reference;
|
||||
- default branch;
|
||||
- repository type: single app, monorepo, infrastructure, library, mixed;
|
||||
- archived/read-only status.
|
||||
|
||||
### Stack
|
||||
|
||||
- languages with evidence paths;
|
||||
- frameworks;
|
||||
- package managers;
|
||||
- runtimes;
|
||||
- test frameworks;
|
||||
- databases and queues;
|
||||
- container/deployment technologies;
|
||||
- CI/CD system.
|
||||
|
||||
### Command registry
|
||||
|
||||
Logical roles:
|
||||
|
||||
- install;
|
||||
- format;
|
||||
- format-check;
|
||||
- lint;
|
||||
- typecheck;
|
||||
- unit-test;
|
||||
- integration-test;
|
||||
- end-to-end-test;
|
||||
- build;
|
||||
- dev-start;
|
||||
- smoke-test;
|
||||
- migration-status;
|
||||
- migration-apply;
|
||||
- security-scan;
|
||||
- dependency-audit.
|
||||
|
||||
Each command stores value, working directory, platform, source, confidence and whether it is safe for direct future execution. MVP uses commands only as prompt text.
|
||||
|
||||
### Structure
|
||||
|
||||
- application roots;
|
||||
- package roots;
|
||||
- service roots;
|
||||
- documentation paths;
|
||||
- test paths;
|
||||
- generated paths;
|
||||
- data/runtime paths;
|
||||
- protected paths;
|
||||
- ignored paths.
|
||||
|
||||
### Policies
|
||||
|
||||
- backwards compatibility;
|
||||
- new dependency policy;
|
||||
- migration policy;
|
||||
- commit/push policy;
|
||||
- required documentation;
|
||||
- required validation roles;
|
||||
- branch conventions;
|
||||
- environment constraints.
|
||||
|
||||
### Source evidence
|
||||
|
||||
Every inferred fact references one or more evidence records:
|
||||
|
||||
- file path and digest;
|
||||
- forge API field;
|
||||
- manual user entry;
|
||||
- prior profile revision;
|
||||
- observation timestamp.
|
||||
|
||||
## Detection strategy
|
||||
|
||||
Use deterministic detectors, not an LLM, for MVP profile import.
|
||||
|
||||
Examples:
|
||||
|
||||
- `package.json`, lockfiles and workspace files;
|
||||
- `.csproj`, `.sln`, `global.json`;
|
||||
- `pyproject.toml`, `requirements*.txt`, `poetry.lock`;
|
||||
- `go.mod`, `Cargo.toml`, `pom.xml`, Gradle files;
|
||||
- Dockerfile and Compose files;
|
||||
- common CI workflow directories;
|
||||
- test configuration files;
|
||||
- root and nested `AGENTS.md` files;
|
||||
- README command snippets only as untrusted suggestions requiring confirmation.
|
||||
|
||||
Detectors return evidence, confidence and possible conflicts. They do not overwrite manual policy silently.
|
||||
|
||||
## Manual profile workflow
|
||||
|
||||
1. Name repository.
|
||||
2. Select repository type.
|
||||
3. Add stack technologies.
|
||||
4. Add command roles.
|
||||
5. Define paths and scope rules.
|
||||
6. Define policies.
|
||||
7. Review validation and save revision.
|
||||
|
||||
The user can create a useful profile without exposing a repository.
|
||||
|
||||
## Source versus override model
|
||||
|
||||
A normalized field can contain:
|
||||
|
||||
```json
|
||||
{
|
||||
"value": "pnpm test",
|
||||
"source": "manual_override",
|
||||
"observedValue": "npm test",
|
||||
"evidence": ["package.json#scripts.test"],
|
||||
"confirmedAt": "..."
|
||||
}
|
||||
```
|
||||
|
||||
This avoids losing observed evidence while respecting operator knowledge.
|
||||
|
||||
## Findings model
|
||||
|
||||
Repository findings are rule-based, evidence-linked observations such as:
|
||||
|
||||
- no repository-level `AGENTS.md` found;
|
||||
- test command not identified;
|
||||
- no protected default branch evidence;
|
||||
- no release history;
|
||||
- README setup command conflicts with package manager lockfile;
|
||||
- Dockerfile appears to run as root;
|
||||
- generated or runtime directory appears tracked;
|
||||
- no issue or pull-request template found;
|
||||
- multiple package managers detected;
|
||||
- CI workflow does not run the profile's required build command.
|
||||
|
||||
Each finding includes confidence and limitations. “No evidence found” is not the same as “feature definitely absent” when permissions or API capabilities are incomplete.
|
||||
|
||||
## Recommendation rules
|
||||
|
||||
A finding maps to a playbook slug and optional prefilled inputs. Example:
|
||||
|
||||
```text
|
||||
Finding: No AGENTS.md found
|
||||
Recommendation: codex-agents-instructions
|
||||
Prefill: repository commands, protected paths and contribution policy
|
||||
```
|
||||
|
||||
Recommendations must explain why they appear and can be dismissed.
|
||||
|
||||
## Snapshot refresh
|
||||
|
||||
A refresh creates new evidence and findings. It does not automatically replace a manually edited profile revision. The UI presents a reviewable diff:
|
||||
|
||||
- new observation;
|
||||
- removed observation;
|
||||
- changed value;
|
||||
- conflict with manual override;
|
||||
- unchanged evidence.
|
||||
|
||||
User can accept all safe changes, accept individually or retain the existing profile.
|
||||
|
||||
## Privacy controls
|
||||
|
||||
- allowlist inspected file names and paths;
|
||||
- configurable maximum file size;
|
||||
- never import `.env`, secret stores, private keys or common credential files;
|
||||
- redact token-like strings in text snippets;
|
||||
- show exactly which files were read;
|
||||
- allow repository snapshots to omit raw snippets and retain only normalized facts;
|
||||
- support deleting snapshots independently from manual profiles.
|
||||
Reference in New Issue
Block a user