Skip to content

Commit a5c0c97

Browse files
committed
docs: apply validation corrections across consolidated proposals
Multi-pass review of the consolidated docs (per-file validation against the code plus cross-repo consistency checks). Highlights: - P-010: spec/Diagnostics.md is derived; ownlang/diagnostics.py TITLES is the source of truth for OWN codes — inverted claim fixed - P-026: add the missing local-immutability dimension so the illustrative report's 4/6 coverage matches the dimensions table - P-027: drop 'existing' for P-021's planned async_methods module; repoint a wrong P-021 open-question citation; attribute the plain-structs lowering rule to P-010 only - P-029: fix broken 007 companion reference (docs/reflect.md -> docs/agent-memory-layer.md), align 'reflect' vocabulary with the landed design, refresh stale proposal counts - P-030: replace the pytest-based sketch with a stdlib runner matching the zero-dependency suite; make the synthesized OwnLang wrapper actually parse per ownlang/parser.py grammar - P-032/P-033: fence all code blocks, promote plain-text section titles to headings, backtick quoted identifiers; P-033 reframed to target the audited legacy app, not the analyzer (source: own.diagnostics.sketches) - agentic-coding-discipline: soften 'o7 run works' to match 007 TODO.md (scaffolded, not yet exercised); add part-2 divider heading - agent-capability-layer §8: Sandboy consumes rendered TOML (not JSON); sandboy status corrected Built -> Spiked (authored, not compiled) - sandboy/README: replace live 007 blob URL with plain cross-repo path; gate steps described as bare bash (bypassPermissions applies to the agent phase) - ROADMAP: index rows for all new proposals P-026..P-033
1 parent ce9eab9 commit a5c0c97

10 files changed

Lines changed: 157 additions & 87 deletions

‎docs/ROADMAP.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -326,5 +326,11 @@ own scan. Label them as estimates wherever they appear.
326326
| [P-020](proposals/P-020-ownts-react-effects.md) | OwnTS React effects profile (`Own.React`) — effect-storm angle | horizon | draft |
327327
| [P-021](proposals/P-021-async-audit-pack.md) | Async audit pack (`Own.Async`) — safety-first WPF/application async lifecycle diagnostics | P2 | draft |
328328
| [P-025](proposals/P-025-obligation-protocols.md) | Obligation protocols (`Own.Protocols`) — barrier-sensitive project invariants (OBL001–005) | P1 | first slice built (core + bridge + fixtures; extractor pending) |
329+
| [P-026](proposals/P-026-csharp-strictness-retrofit.md) | C# strictness retrofit profile (`own audit strictness`) — witness/score over existing findings | P2 | draft (framing) |
329330
| [P-027](proposals/P-027-resource-state-machine.md) | Resource state machines & stale-async-write detection (extends `Own.Async`) | P2 | draft |
330331
| [P-028](proposals/P-028-unneeded-dependency-profile.md) | Unneeded-dependency profile (`Own.Lean`) — evidence-only "you don't need this abstraction" findings (YDN001–002) | P2 | draft |
332+
| [P-029](proposals/P-029-agent-memory-layer.md) | Agent memory & policy layer (`.agents/`) — reviewed destination for AGENTS.md and learned-rule promotions | enabling | draft |
333+
| [P-030](proposals/P-030-naughty-strings-testing.md) | Naughty-strings robustness pack (BLNS crash-testing of lexer/parser/serializers/CLI) | enabling | draft |
334+
| [P-031](proposals/P-031-resource-model-files.md) | Project resource model files (`own.models.yaml`) — declarative acquire/release/capture | P2 | draft |
335+
| [P-032](proposals/P-032-own-arch-facts.md) | Own.Arch facts & intent model — deterministic architecture-fact core (deepens P-023) | P2 | draft |
336+
| [P-033](proposals/P-033-probabilistic-data-structures.md) | In-process sketches & bitmap indexes for audited legacy apps | horizon | draft |

‎docs/agentic-coding-discipline-proposal.md‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,9 @@
99
## Что из этого уже реализовано/задокументировано
1010

1111
- **007** (`README.md`, `TODO.md`) — цикл `isolate → run → gate → harvest` уже
12-
работает: `o7 run` делает git worktree, гоняет `claude` full-auto, прогоняет
12+
реализован (`o7 run` — scaffolded, ещё не прогнан на реальной coding-задаче;
13+
`o7 judge` — verified working): `o7 run` делает git worktree, гоняет `claude`
14+
full-auto, прогоняет
1315
`.007/gate.toml`, собирает `task.md / meta.json / agent.stdout / diff.patch /
1416
gate/*.log` (`src/agent.rs`, `gate.rs`, `worktree.rs`, `record.rs`,
1517
`verdict.rs`).
@@ -487,6 +489,8 @@ task contract → isolated run → gates → harvest → judge/review → verdic
487489

488490
---
489491

492+
## Часть 2 — применение к 007
493+
490494
### 1. Для 007 нужен не "prompt template", а Task Contract
491495

492496
В Own.NET можно было держать `.ai/task-template.md`.
@@ -760,7 +764,7 @@ judge возвращает machine-readable verdict
760764
без замка.
761765
```
762766

763-
Практический вывод
767+
#### Практический вывод
764768

765769
В 007 надо добавить `trust_level`:
766770

@@ -1020,7 +1024,7 @@ examples/policy.safe-defaults.toml
10201024

10211025
Это даст 007 реальную ценность как harness, а не просто runner.
10221026

1023-
MVP формата
1027+
#### MVP формата
10241028

10251029
```toml
10261030
version = 1

‎docs/notes/agent-capability-layer.md‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -112,7 +112,7 @@ syscall/reachable-binary level. Two different enforcement models — don't confl
112112
| Phase | What | Verdict |
113113
|---|---|---|
114114
| **1. Policy engine** | `owen-policy`: parse `owen.policy.toml`, `policy check/explain`, `gen-ignore` | **Do.** Daily use, zero risk, not built. 80% of daily value. |
115-
| **2. Runner enforcement** | wrap agent in worktree + Sandboy | **Built** (`sandboy/`). Wire to a real gate step. |
115+
| **2. Runner enforcement** | wrap agent in worktree + Sandboy | **Spiked** (`sandboy/` — authored, not yet compiled; acceptance gate: `cargo build` + `tests/demo.sh`, see `sandboy/README.md`). Wire to a real gate step. |
116116
| **3. WIT tool components** | move tools to capability-scoped components | **Selective.** WIT only where input/author is untrusted: `secret-scanner`, `patch-analyzer`, `verifier-adapter` (parse untrusted output) — yes. `memory-search` over **your own** data — plain code, WIT buys nothing. |
117117
| **4. MCP/WIT bridge** | `owen-mcp` tools backed by policy + components | Thin, later. |
118118

@@ -139,7 +139,7 @@ syscall/reachable-binary level. Two different enforcement models — don't confl
139139
canonical policy owen.policy.toml (Phase 1 — build)
140140
context hygiene generated ignore + filtered packs (hygiene, NOT security)
141141
tool isolation WIT + Wasmtime (own-adapter-host+) (Phase 3 — selective)
142-
native isolation worktree + Sandboy (built: sandboy/)
142+
native isolation worktree + Sandboy (spiked: sandboy/)
143143
agent integration mode (B): agent-with-shell in the (Sandboy is the cage,
144144
Sandboy cage, Owen tools on top WIT tools are contracts)
145145
memory / verifier only through policy-mediated ifaces
@@ -196,8 +196,10 @@ gates/
196196
# denylist that silently forgot it
197197
```
198198

199-
Compiled down to flat JSON for whatever actually enforces it at runtime (the
200-
Sandboy policy, `owen policy check`'s consumer) — the authoring layer is for
199+
Compiled down to flat artifacts for whatever actually enforces it at runtime —
200+
rendered TOML for the per-step Sandboy policy (`cue export --out toml`, see
201+
`sandboy/README.md`), flat JSON for the gate manifest / `owen policy check`
202+
consumer — the authoring layer is for
201203
humans; the enforcement point should stay a boring, strict parser with no CUE
202204
evaluation at run time.
203205

‎docs/proposals/P-010-type-disciplines.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -228,7 +228,8 @@ payoff of doing this pillar at all is *unification*: one mental model
228228

229229
17. **Generated docs.** Render the `.own` declarations (brand / refinement /
230230
union / protocol) into human-readable reference pages, the same way
231-
`spec/Diagnostics.md` is the single source of truth for `OWN` codes today —
231+
`ownlang/diagnostics.py` (`TITLES`) is the single source of truth for `OWN`
232+
codes today, with `spec/Diagnostics.md` as its human-readable grouping —
232233
one declaration, read by the compiler *and* the wiki, so the contract and
233234
its documentation cannot drift apart.
234235

‎docs/proposals/P-027-resource-state-machine.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -176,7 +176,7 @@ correctly.
176176
an `await`, writes after it, with no visible guard" — a syntactic pattern, not
177177
a soundness proof.
178178
- **No shipped runtime type.** Own.NET does not ship a `ResourceState<T>`
179-
NuGet package as the mandated fix, matching P-008/P-010's existing rule that
179+
NuGet package as the mandated fix, matching P-010's existing rule that
180180
brands/refinements/protocols lower to plain structs the *team* owns. The
181181
diagnostic explains the pattern; teams write their own status type (or adopt
182182
whichever shape fits their codebase).
@@ -202,8 +202,8 @@ Python core emits verdicts:
202202
```
203203

204204
`ASYNC051`/`ASYNC052` are per-method and most likely land as two more hazard
205-
kinds in P-021's existing `async_methods` fact family
206-
(`ownlang/async_rules.py`). `ASYNC050` is type-scoped — a cluster of fields
205+
kinds in the `async_methods` fact family P-021 plans (its proposed
206+
`ownlang/async_rules.py` module). `ASYNC050` is type-scoped — a cluster of fields
207207
assigned together across the whole class, not one method — so it needs its own
208208
type-level fact rather than living inside a method entry:
209209

@@ -247,8 +247,8 @@ contracts separate.
247247
2. **Threshold for state soup.** Two co-varying fields (`HasValue`/`Value`) are
248248
completely ordinary and shouldn't fire. Where's the real line — 3 fields? A
249249
specific combination like `bool + bool + nullable`? This needs corpus
250-
evidence (P-012) rather than a guessed constant, same as P-021's own open
251-
question 2 about severity thresholds.
250+
evidence (P-012) rather than a guessed constant, in the same evidence-first
251+
spirit as P-021.
252252
3. **Staleness-check feasibility.** Proving "the gating field was re-read or a
253253
version was compared between the pre-await read and the post-await write"
254254
needs more than single-method syntax — it's adjacent to P-016's deep fact

‎docs/proposals/P-029-agent-memory-layer.md‎

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,8 @@
44
proposal.
55
- **Depends on:** nothing structurally; it formalizes conventions already used
66
elsewhere in this repo (see Sketch). Consumed by, but does not depend on, the
7-
reflect/learning-engine design in the sibling private repo `PhysShell/007`
8-
(`docs/reflect.md` there) — that engine is one possible *source* of
7+
agent-memory-layer design in the sibling private repo `PhysShell/007`
8+
(`docs/agent-memory-layer.md` there) — that memory layer is one possible *source* of
99
promotions into the layer this proposal defines; a human editing `AGENTS.md`
1010
by hand is another, equally valid, source.
1111

@@ -15,7 +15,7 @@
1515
gate, the pipeline shape, and a handful of hard rules (unknown-call handling,
1616
`assert_never` dispatch sites, codegen modes, OwnIR versioning). That is
1717
exactly the right size for what it covers today. The risk is what happens as
18-
it grows: this repo already carries 25 proposals and 30+ design notes under
18+
it grows: this repo already carries 30+ proposals and 30+ design notes under
1919
`docs/`, plus a second, much longer file
2020
(`AGENTS.execution-surfaces.md`, 14KB) for a single ADR. Two failure modes are
2121
already visible in miniature:
@@ -36,10 +36,10 @@ from the outside — see `007`'s own `README.md`) both converge on the same
3636
idea: corrections and repeat-failure patterns from real agent runs should
3737
become reviewed, persistent project memory rather than being re-learned every
3838
session. `007` is explicitly the place that *mines* run records for candidate
39-
learnings (`docs/reflect.md` in that repo) — it is private, and its own
40-
`README.md` is explicit that harness-internal reasoning must never land in a
41-
public tree. What this repo needs, independent of whether 007 ever ships that
42-
engine, is: **a defined, reviewed, structured place those promotions — or a
39+
learnings (`docs/agent-memory-layer.md` in that repo) — it is private, and its own
40+
`README.md` is explicit that the harness must stay private (its auth/agent-
41+
routing internals must not land in a public tree). What this repo needs,
42+
independent of whether 007 ever ships that engine, is: **a defined, reviewed, structured place those promotions — or a
4343
human's own manual corrections — land in.** That is this proposal's entire
4444
scope: the destination shape, not a detector.
4545

@@ -68,7 +68,7 @@ already relies on to agent guidance specifically, instead of one growing file.
6868
Each `.agents/*.md` file gets a soft line budget (~150 lines, the same
6969
heuristic `claude-reflect` uses to warn on oversized memory files). Once a
7070
file would cross that budget, it splits — same discipline that already
71-
produced 25 separate proposals instead of one `PROPOSALS.md`.
71+
produced 30+ separate proposals instead of one `PROPOSALS.md`.
7272

7373
### `.007/gate.toml`
7474

@@ -104,8 +104,8 @@ open question on generation below.
104104
### The promotion contract
105105

106106
Whatever proposes a change to `.agents/*.md` — a human noticing a repeat
107-
correction, or an accepted candidate out of `007`'s (separate, private)
108-
reflect queue — must arrive as an ordinary reviewed PR carrying:
107+
correction, or a human-confirmed memory entry promoted out of `007`'s (separate,
108+
private) memory layer — must arrive as an ordinary reviewed PR carrying:
109109

110110
- **the rule itself**, scoped to one `.agents/*.md` file and section;
111111
- **provenance**: what motivated it (a run, a PR comment, a postmortem) —
@@ -185,7 +185,7 @@ Guidance for agents working in this repo. Start here, then follow a link:
185185
checked in CI so drift fails loudly rather than rotting silently.
186186
2. **Does the promotion contract need its own proposal**, or does it stay a
187187
section of this one? Leaning: stays here until there's a second consumer
188-
besides `007`'s reflect design — one contract, one place, until proven
188+
besides `007`'s memory-layer design — one contract, one place, until proven
189189
otherwise.
190190
3. **Should `.cursor/rules/` and `.roo/rules-*/` eventually generate from
191191
`.agents/`** instead of maintaining separate tool-specific prose? Not in
@@ -198,7 +198,7 @@ Guidance for agents working in this repo. Start here, then follow a link:
198198
lines" heuristic)? Leaning: start as a soft PR-review convention; only add
199199
a mechanical gate if bloat actually recurs — no gate for a problem that
200200
hasn't happened yet.
201-
5. **Timing relative to `007`'s reflect engine:** this proposal's directory
201+
5. **Timing relative to `007`'s memory layer:** this proposal's directory
202202
layout is useful on its own (splitting an already-growing `AGENTS.md`)
203203
regardless of whether `007`'s mining engine ever ships. It should not block
204204
on that design landing first.

‎docs/proposals/P-030-naughty-strings-testing.md‎

Lines changed: 24 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ way instead of by test.
4646
line-ending oddities, format-breakers for JSON/XML/CSV/SQL/shell), shipped as a
4747
plain `blns.json` array plus a `.NET` port (`NaughtyStrings` NuGet package) for
4848
the C#-side pieces (`audit/`'s eventual C# on lift-out, per
49-
[`OwnAudit/README.md`](https://github.com/PhysShell/OwnAudit)). BLNS itself is
49+
[`OwnAudit/README.md`](https://github.com/PhysShell/OwnAudit/blob/main/README.md)). BLNS itself is
5050
explicit that it is not a substitute for real security testing (see
5151
Non-goals) — its contract here is narrower and cheaper: **the tool must not
5252
crash, hang, or corrupt output on any string in the corpus.**
@@ -132,21 +132,36 @@ tests/test_naughty_strings.py # parametrized over every entry, 3 layers abov
132132
```
133133

134134
```python
135-
import json, os, pytest
135+
import json, os
136136
from ownlang.lexer import LexError
137137
from ownlang.parser import ParseError, parse
138138

139139
with open(os.path.join(os.path.dirname(__file__), "fixtures", "blns.json"),
140140
encoding="utf-8") as f:
141141
BLNS = json.load(f)
142142

143-
@pytest.mark.parametrize("naughty", BLNS)
144-
def test_parser_does_not_crash(naughty):
145-
src = f'resource R;\nfn f() {{ let s = "{naughty}"; }}\n'
146-
try:
147-
parse(src)
148-
except (ParseError, LexError):
149-
pass # an honest rejection is fine; anything else is a bug
143+
144+
def run() -> int:
145+
"""One case per BLNS entry, in the suite's zero-dependency style: no
146+
pytest — tests/run_tests.py auto-discovers every test_*.py that exposes
147+
a run() -> int, same as tests/test_corpus.py."""
148+
fails: list[str] = []
149+
for naughty in BLNS:
150+
# Embed the entry in a grammatically legal STRING position: per
151+
# ownlang/parser.py's grammar, string literals appear only in
152+
# resource emit_*/kind members (a `let` rhs never takes a string),
153+
# so a benign entry parses cleanly and only the naughty content is
154+
# under test — the wrapper follows the run_tests.py PRELUDE shape.
155+
src = f'module M\nresource R {{ acquire a release r emit_type "{naughty}" }}\n'
156+
try:
157+
parse(src)
158+
except (ParseError, LexError):
159+
pass # an honest rejection is fine; anything else is a bug
160+
except Exception as e:
161+
fails.append(f"{naughty!r}: {type(e).__name__}: {e}")
162+
for f in fails:
163+
print(f"NAUGHTY FAIL: {f}")
164+
return 1 if fails else 0
150165
```
151166

152167
Serialization side follows the same shape against `diag_sarif.py` /

0 commit comments

Comments
 (0)